sdk_core

Manage, display, and create your custom advertisements on Android using cutting-edge technologies such as Coroutines, and Jetpack Compose based.

Note

To use the ADITION AdSDK the application developer will need to acquire the AdSDK library as well as networkId and contentId pairs from an ADITION customer.

Getting started

To serve advertisements using the Adition AdSDK you will typically:

• Add the package dependencies

• Initialize and configure the AdService

• Register Ad Renderers

• Request Ads

• Observe AdState

Apps using this AdSDK must be built at least for Android SDK Level 24.

Important Classes & Functions

When dealing with Ads you will interact with the following classes:

• AdService - for cookie handling, configuring and management of the cache. You create and use this as a singleton.

• Advertisement - represents an advertisement with methods for loading the Ad content.

These classes allow the configuration and loading of ads independent from any display technology. If your app is using Jetpack Compose, then use the sdk_presentation_compose package which will help you display ads in your apps that use Jetpack Compose.

You can see an example of using the SDK with Jetpack Compose in the 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 must pass certain information. The first argument you will pass when creating an AdService is the networkId.

When creating an Advertisement, you can pass additional information through the constructor:

• contentId or learningTag (required)

• adTypes (required)

• timeoutAfterSeconds (optional)

• profiles (optional)

• keywords (optional)

• wi (optional)

• gdprPd (optional)

• serverSideHeaderBidding (optional)

• campaignId (optional)

• bannerId (optional)

• dsa (optional)

• placementType (optional)

• targetURLHandler (optional)

Some parameters of Advertisement 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:

• gdpr

• externalUID

• isOptOutEnabled

• userIds

• isSHBEnabled

• dsa

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 object of TargetURLHandlerInterface to the Advertisement constructor.

Events

Advertisements will emit two types of events:

• Lifecycle events:

• Loading

• Caching

• AdReadyToDisplay

• Error

• Tracking events:

• Tap

• Impression

• Viewable

• CustomRendererEvent

Some tracking events should be enabled in the Adition Backend. An example of how to monitor these events can be found in the tutorial documentationhttps://vm-mobile-sdk.github.io/nextgen-adsdk-android-release/4.6.0/handling-the-state-and-events-of-advertising.html).

SDK Errors

If an error prevents an advertisement from being delivered or rendered, the advertisement's AdState will be AdException. It contains two properties: adError and an exception.

• AdException

• The adError is an constant of the type ErrorCode.

• AdError is the object which contains the different custom SDK ErrorCode types.

• The exception is an optional Android/Kotlin exception.

You can see all possible types of errors that the SDK can return in the AdError documentation.

You have to decide how to handle errors within your App. For example, you could re-try requesting an Ad or fail silently and hide the ad space. Here an example how you could check for these errors:

is AdState.State.Error -> {
    var adException = state.adException
    var adError = adException.adError

    when(adError) {
        AdError.DECODING -> // ...
        AdError.TIMED_OUT -> // ...
        AdError.DEFAULT -> // ...
        else -> // ...
    }
}

Handling inApp-ClickURL

inApp-ClickURLs is a feature which allows you to specify a custom schemed click url. An example of a custom scheme url is `myschema://coupons`. Banners with this option selected will not open a browser when it is clicked. It will attempt to fire an intent which has been registered to handle the custom schemed click url.

The ADITION click counting works by initially calling the adserver url which will then count the click and redirect to the banner click url. By default this is done by the built-in ADITION browser. 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.

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 object of TargetURLHandlerInterface to the Advertisement constructor.

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 adserving platform.

See TagRequest. This class uses as a parameter the AdService.tagUser method. You can pass all tags as a list.

Tracking request

Tracking is a server side feature. You are able to perform tracking request to track your conversions.

See TrackRequest. The app can fire the track request as soon as a conversion occurs within the app. See AdService.trackUser.

Tagging and Track request global paramaters

TagRequest and TrackRequest 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:

• gdpr

• externalUID

• isOptOutEnabled

• userIds

Manual tap event triggering

There is function called Advertisement.triggerAdClick, responsible for performing tap event. This function use for app developer when they need to call tap event manually.

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 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 prepare method of the AdRenderer interface. This method will be called every time Advertisement manages to load advertisement data. In it you can process the data, and prepare the renderer for display. Also, you need to override the RenderAd composable function with your the presentation logic.

3. Communication

For the communication with the AdSDK you need to use the AdStateInterface from prepare method.

The main part is changing the state of the renderer. You can change the state depending on your current lifecycle by changing the state property.

Also, there are some methods to interact with the AdSDK via AdStateInterface:

• triggerAdClick

• triggerCustomEvent

• updateAdData

4. Renderer Registry

To make the SDK aware of your ad, you need to register it with the SDK using AdComposeRenderRegistry. 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 controller and view classes in case actual ad content is delivered by the ad server.

You can see a simple example of creating a renderer in the AdRenderer documentation.