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.
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.
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>
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.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.
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 as been replaced by the much more compact
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();