Overview

Version 4.0 of the Android XAPPmedia SDK was built on the idea to make the SDK easier to implement by removing or automating a lot of what it took to get from start to finish. As a result, the public API took quite a big overhaul. The goal of this guide is to ease the transition from 3.11.x to 4.x.

Manifest Setup

XappService

One extra step for 4.x is the xappmedia.sdk.XappService needs to be declared in the AndroidManifest.xml like so:

<application>
  <service android:name="xappmedia.sdk.XappService"/>
</application>

This is required.

XappInterstitialActivity

If you play ads as interstitials, then replace the older xappmedia.sdk.PlayAdActivity with the new xappmedia.sdk.XappInterstitialActivity. It is an AppCompatActivity so it is compatible with devices as low as Android 2.1 however this also means it requires an AppCompat theme.

<application>
  <activity android:name="xappmedia.sdk.XappInterstitialActivity"
                  android:theme="@style/Theme.AppCompat.NoActionBar"/>
</application>

Credentials

Originally in 3.11.x, the API and APP keys were supplied via XappAds.start(). In 4.0, it is no longer necessary keep or store the API and APP keys inside the Java code. Instead these are supplied in the app’s AndroidManifest.xml file as <meta-data> tags with the names xapp.sdk.ApiKey and xapp.sdk.AppKey. For example:

 <application>
        <meta-data
            android:name="xapp.sdk.ApiKey" android:value="<!-- your app's API key -->"/>

        <meta-data
            android:name="xapp.sdk.AppKey" android:value="<!-- your app's APP key -->"/>
  </application>

Alternatively, this can be supplied by the new Config class that is passed in when retrieving the Xapp singleton. For example:

String apiKey = methodToGetApiKey();
String appKey = methodToGetAppKey();
   
Config xappConfig = new Config();
xappConfig.apiKey(apiKey);
xappConfig.appKey(appKey);
   
Xapp xapp = Xapp.from(context, xappConfig);

This may be useful if the API and APP keys are stored on a server or otherwise can not be accessed at compile time.

Side note: The method Xapp#from(Context context) returns a singleton of the configured Xapp object, so you only need to configure it when there are changes to the configuration.

Session Lifecycle

In 3.11.x, a session was started by the very verbose method:

XappAds.start(String apiKey, String appKey, UserData userData, Location location, Context context, XappAdsListener listener)

Then the also verbose XappAdsListener was required to know when a session was started or failed.

In 4.x, sessions no longer exist. So feel free to skip this part and go right on to requesting. Likewise, since there are no sessions, there are no sessions to terminate.

XappAdsListener

The 3.11.x XappAdsListener as been replaced by the much more compact PlayListener and LoadCallback.

The optional LoadCallback is intended for request events and there are two methods: LoadCallback#onLoad(Advertisement ad) and LoadCallback#onError(Throwable t). The onLoad() method is equivalent to the old method XappAdsListener#onAdRequestCompleted (Advertisement ad). The onError() method is equivalent to the old method XappAdsListener#onAdRequestFailed(AdRequest adRequest, Error error).

The optional PlayListener is intended for playback events. The method PlayListener#onFinish(Advertisement ad, AdResult result) is the replacement for the old method XappAdsListener#onAdCompleted(AdResult adResult). This method is called when the XappAdController is shutting down. The Advertisement parameter can be null if there is an error in retrieving the ad. The AdResult is always not null and can be used with custom actions that were interacted with during playback.

Requesting and Playing an Ad

In 3.11.x, requesting required waiting on the session to start. Then once it started, you would call XappAds.requestAd(AdRequest request) to retrieve them. Then you were required to wait for it to download before calling one of the XappAds.playAs_______ methods to actually play it.

In 4.x, all of this is handled internally. So now, requesting and playing an ad can be as simple as this:

Xapp.from(context)
  .xappAds()
  .newRequest()
  .loadAd(loadCallback)
  .start();

Broken down, this will build a request, download an ad, then start it as soon as it is ready. The provided LoadCallback will be helpful in determining if the request fails.

Though most of the time it may be best to preload the ad. For this, the reference to the returned XappAdsController needs to be kept. XappAdsController#start() can be called when it is time to actually play. For example:

  XappAdsController controller = Xapp.from(context)
                                      .xappAds()
                                      .newRequest()
                                      .loadAd(loadCallback);
  controller.setPlayListener(playListener);

  // Some time in the future
  controller.start();