Adding XappAds to your Project

Maven and Gradle

In your build.gradle, add the link to our maven repository and add XappAds as a dependency:

repositories {
    mavenCentral()
    maven { url "https://repo.xappmedia.com/nexus/content/groups/xapp-android/" }
}

dependencies {
    compile ('com.xappmedia:xapp-ads:3.11.6@aar') {
     transitive = true
    }
}

Alternate Methods

If you use another method to import dependencies, let us know as we would like to support it.

AndroidManifest.xml Modifications

Permissions

Add the following permissions, typically right before the <Application> tag:

<!--//BLUETOOTH - Necessary for reporting users audioroute.-->
<uses-permission android:name="android.permission.BLUETOOTH" />
<!--//ACCESS_NETWORK_STATE - Necessary for network optimization and diagnostics.-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!--//INTERNET - Necessary for HTTP access-->
<uses-permission android:name="android.permission.INTERNET" />
<!--//RECORD_AUDIO - Necessary for performing voice recognition-->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<!-- Optional -->
<!--//CALL_PHONE - Necessary to enable "Call Now" actions-->
<!--<uses-permission android:name="android.permission.CALL_PHONE" /> -->

Activities

Add the following two lines to your AndroidManifest.xml within the <Application> tag:

// allows us to launch the activity for a full screen interstitial.
<activity android:name="xappmedia.sdk.PlayAdActivity"
          android:screenOrientation="portrait"></activity>
// allows us to launch an in-app browser to handle touched ads, and certain ad actions.
<activity android:name="xappmedia.sdk.inappbrowser.WebViewActivity"></activity>

Basic Usage

Implement the XappAdsListener

Add import statements, implements XappAdsListener after your class name, and override all of the XappAdsListener methods in your activity.

A simple interaction is as follows:


import android.util.Log;

import xappmedia.sdk.AdRequest;
import xappmedia.sdk.Advertisement;
import xappmedia.sdk.XappAds;
import xappmedia.sdk.XappAdsListener;
import xappmedia.sdk.model.AdResult;
import xappmedia.sdk.model.Error;

public class XappAdsAdapter extends Activity implements XappAdsListener {

    String TAG = "XAPP";
    XappAds xappAds;

    @Override
    public void onCreate(Bundle savedInstanceState) {

      super.onCreate(savedInstanceState);
      setContentView(R.layout.<yourLayout>);

      xappAds = new XappAds();
      xappAds.start(<yourAPIKey>, <yourAPPKey>, userData /** or null */, location /** or null */, <yourContext>, <yourXappAdsListener>);

    }

    /**
     * XappAds Listener Methods
     */
    @Override
    public void onXappAdsStarted () {
        //Request an ad once XappAds has been initialized
        AdRequest adRequest = new AdRequest();
        xappAds.requestAd(adRequest);
    }

    @Override
    public void onXappAdsFailed(Error error) {
        Log.e(TAG, "XappAds failed: " + error.getLocalizedMessage());
    }

    @Override
    public void onXappAdsTerminated() {
        Log.d(TAG, "XappAds terminated");
    }

    @Override
    public void onAdRequestFailed(AdRequest adRequest, Error error) {
        Log.e(TAG, "Ad request failed " + error.getLocalizedMessage());
    }

    @Override
    public void onAdRequestCompleted (final Advertisement advertisement) {
        Log.d(TAG, "Ad received");
        //Plays the ad as a full-screen interstitial
        xappAds.playAsInterstitial(advertisement);

    }

    @Override
    public void onAdStarted(Advertisement advertisement) {
        Log.d(TAG, "Ad started");
    }

    @Override
    public void onAdCompleted(AdResult adResult) {
        Log.d(TAG, "Ad Complete");
    }

    @Override
    public void onAdFailed(Error error) {
        Log.e(TAG, "Ad failed " + error.getLocalizedMessage());
        //Failed to get audioFocus or ad failed to play for some other reason described in the error message
    }
//    ...
}

Start a Session

The API Key and APP key will be provided by your contact person at XappMedia.

 xappAds = new XappAds();
 xappAds.start(<yourAPIKey, <yourAPPKey>, userData /** or null */, location /** or null */, <yourContext>, <yourXappAdsListener>);

The last parameter to the start call is the instance that implements XappAdsListener, which is assumed to be the calling class. Wait for XappAdsListener method onXappAdsStarted to request an ad.

Request an Ad

Request an ad:

//Request an ad once XappAds has been initialized
AdRequest adRequest = new AdRequest();
xappAds.requestAd(adRequest);

The XappAdsListener method onAdRequestCompleted will be called when the ad is ready for playback.

Play the Ad

Once you receive the ad, it is ready to play. You can play the ad in three different ways; full-screen interstitial, in-tuner tile, or audio only.

//Play the ad as a full-screen interstitial
xappAds.playAsInterstitial(advertisement);

//Play the ad as an in-tuner tile, where adView is a reference to a AdView
xappAds.playAsInTuner(adView, advertisement);

//Play the ad as audio only
xappAds.playAsAudioOnly(advertisement);

Request Record Permission

Since the introduction of Android Marshmallow (API 23), applications are no longer automatically granted the permissions they request on install. If you are building for API level 23 and up, to serve ads that require microphone permission you will need to request the record permission. The Permissions API provides an easy way to request the permission from the user. For more detailed information see the Permissions API guide or see the example project.

Add the activity to your AndroidManifest.xml:

<activity
    android:name="xappmedia.sdk.permissions.ui.RequestPermissionsSoftAskActivity"
    android:theme="@style/Xapp.Theme.Permissions.Activity"/>

Then request the permission:

ArrayList<Permission> collection = new ArrayList<>();
collection.add(Permission.newPermission(Manifest.permission.RECORD_AUDIO).build());

RequestPermissionsSoftAskActivity.newIntent(collection)
        .keys(apiKey, appKey)
        .type(RequestPermissionsCreativeFragment.TYPE_IMAGE)
        .creativeOnly(true)
        .startActivity(getActivity(), REQUEST_PERMISSIONS);

Then the Activity will present a prompt with the given rationale asking the user for the permission. If the user accepts, then the Android system prompt will be displayed to actually grant the permissions. The Activity will immediately return if all permissions have already been granted previously.

Important Notes

Duplicate files copied in APK META-INF/LICENSE Error

If you get the following error:

Error:Execution failed for task ':app:packageDebug'.
> Duplicate files copied in APK META-INF/LICENSE
  	File 1: /Users/user/.gradle/caches/modules-2/files-2.1/com.fasterxml.jackson.core/jackson-core/2.4.3/4cb3dbb0c2f75b51aa7543c53252989785a0c609/jackson-core-2.4.3.jar
  	File 2: /Users/user/.gradle/caches/modules-2/files-2.1/com.fasterxml.jackson.core/jackson-core/2.4.3/4cb3dbb0c2f75b51aa7543c53252989785a0c609/jackson-core-2.4.3.jar

Please add to your android namespace to the module’s build.gradle file:

packagingOptions {
    exclude 'META-INF/NOTICE' // will not include NOTICE file
    exclude 'META-INF/LICENSE' // will not include LICENSE file
}

Passing a Context

It is important that the Context and XappAdsListener provided are fresh when you use the SDK. If either of these would be destroyed during normal application lifecycle, you must currently:

  1. Call xappAds.terminate(),
  2. Create a new instance of XappAds
  3. Call xappAds.start() with a fresh context and listener.

In the above example, this would need to occur any time:

  1. You or someone else calls finish() on the activity which provides the context.
  2. During the default BackPress implementation (which can trigger an onDestroy() call)

You can move the XappAds SDK behind a service, and update the context when refreshing the SDK, but this is beyond the scope of this document.