ad_sdk
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.
Requirements
Apps using AdSDK must be built at least for Android SDK Level 24.
Permissions Required
This library requires the following permissions to function correctly:
INTERNET– to access the network.ACCESS_NETWORK_STATE– to check network connectivity status (if applicable).
Make sure to include the following permissions in your app's AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>Overview
To serve advertisements using the Adition AdSDK you will typically:
Add the package dependencies.
Create AdServiceProvider.
Create and configure the AdService via AdServiceProvider.configure method.
Obtain AdService using the AdServiceProvider.get method.
Request the creation of an Advertisement from AdService passing AdRequest via AdService.makeAdvertisement.
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:
AdServiceProvider – provider for creating and configuring AdService that can be used in DI containers.
AdServiceProvider.configure – includes creating and configuring the AdService, setting global requests parameters, registering native renderers, and setting the cache size.
AdServiceProvider.get – method for getting a configured AdService.
AdService – core SDK's interface.
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 – 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 via AdServiceProvider.configure is the AdService.networkId.
Consent Management
An app can ask users about their consent for sharing information with third parties. The SDK can forward users preferences automatically if they follow the TCF v2 format. To control the observation of such changes, you should pass parentCoroutineScope to method AdServiceProvider.configure, which should be cancelled at the same time as AdService is destroyed.
If your application does not use CMP, or your CMP does not follow the TCF v2, you can transfer these parameters manually using the globalParameters in the AdServiceProvider.configure method. See more about GlobalParameters and AdRequestGlobalParameters in #requests-global-parameters.
Advertisement Request
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)
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
You can build retargeting segments by exposing a user in your application to tagging requests. Segments can be used in Adition campaign targeting.
See TagRequest. This class uses as a parameter the AdService.tagUser method. You can pass all tags through the constructor.
Tracking Request
You can use tracking requests to track your app users conversions.
See TrackingRequest. The app can fire the track request as soon as a conversion occurs within the app via AdService.trackingRequest method.
Requests Global Parameters
Some parameters of AdRequest, TagRequest and TrackingRequest are designed to be passed in all requests, not just individual ones. To avoid duplicating code when creating requests you can pass all parameters via AdServiceProvider.configure using the globalParameters parameter, and change them later using AdService.setGlobalParameters and AdService.removeGlobalParameter.
GlobalParameters.gdpr (Can be set automatically if the app uses a CMP that follows TCF v2 format)
In addition to GlobalParameters, AdRequest also has its own unique AdRequestGlobalParameters that will be used each time AdRequest is executed. You can pass all parameters via AdServiceProvider.configure using the adRequestGlobalParameters parameter, and change them later using AdService.setAdRequestGlobalParameters and AdService.removeAdRequestGlobalParameter.
Learn more about GlobalParameters and 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.
The renderers can get a cache object via the AdRenderer.ServiceLocator. In turn, the application can control the cache using AdService.
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 AssetCache 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:
AdTapEvent via AdEventListener.tapEventProcessed and AdEventListener.tapEventProcessingFailed methods.
Custom tracking events in case of using custom advertising via AdEventListener.customTrackingEventProcessed and AdEventListener.customTrackingEventProcessingFailed methods.
Custom message from the advert via AdEventListener.rendererMessageReceived method.
Request to unload advertising via AdEventListener.unloadRequest method.
AdTrackingEvent via AdEventListener.trackingEventProcessed and AdEventListener.trackingEventProcessingFailed methods.
Note: Which tracking events are enabled for which advertisement is configured in the Adition Backend.
To gain a more detailed understanding of how to work with the AdEventListener, 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 AdTapEvent. This method use for app developer when they need to call tap event manually.
Advertisement Life Cycle Control
Since the object of Advertisement is not a lifecycle-aware component, the application developer should control the lifecycle from within the application in order to avoid leaks.
To clean up and cancel all internal tasks, the application developer should call the Advertisement.dispose method before removing the reference to the object.
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 AdRenderer interface. Your renderer class needs to implement the configure 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.
Optionally, you can implement an prepareForReload method that will be called each time before Advertisement is reloaded.
To clean up your renderer before disposing of it, you can implement the dispose method.
The last step will be overriding the AdRenderer.RenderAd composable method with your 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. In the factory method, you can use AdRenderer.ServiceLocator as a service locator or DI container when creating your renderer object. 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.