Cxense Ad Android SDK

Introduction

The Cxense Ad SDK for Android enables the display 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 a minimum API level < 15.

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

3. SDK uses Advertising ID instead of Android ID as the default user ID. You should migrate your data if you used the default user ID from the 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 higher.

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

Quick Start

1. Change the 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 can configure the environment, 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 the WebView component. That gives an opportunity to customize the behavior of AdView, like adding your own tricky cache mechanisms for web content caching or implementing interactions between your application and ad content.

User ID

To enable audience-targeted ad campaigns in mobile apps, the Ad SDK provides a user-tracking feature. Each API call includes a special parameter named usi (full description: Search REST and JavaScript API), which designates the current user identifier.

By default, the Advertising ID serves as the user identifier in ad calls until a custom user ID overrides it.

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 userconsent(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: August 11, 2026