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:4.0.4@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" /> -->
API and App keys.
To use the Xapp SDK, the application’s API keys and APP keys should be included as meta-data in the App’s Manifest inside the <Application> tag with the names xapp.sdk.ApiKey and xapp.sdk.AppKey respectively. For example:
<Application>
...
<meta-data android:name="xapp.sdk.ApiKey" android:value="<!-- Application's API key -->"/>
<meta-data android:name="xapp.sdk.AppKey" android:value="<!-- Application's APP key -->"/>
...
</Application>
Activities and Services
Add the following two lines to your AndroidManifest.xml within the <Application> tag:
<!-- Required: This Service is required to play any Xapp ad. -->
<service android:name="xappmedia.sdk.XappService"/>
<!-- Optional: This Activity is required to play a Xapp Ad in Interstitial mode. It can be omitted if the app plays only in Tuner or audio only. -->
<activity android:name="xappmedia.sdk.XappInterstitialActivity"
android:theme="@style/Theme.AppCompat.NoActionBar"/> <!-- Interstitial Activities are compatible with AppCompat themes -->
<!-- Optional: Allows us to launch an in-app browser to handle touched ads, and certain ad actions. Can be ommitted which will send them to the default browser. -->
<activity android:name="xappmedia.sdk.inappbrowser.WebViewActivity"/>
<!-- Optional: This Activity is required to request permissions through a "soft ask" creative. This can be omitted if the app handles permissions in another way. -->
<activity android:name="xappmedia.sdk.permissions.ui.RequestPermissionsSoftAskActivity"/>
Basic Usage
Request an Ad
Requesting a Xapp can be done either as audio only, tuner, or in as an interstitial Xapp. Audio Only, as the name implies, will only play the Xapp in the background without any visuals. Tuner Xapps will allow you to embed the xapp inside a current Activity rather than starting a new one. An interstitial Xapp will open a new Xapp as a new Activity and handle all the lifecycle issues on its own.
Audio Only
Requesting as Audio Only is the simplest method. It does not include any visual and will play the Xapp in the background for just audio.
public class AppActivity extends Activity {
private void startXapp() {
XappAdController xappController = Xapp.from(this)
.xappAds()
.newRequest()
.loadAd(null);
xappController.start();
}
}
Tuner
Requesting as a Tuner will allow the Xapp to be played inside a ViewGroup container. This method requires a android.support.v4.app.fragmentManager and the container ID. The regular android.app.FramgentManager is currently not supported.
public class AppActivity extends Activity {
private void startXapp() {
XappAdController xappController = Xapp.from(this)
.xappAds()
.newRequest()
.loadAd(getSupportFragmentManager(), R.id.xappContainer, null);
xappController.start();
}
}
Interstitial
Requesting a Xapp as an Interstitial will play a fullscreen Activity of the Xapp. For this you will need to add the Interstitial Activity to the app’s Manifest like so:
<activity android:name="xappmedia.sdk.XappInterstitialActivity"
android:theme="@style/Theme.AppCompat.NoActionBar"/> <!-- Interstitial Activities are compatible with AppCompat themes -->
The Activity extends from AppCompatActivity so it requires an AppCompat theme applied to it. This is not needed if the main app’s theme is already derived from an AppCompat theme.
There are two methods to play it. The first method accepts the calling Activity and a request code. The request code is used for Activity#onActivityResult(int, int, Intent) which will receive the AdResult object on a finished Xapp.
Requesting for an ad result:
public class AppActivity extends Activity {
public static final int XAPP_REQUEST_CODE = 1;
private void startXapp() {
XappController controller = Xapp.from(this)
.xappAds()
.requestAd()
.loadAd(this, XAPP_REQUEST_CODE, null);
controller.start();
}
@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == XAPP_REQUEST_CODE) {
if (resultCode == Activity.RESULT_OK) {
AdResult result = data.getParcelableExtra(XappInterstitialActivity.RESULT_ADRESULT);
// Use result
} else {
// An error ocurred while trying to play the Xapp and the Activity had to cancel.
}
}
}
}
Starting an Interstitial without a result.
public class AppActivity extends Activity {
private void startXapp() {
XappController controller = Xapp.from(this)
.xappAds()
.requestAd()
.loadAd(this, null);
controller.start();
}
}
LoadCallback
To capture loading errors, each loadAd() method accepts a LoadCallback which has two methods: LoadCallback#onLoad() and LoadCallback#onError(). onLoad() is called when the Xapp is downloaded and ready to play. onError() is called when the Xapp failed to download. If this occurs, then the controller has been released and a new request must be made.
XappAdController
The returned XappAdController also gives the options to pause, stop, and release the controller. Calling XappAdController#start() before the Xapp is downloaded will start the Xapp as soon as it is ready.
Calling XappAdController#pause() will pause the Xapp at it’s current location. Calling XappAdController#start() again after a XappAdController#pause() will resume the Xapp.
Calling XappAdController#stop() will stop the Xapp at it’s current location. Calling “start” again after a “stop” will restart it from the beginning.
Releasing is done automatically when the Xapp has finished playing, but calling XappController#release() early will stop it and release all resources. Once this is done, then the controller object is considered dead and cannot be re-used.
The XappAdController#setVolume allows manual control of the volume. This method accepts a value of 0-100 representing the precentage of volume to set. 0 is mute while 100 is full volume.
Attaching to a Xapp
Because of the nature of Android, XappControllers can’t be kept around if an Activity or Service that has held the controller has been destroyed. An Activity can re-attach to a currently playing Xapp by using the XappAds#attach() methods that corresponds with the Xapp is being played. These will give a controller that links to the current Xapp. These methods will return null if there is no xapp currently playing.
Attaching as an audio only controller
The XappAds#attach() method will simply attach to the currently playing Xapp. No visual will be presented.
public class AppActivity extends Activity {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
XappAdController controller = Xapp.from(this)
.xappAds()
.attach();
if (controller != null) {
// There is a Xapp playing and the controller can now control it.
} else {
// There is no Xapp currently playing.
}
}
}
Attaching as a tuner controller
The XappAds#attach(FragmentManager, int) will attach a Xapp to the container ID given to the method.
public class AppActivity extends AppCompatActivity {
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
XappAdController controller = Xapp.from(this)
.xappAds()
.attach(getSupportFragmentManager(), R.id.xappContainerId);
if (controller != null) {
// There is a Xapp playing and the controller can now control it.
} else {
// There is no Xapp currently playing.
}
}
}
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)
.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.
Time to Test
Complete your integration by running through our recommended test cases.