Oracle CX Advertising Android SDK

Integrating the Oracle CX Advertising SDK (formally known as the Oracle Data Cloud platform) into your native and hybrid apps enables you to extract mobile user attributes from your screens (product page visits, purchase intent signals, add-to-cart actions, and conversions), and transfer them into the Oracle CX Advertising platform.

To import your mobile app data into the Oracle CX Advertising platform, add the Oracle CX Advertising SDK to the screens in your mobile app, pass phints (key-value pairs representing user attributes) to the platform, and create rules to map the phints into categories in your taxonomy.

Choosing the Android SDK version

Choose the version of the Oracle CX Advertising Android SDK you want to work with:

SDK version	Features	Next Steps
2.1.9	Extracting Attributes for product page visits, purchase intent signals, add-to-cart actions, and conversions.	Go to Android SDK version 2.1.9
4.0.0	This is the latest version of the Android SDK. Features include: Hashed Email Support Customer unique ID and value support GDPR (TCFV2) Support PII Redaction and many more. To learn more, see the changelog. Important: If you are using TCFV2 integration (GDPR), initialize Bluekai SDK once you accept or deny GDPR pop-up. CX Advertising SDK will read the GDPR consent from the device and will internally append GDPR consents in the URL accordingly. Learn more about integrating GDPR.	Download Go to Steps to integrate the Android SDK in your apps.

SDK version

Features

Next Steps

2.1.9

Extracting Attributes for product page visits, purchase intent signals, add-to-cart actions, and conversions.

Go to Android SDK version 2.1.9

4.0.0

This is the latest version of the Android SDK.

Features include:

Hashed Email Support
Customer unique ID and value support
GDPR (TCFV2) Support
PII Redaction and many more.

To learn more, see the changelog.

Important: If you are using TCFV2 integration (GDPR), initialize Bluekai SDK once you accept or deny GDPR pop-up. CX Advertising SDK will read the GDPR consent from the device and will internally append GDPR consents in the URL accordingly. Learn more about integrating GDPR.

Download

Go to Steps to integrate the Android SDK in your apps.

Steps to integrate the Android SDK in your apps

To integrate the Android SDK in your apps:

Get a site ID.
Scope your data.
Integrate the Android SDK.
Classify your data.
Monitor data ingest.

Step 1: Getting a site ID

To instantiate the Oracle CX Advertising platform SDK in your mobile app, you need a site ID. The site ID is used to manage your data in the Oracle CX Advertising platform. Classification rules use the site ID to identify into which categories to map user attributes. You generate a site ID by creating a container. You can create containers in the UI or with the containers API. It is a good practice to create separate site IDs for testing and for production environments.

After you create the container, open a Oracle Support ticket requesting "Direct Ingest Access for ADID" and include your partner name, partner ID, and the site ID.

To onboard data for user profiles located in the European Union (EU), you must have signed Oracle's General Data Protection Regulation (GDPR) Consent agreement. If you have not signed the agreement, you can only create containers that are configured for non-EU countries. This means that a blacklist must include the EU region or countries and a whitelist may not. If you attempt to create a container with an invalid configuration, the UI or API displays an error. By default, new containers blacklist the EU. Contact your Oracle Account Representative to obtain and sign the GDPR Consent agreement.

Step 2: Scoping data

Identify the user attributes you want to extract from your mobile app and transfer to the Oracle CX Advertising platform. For example, if your app includes a screen about toasters, you could pass a toaster attribute to the platform when users visit that screen. If you purchased consulting services, your solutions consultant can work with you on scoping your mobile app and designing a data collection strategy.

Step 3: Integrating the Android SDK

To begin collecting page-level and user data from your mobile apps and transferring it into the Oracle CX Advertising platform, you need to install and implement the Oracle CX Advertising SDK. After you implement the SDK, you must re-release your app via the app store.

Choose an option:

Upgrading to Android SDK version 4.0.0
Installing Android SDK version 4.0.0 for first time users

After upgrading or installing, you will then complete the following:

Updating the Android manifest and build.gradle
Setting up the SDK
Implementing the DataPostedListener
Using the SDK

Note: This topic discusses working with latest version of the Oracle CX Advertising Android SDK. To work with version 2.1.9, see Android SDK version 2.1.9.

Upgrading to Android SDK version 4.0.0

If your application is uses a previous version of the Oracle CX Advertising Android SDK and you want to use the latest Android SDK, please follow the below steps. Oracle CX Advertising SDK version 4.0.0 depends on the oracle-cx-mobile-sdk (core SDK) internally. So Oracle CX Advertising users need to integrate Core SDK.

Use the following steps to download the latest Oracle CX Mobile SDK (Core) and Oracle CX Advertising SDKs and add them to your existing Android project. Alternatively, you can add by following the instructions here.

Adding the SDKs to an existing project:

Download the latest Oracle CX Mobile SDK and the Oracle CX Advertising Android SDK.
Place the oracle-cx-mobile-sdk.aar and the oracle-cx-advertising.aar files in your local system.
Open your existing Android Studio project.
Copy the downloaded SDK (jar or aar file) to your local (libs) folder. In your project, create a folder named "libs" inside the app if it does not exist already exist.
Copy oracle-cx-mobile-sdk-{version}.aar and oracle-cx-advertising-{version}-release.aar to the libs folder.
Add the following code to app/build.gradle file of your project 6. After adding both the SDKs remove Bluekai SDK from dependencies.

implementation files('libs/oracle-cx-mobite-sdk-1.1.3.aar')
implementation files('libs/oracle-cx-advertising-4.0-release.aar')
After adding both the SDKs, remove Bluekai SDK from dependencies.

After you finish, resolve package import issues.

Resolving package import issues

The package structure of the CX Advertising SDK has changed. The base package of the SDK is com.oracle.cx.advertising. So all public classes should be imported from the com.oracle.cx.advertising package.

After removing the old Android SDK dependency, you will get a compilation error at import statements. To resolve the errors, you must replace com.bluekai.sdk with com.oracle.cx.advertising wherever you get the compile-time error.

Installing Android SDK version 4.0.0 for first time users

For first time users, follow the steps below to download the latest Oracle CX Mobile SDK (Core) and Oracle CX Advertising Android SDK. After downloading the SDKs, you will import them into your Android project. Alternatively, you can add by following the instructions here.

To install the Android SDK:

Download the latest Oracle CX Mobile SDK and the Oracle CX Advertising SDK.
Place the oracle-cx-mobile-sdk.aar and the oracle-cx-advertising.aar files in your local system.
Open your existing Android Studio project.
Copy the downloaded SDK (jar or aar file) to your local (libs) folder. In your project, create a folder named "libs" inside the app if it does not exist already exist.
Copy oracle-cx-mobile-sdk-{version}.aar and oracle-cx-advertising-{version}-release.aar to the libs folder.
Add the following code to app/build.gradle file of your project 6. After adding both the SDKs remove Bluekai SDK from dependencies.

implementation files('libs/oracle-cx-mobite-sdk-1.1.3.aar')
implementation files('libs/oracle-cx-advertising-4.0-release.aar')
After adding both the SDKs, remove Bluekai SDK from dependencies.

After you finish, update the Android manifest and build.gradle.

Updating the Android manifest and build.gradle

Updating the Android manifest

The Oracle CX Advertising Android SDK needs the following permissions to work properly. Add these permissions to the AndroidManifest.xml in your existing project.

<uses-permission android:name="android.permission.INTERNET"/>

Updating the apps build.gradle file of your project

Add the following code to the app/build.gradle file of your project:

Locate implementation 'androidx.preference:preference:1.1.1' and add minSdk 24:

defaultConfig {
	...
		minSdk 24
	...
}

Setting up the SDK

There are two ways we can set up the Oracle CX Advertising Android SDK.

Setting up the SDK with oracle.json - This is a recommended way to set up the SDK.
Setting up the SDK without oracle.json

Setting up the SDK with oracle.json

It is recommended that you setup the SDK with the oracle.json file. The oracle.json file is a single configuration file for all different CX modules. The sample oracle.json file can be found here (applewebdata://C7E17C60-B74A-422D-B7A4-C3F2A7C5FC17/oracle.json). Place the oracle.json file in the app module assets folder and update the file with your own values. More details about oracle.json can be found in Oracle CX Mobile SDK documentation. Below are the steps to configure the SDK in Java and Kotlin.

Create a class and extend it from com.oracle.cx.advertising.ORABaseApplication.
Add the class entry in the AndroidManifest.xml file under the <application> tag.
In the created class load the configuration file using the ORAAdvDataContainer API.

Java

.java public class TestApplication extends ORABaseApplication{
	@Override
	public void onCreate() {
		super.onCreate();
		ORAAdvDataContainer container = new ORAAdvDataContainer(this);
		container.loadFromConfigFile();
	}
}

Kotlin

.kt class TestApplication : ORABaseApplication() {
	override fun onCreate() {
		super.onCreate()
		val container = ORAAdvDataContainer(this)
		container.loadFromConfigFile()
	}
}

Android Manifest example

.xml
<application android:name="com.oracle.testapp.TestApplication"
......
......
>
</application>

Setting up the SDK without oracle.json

Using the oracle.json file is recommended but optional. You can use the SDK without adding the oracle.json file to the project. This is not the recommended way, and the initialization method is deprecated. Below is the example code to set configurations.

Java

.java public class MainActivity extends AppCompatActivity implements DataPostedListener {
	BlueKai blueKai = null;
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_main);
		blueKai = BlueKai.getInstance(this,this,false,"2","1.0",this,new Handler());
		blueKai.setDataPostedListener(this);
	}
}

Kotlin

.kt class MainActivity : AppCompatActivity(), DataPostedListener {
	//Oracle CX Advertising SDK main object
	var blueKai: BlueKai? = null
	override fun onCreate(savedInstanceState: Bundle?) {
		super.onCreate(savedInstanceState)
		setContentView(R.layout.activity_main)
	
		//Get instance of BlueKai object
		blueKai = BlueKai.getInstance(this, this, false, "2","1.0",this, Handler())
		blueKai!!.dataPostedListener = this
	}
}

Implementing the DataPostedListener

You can implement the DataPostedListener using one of the following methods:

By defining DataPostedListener methods
By implementing the DataPostedListener interface

Defining DataPostedListener methods

Kotlin

var blueKai: BlueKai? = null
var dataPostedListener: DataPostedListener? =null
....

dataPostedListener = object : DataPostedListener{
            override fun onDataPosted(success: Boolean, message: String?) {
               #TODO
            }

            override fun onDataPosted(
                response: String,
                dataPosted: HashMap<String, String>,
                campaigns: JSONObject
            ) {
              #TODO
            }
        }

  blueKai = BlueKai.getInstance(this, this, false, "88523","1.0",dataPostedListener, Handler())

Implementing the DataPostedListener interface

Kotlin

import com.oracle.cx.advertising.listeners.DataPostedListener

class MainActivity: AppCompatActivity(), DataPostedListener{

 override fun onCreate(savedInstanceState: Bundle?) {
  
	blueKai = BlueKai.getInstance(this, this, false, "2","1.0",this, Handler())
  	blueKai!!.dataPostedListener = this
}

override fun onDataPosted(success: Boolean, message: String?) {
        TODO("Not yet implemented")
 }

override fun onDataPosted(
      response: String,
      dataPosted: HashMap<String, String>,
      campaigns: JSONObject
   ){
      TODO("Not yet implemented")
    }

}

Using the SDK

Once the SDK setup is done, users can start using the SDK. The singleton BlueKai class has all the convenient methods to use the SDK. Please refer to the documentation for available public methods.

Example:

blueKai?.put("car","audi")

Step 4: Classifying data

After you have integrated the Oracle CX Advertising SDK into your app, classification rules need to be written to map the page and user attributes you are extracting from your mobile app to categories in the Oracle Data Cloud platform (a category is a collection of users that have the same attribute). purchase =, then the add the user to the toaster category).
Classification rules can be written using one of the following three methods:

Self-classification tools: Use the Self Classification tools in the Oracle Data Cloud platform UI to manually create the data mapping rules and categories.
category and rule APIs: Programmatically create the data mapping rules and categories.

Classification via Oracle Data Cloud's classification and taxonomy team: You will create a data map that will enable the platform to create classification rules that map your phints to categories in your taxonomy. Your data map must include the following information:

The set of keys used in your phints.
The possible set of values for each key, and associate them with human readable category names, if necessary.
The hierarchical relationships, if any, between a set of keys.

For example, consider an auto shopping site that collects the makes and models of cars for which users have demonstrated intent to purchase. The key-value pair for the make node would have the following syntax: MA100=[VALUE]. The example key-value pairs for this node could be as follows:

MA100=Honda
MA100=Acura
MA100=Toyota

The key-value pair for the model node would have the following syntax: MA110=[VALUE]. Based on the previous example make nodes, example key-value pairs for the model node could be as follows:

MA110=Accord
MA110=Civic
MA110=TL
MA110=TSX
MA110=Corolla
MA110=Camry

If the values for the makes were encoded (for example, you pass 23098, 21409, 57983 instead of Honda, Acura, and Toyota), the platform would need human readable category names for these encoded values. For example, the following translations could be used:

MA100=23098 > Honda
MA100=21409 > Acura
MA100=57983 > Toyota

The following data map could then be created for this site:

Key	Key translation	Value	Value translation (category name)
MA100	Make	Honda	Honda
MA100	Make	21409	Acura
MA100	Make	57983	Toyota
MA110	Make > Model	Accord	Honda > Accord
MA110	Make > Model	89065	Honda > Civic
MA110	Make > Model	TL	Acura > TL
MA110	Make > Model	TSX	Acura>TSX
MA110	Make > Model	Corolla	Toyota > Corolla
MA110	Make > Model	Camry	Toyota > Camry

When you are done creating your data map, send it to your Oracle CX Advertising Partner Manager.

Step 5: Monitoring data ingest

After your app begins transferring data into the Oracle CX Advertising platform, you should verify that your data is being collected and classified correctly and that your app is generating the expected amount of inventory.

To monitor your data ingest:

Check if your mobile app is calling the platform. Use the site hits report in the platform to verify that your app is sending calls.
Check if your inventory is growing. Use the inventory trend report to verify that the amount of inventory per category is increasing daily.
Check your 30-day inventory. Use the Audience Builder in the Oracle Data Cloud platform to view the estimated number of unique users in your categories based on current configurations.

You can also use the categories API to programmatically check your inventory of your unique users.

Learn more

SDK changelog