Oracle CX Advertising SDK installation guide

Existing SDK users

If the application is having old Bluekai SDK and you want to use new CX Advertising sdk, please follow below steps.

The new CX Advertising sdk depends on the oracle-cx-mobile-sdk(core sdk) internally. So CX-Advertising sdk users need to integrate Core sdk.

Adding libraries to existing project

Below are the steps to add Oracle CX Mobile SDK(Core SDK) and Oracle CX Advertising SDK(link to be added) to an existing project.

1. Download oracle-cx-mobile-sdk.aar and oracle-cx-advertising.aar files and place in your local system
2. Open your existing android studio project
3. Copy the downloaded SDK (jar or aar file) to your local(libs) folder. In your project, create a folder named “libs” inside app if it does not exist already.
4. Copy oracle-cx-mobile-sdk-{version}.aar and oracle-cx-advertising-{version}-release.aar to the libs folder.
5. Add the following code to app/build.gradle file of your project

6. After adding both the SDKs remove Bluekai SDK from dependencies.
OR
You can add by following this Link

Resolving package import issues

The package structure of CX-Advertising sdk is changed and the base package of the sdk is com.oracle.cx.advertising. So all the public classes should be imported from the com.oracle.cx.advertising package. After removing the old bluekai sdk dependency you will get compilation error at import statements. So you need to replace com.bluekai.sdk with com.oracle.cx.advertising wherever you get the compile time error.

New SDK Users

Download the latest Oracle CX Mobile SDK(Core) & Oracle CX Advertising SDK(link to be added). To import these sdks to the android project follow the below steps.

Adding libraries to android project

1. Download oracle-cx-mobile-sdk.aar and oracle-cx-advertising.aar files and place in your local system
2. Open your existing android studio project
3. Copy the downloaded SDK (jar or aar file) to your local(libs) folder. In your project, create a folder named “libs” inside app if it does not exist already.
4. Copy oracle-cx-mobile-sdk-{version}.aar and oracle-cx-advertising-{version}-release.aar to the libs folder.
5. Add the following code to app/build.gradle file of your project

OR
You can add by following this Link

Edit AndroidManifest.xml

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

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

  implementation 'androidx.preference:preference:1.1.1' 

Add minSdk 24

    defaultConfig {
    ...
    minSdk 24
    ...
  }

Setup the SDK

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

1. With oracle.json

This is a recommended way to set up the SDK. oracle.json is a single configuration file for all different CX modules. The sample oracle.json file can be found here. 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.

1. Create a class and extend it from com.oracle.cx.advertising.ORABaseApplication. And add the class entry in the AndroidManifest.xml file under <application> tag.

2. In the created class load the configuration file using 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

This is same for both java and Kotlin projects.

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

2. Without oracle.json

Even though using oracle.json file is preferred way, using this file is optional. Users can use the SDK without adding the oracle.json file to the project. This is not recommended way, and the initialisation 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
  }
}

There are two ways to implement DataPostedListener:

      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,
                      campaigns: JSONObject
                  ) {
                    #TODO
                  }
       
              }
       
        blueKai = BlueKai.getInstance(this, this, false, "88523","1.0",dataPostedListener, Handler())
    

    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,
          campaigns: JSONObject
      ){
          TODO("Not yet implemented")
        }
    
    }
    

Using the SDK

Once the sdk set up is done, users can start using the sdk. The singleton BlueKai class having all the convenient methods to use the sdk. Please refer to the documentation for available public methods.

Example:

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

NOTE:

If you are using TCFV2 integration(GDPR), Initialize Bluekai SDK once you accept/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. For more details about integrating GDPR follow this link