sdk_core
Manage, display, and create your custom advertisements on Android using cutting-edge technologies such as Coroutines, and Jetpack Compose.
Note
To use the Adition AdSDK the application developer will need to acquire the AdSDK library as well as networkId and contentUnit or learningTag pairs from an Adition.
If your experience "cannot load page" errors when navigating between entries in this documentation, then the culprit is very likely an activated ad blocker. Many of the documented classes and services have names related to advertising terms. We found that this can trigger ad blockers. So please disable your adblocker if you have issues.
Overview
To serve advertisements using the Adition AdSDK you will typically:
Add the package dependencies.
Configure the AdService via AdService.configure method.
Request the creation of an Advertisement from AdService passing AdRequest.
Apps using this AdSDK must be built at least for Android SDK Level 24.
You can follow the AdSDK integration tutorial documentation with code examples where you will create your first application using the AdSDK.
Important Classes & Functions
When dealing with Ads you will interact with the following API:
AdService – core SDK's interface. You use it as a singleton.
AdService.configure – includes configuring the AdService, registering native renderers, and setting the cache size and path.
AdService.setAdRequestGlobalParameter – setting global parameters that will apply to each AdRequest.
AdService.makeAdvertisement – creating an Advertisement object with inline or interstitial placement type and initiating a request to the ad server.
Advertisement – represents an advertisement.
Ad – while Advertisement represents the content of an advertisement, Ad is the element for displaying AdPlacementType.INLINE ad on a view hierarchy.
Interstitial – while Advertisement represents the content of an advertisement, Interstitial is the element for displaying AdPlacementType.INTERSTITIAL ad as a full screen cover.
AdResult – a wrapper class that represents either a success or a failure that contains AdError.
If you are creating a custom ad, you will also use:
AdRenderer&AdComposeRenderer – interface of the future presentation layer of the ad.
AdService.registerRenderer – registers your custom ad in the SDK.
To gain a more detailed understanding of how to work with these objects and how they are related, we recommend going through our tutorial documentation.
Explaining the Concepts of AdSDK Server Requests
Your app uses the AdSDK to request ads from an ad server.
To enable the ad server to serve relevant ads, you should pass certain information. The first argument you will pass when configuring an AdService is the AdService.networkId.
When creating an Advertisement, you can pass additional information and interfaces through the AdService.makeAdvertisement method:
AdRequest (required)
AdRequest.contentUnit or AdRequest.learningTag (required)
AdRequest.profiles (optional)
AdRequest.keywords (optional)
AdRequest.window (optional)
AdRequest.timeoutAfterSeconds (optional)
AdRequest.gdprPd (optional)
AdRequest.campaignId (optional)
AdRequest.bannerId (optional)
AdRequest.isSHBEnabled (optional)
AdRequest.dsa (optional)
AdPlacementType (required)
AdEventListener (optional)
TargetURLHandler (optional)
Some parameters of AdRequest are designed to be passed in all requests, not just individual ones. To avoid duplicating code, SDK provide AdService.setAdRequestGlobalParameter and AdService.removeAdRequestGlobalParameter methods, which will modify these optional parameters:
Learn more about AdRequestGlobalParameters in our tutorial documentation.
Asset Caching
The SDK has a built-in FIFO persistent cache that caches all possible advertising resources, such as banners on the device.
Both the application and renderers can get a cache object using the AdService.getCacheInstance method. You can set the initial path for the cache to work with AdService.configure or change it over time with AdService.setCachePath.
The built-in cache limit is 100 MB, but you can set another size when configuring an AdService, or change it over time using AdService.setCacheSize. You can also clear the cache with AdService.flushCache.
Learn more about DriveCache in our tutorial documentation.
Controlling Advertisement's Events
Advertisement can be configured to send certain tracking events to the ad server or to pass information to the app. To monitor these events, you can pass the AdEventListener to the AdService.makeAdvertisement method.
With the help of this interface, you will be able to monitor:
Tracking events:
Note: Which tracking events are enabled for which advertisement is configured in the Adition Backend.
User interaction events:
Custom renderer events:
To gain a more detailed understanding of how to work with the AdEventListener and AdEventType, we recommend going through our tutorial documentation.
Advertisement Tap Handling
Target URL Handling
We call the target URL the URL that should be shown to the user as a result of tapping on the ad.
By default, the SDK opens an external browser when processing a target URL. You can override this behaviour with your own. For example, this can be useful if you want to open your internal browser in your application to process the target URL. To do this, you pass the TargetURLHandler to the AdService.makeAdvertisement method.
Learn more in our tutorial documentation.
Handling inApp-ClickURL
inApp-ClickURLs is a feature which allows you to specify a custom schemed tap url. An example of a custom scheme url is `myschema://coupons`. Banners with this option selected will not open a browser when it is tapped. It will attempt to fire an intent which has been registered to handle the custom schemed tap url.
The Adition click counting works by initially calling the ad server url which will then count the click and redirect to the banner click url. The exception to this default click handling is with inApp-ClickURL banners, as they are handled by the SDK internally which ensures the click is successfully counted and the intent fired.
It is important that the app has registered intent-filters for the banner being delivered otherwise the fired intent will be silently ignored. It is possible to have multiple http-schema redirects with this option activated, but they will be silently requested and ignored if they don't end up redirecting to a custom schema. Using common schemas like http will result in a dialog popup which will request the user to select the (default) app to handle the intent.
Manual Tap Event Triggering
There is method called Advertisement.performTapEvent, responsible for performing AdEventType.Tap. This method use for app developer when they need to call tap event manually.
User Tagging and Conversion Tracking Features
AdSDK provides powerful functionality for user tagging and conversion tracking. You can find an example of the implementation in our tutorial documentation.
Tagging Request
Tagging targeting is a server side tagging (user profile) feature. You are able to tag a user currently using your application with key = value tags that can be used in targeting of campaigns within the Adition ad serving platform.
See TagRequest. This class uses as a parameter the AdService.tagUser method. You can pass all tags through the constructor.
Tracking Request
Tracking is a server side feature. You are able to perform tracking request to track your conversions.
See TrackingRequest. The app can fire the track request as soon as a conversion occurs within the app via AdService.trackingRequest method.
Global Parameters
TagRequest and TrackingRequest has ability to set global parameter, which are designed to be passed in all requests, not just individual ones. To avoid duplicating code, SDK provide AdService.setTrackingGlobalParameter and AdService.removeTrackingGlobalParameter methods, which will modify these optional parameters:
Learn more about TrackingGlobalParameters in our tutorial documentation.
Creating Custom Native Ads
As App developer, you can create your own custom ad formats. For example, you can implement interactive ad formats like surveys, rotating galleries or Ads that play video.
1. Server Side
Your custom ad format can be configured in the Adition backend. There you can define a creative template with custom JSON that will be delivered as part of the ad. For example, you could provide a way to configure some styling aspects for the ad by adding custom JSON key-value-pairs to the creative template.
2. Renderer
On the app side, you can implement your custom Ad with native technologies like Kotlin and Jetpack Compose. As part of your custom ad you will need to create a renderer class which implements the AdComposeRenderer interface. Your renderer class needs to implement the AdRenderer method. This method will be called every time Advertisement manages to load or reload advertisement data. In it you can process the data, and prepare the renderer for display. The last step will be overriding the AdComposeRenderer.RenderAd composable method with your the presentation logic.
3.Communication
Also, there are some methods to interact with the AdSDK and App via AdRendererEventHandler:
4. Renderer Registry
To make the SDK aware of your ad, you need to register it with the SDK using AdService.registerRenderer. Once your custom ad is registered, the SDK will signal the Adition ad server that it can handle this new ad format for subsequent ad request. The SDK will also manage the creation of the instances of your renderer classes in case actual ad content is delivered by the ad server.