Cxense Ad Android SDK

Introduction

The Cxense Ad SDK for Android enables displaying of ads from the Cxense Ad service in Android applications.

Migration Notes

Version 3.2.1 simplifies SDK addition for your project.

1. SDK is available in one popular Maven repository now. See section "Add library using Gradle" in Quick Start

2. SDK JavaDoc is available online now. See here

Version 3.2.0 has many breaking changes in API and SDK structure. Please see JavaDoc and Quick Start

1. SDK requires API level 15 as minimum. Use previous version 3.1.18, if your application needs minimum API level < 15.

2. SDK uses auto initialize method. You should remove old initialization code.

3. SDK uses Advertising ID instead Android ID as default user id. You should migrate your data, if you used default user id from SDK before.

4. SDK uses some new third-party dependencies:

   1. Retrofit 2, OkHttp 3, Jackson

   2. Google Play Services Ads 7.0 (only for AAID).

Requirements

SDK requires at minimum Java 8 and Android 4.0.3 (API level 15) or upper.

You should use Gradle for building your app. SDK relies on Gradle features.

Quick Start

1. Change gradle plugin version in root build.gradle (We need 3.0 or newer). Find this code:

   buildscript {
       repositories {
           google()
           jcenter()
       }
       dependencies {
           classpath 'com.android.tools.build:gradle:3.0.0' // and change this line
       }
   } 
   

2. Add SDK to project using Gradle
   

   1. Add in your root build.gradle at the end of repositories:

      allprojects {
          repositories {
              ...
              maven { url 'https://jitpack.io' }
          }
      }  
      

   2. Add in app build.gradle

      android {
          ...
          packagingOptions {
              exclude 'META-INF/LICENSE'
          }
          compileOptions {
              sourceCompatibility JavaVersion.VERSION_1_8
              targetCompatibility JavaVersion.VERSION_1_8
          }
      }
      dependencies {
          ...
          compile "com.cxpublic.cx-android-sdk:cx-ad:VERSION"
      } 
      

3. Add AdView:

   1. Using XML (Example)

      <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:app="http://schemas.android.com/apk/res-auto"
          xmlns:tools="http://schemas.android.com/tools"
          android:layout_width="match_parent"
          android:layout_height="match_parent"
          tools:context="com.example.cxensead.BannerFragment">
          <com.cxense.ad.AdView
              android:id="@+id/adView"
              android:layout_width="match_parent"
              android:layout_height="match_parent"
              app:adSpace="YOUR_AD_SPACE_ID"
              app:refreshRate="60"
              app:autoStart="true"/>
      </FrameLayout>
      

   2. Using code

      AdView adView = new AdView(context);
      adView.setAdSpace("YOUR_AD_SPACE_ID");
      ...
      adView.start();
      ...
      // Set refresh rate (60 seconds by default), to disable automatic refresh handling set the refresh rate to 0
      adView.setRefreshRate(refreshRate, TimeUnit.SECONDS);
      // if you disable refresh timeout, use this for manually refresh view
      adView.refresh();
      

Additional Configuration

In addition to the above you canconfigureenvironment, network restrictions for when new ads are allowed to be fetched and user geolocation (used for Geospatial Targeting):

CxenseAd cxenseAd = CxenseAd.getInstance();
cxenseAd.setEnvironment(Environment.LIVE);
cxenseAd.setNetworkRestriction(NetworkRestriction.NONE);
cxenseAd.setLocation(lastKnownLocation);

Customization points

AdView extends WebView component. That gives an opportunity tocustomizebehaviorofAdView like adding own tricky cache mechanisms for web content caching or implementing interactions between your application and ad’s content.

User ID

To make possible to use audience targeted ad campaigns in mobile applications, Ad SDK provides user tracking feature. You can see that among other parameters each API call has specialparametercalled "usi" (full description is available here: Search REST and JavaScript API). It designates current user identifier.

Advertising ID is used by default as user identifier in ad calls until it will be overridden by custom user id.

Using custom User ID

CxenseAd cxenseAd = CxenseAd.getInstance();
 
// Get default user id. Current value is Advertising ID
String defaultUserId = cxenseAd.getDefaultUserId();
 
// Get current user id
String currentUserId = cxenseAd.getUserId()
 
// Set custom user id
cxenseAd.setUserId(customUserId);

Working with userconsest(GDPR)

CxenseAd cxenseAd = CxenseAd.getInstance();
Set<ConsentOption> currentOptions = cxenseAd.getConsentOptions();
cxenseAd.setConsentOptions(ConsentOption.CONSENT_REQUIRED, ConsentOption.PV_ALLOWED, ConsentOption.RECS_ALLOWED, ConsentOption.SEGMENT_ALLOWED);

Release Notes

Last updated: January 19, 2022