Basic Installation Guide

The Oracle CX Core SDK is a library for Android that enables easy integration with Oracle Infinity Analytics. This guide will walk you through the initial setup process, enabling you to start using the SDK quickly.

Below are the three steps to follow to integrate the SDK into your project

1. Import Oracle CX Core SDK

First download the latest Oracle CX Mobile SDK. The Oracle CX Core SDK is a basic library for Android. This guide will walk you through the initial setup process, from integrating the SDK with your project, to sending events to Oracle Infinity Data Collection Server.

Import the SDK into Your Project

Once you have an Android project, adding the SDK is simple. These instructions will be based on using Android Studio, but they may easily be adapted for use with Eclipse or any other Android IDE.

  1. Once the SDK is downloaded and extracted, open up your Android project.
  2. Select your project root or any module in the project, right click on it and then choose Open Module Settings
  3. Click the +** sign on the top left under **Modules column to add a new module.
  4. Select Import .JAR/.AAR Package from the list of options and click Next.
  5. Browse to the extracted oracle-cx-mobile-sdk-release-xxx.aar file. This filename will vary from version to version. Click Finish to import.
  6. In Module Settings screen, select Dependencies and select your project main module.
  7. Select +** button under **Declared Dependencies section, Select Module Dependency
  8. Select the module that you just imported and click OK.

2. Initialize the SDK

Oracle Core Mobile SDK needs Application context to initialize the SDK. There are two ways to pass Application context to SDK. You can use either one of two.

1. Using ORABaseDataCollector.setApplication() method

ORABaseDataCollector has a static method setApplication() which accepts android.app.Application as a parameter. Any other module developer or application developer has to call this method before calling any other method in the SDK. It is recommended to call this method in android application class(which is the starting point of android application).

import android.app.Application;
publicclass TestApplication extends Application {
@Override
publicvoid onCreate() {
super.onCreate();
ORABaseDataCollector.setApplication(this);
}
}

2. Extend from ORABaseApplication

There is one other way to provide Application context to the SDK. SDK having the class ORABaseApplication which internally extends Application class. So application/module developers has to extends their application class from ORABaseApplication instead of android.app.Application. And it need to be added this class in Android Manifest file.

package com.sample.testapp;
publicclass TestApplication extends ORABaseApplication {
@Override
publicvoid onCreate() {
super.onCreate();
}
}

In AndroidManifest.xml

<manifestxmlns:android="http://schemas.android.com/apk/res/android"
package="com.sample.testapp">
----------
----------
<application
android:name="com.sample.testapp.TestApplication"
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:theme="@style/AppTheme">
-----------
-----------
</application>
</manifest>

Note: Its mandatory to use any one of the above mentioned way to instantiate the SDK. Otherwise all calls to ORABaseDataCollector will throw IllegalStateException with message Oracle must be initialized with a call to ORABaseDataCollector.setApplication(Application)

3. Configure the SDK

There are two ways one can configure the Oracle CX Core SDK

1. Without Configurations

In this case, without manually enabling Oracle CX Core configurations, one can use all the features of the SDK except sending events to server. This will be helpful in case we don't want to send the events to the data collection server. In case if you want to send events to the server, then please follow the next step. Below are the few features we can use without configuration:

  • HTTP layer
  • Namespace storage
  • Relational data store

2. With Configurations

Using this case, the Oracle CX Core SDK will send all the event tracking data to the server. To enable the configurations, please follow the below documentation.

If you are using the older version(1.0.4 and below) of SDK, to set the configurations, skip the below step and follow Set the configurations without json file. Please note, this method has been deprecated.

Setting the Configurations Using oracle.json

Once you have integrated Oracle CX Core SDK, if you would like to send the events to data collection server, it is required to pass the configurations such as url and account_guid etc. This can be done with the help of oracle.json file. The sample oracle.json file can be found here. Place the oracle.json file in the application assets folder and update the keys ora_dc_collection_url & ora_dc_account_guid with your own values given. This configuration will help in sending data to the server. As a next step, we need to load these configurations from the code. After adding the oracle.json, you need to call loadFromConfigFile() method with ORACoreDataContainer instance

ORACoreDataContainer container = new ORACoreDataContainer(this);
container.loadFromConfigFile();

In general it is recommended to call loadFromConfigFile() at the starting point of the application. So it is good to call loadFromConfigFile() in android Application class.

The loadFromConfigFile() will throw ORARuntimeException if oracle.json is not present in assets folder, or the oracle.json contains invalid json text. If you forgot to call loadFromConfigFile() then the library will work with default values.

Note: You will learn more about oracle.json and about its versioning in Configuration Guide. You can learn more about ora_dc_end_point_config in Multiple Endpoint Guide.

If you would like to add any other Core configs in the above json, you can add as shown below.

{
"config_version": "1.0",
"ORACORE": {
"ora_dc_end_point_config": [
{
"ora_dc_collection_url": "https://dc.oracleinfinity.io/v3/",
"ora_dc_account_guid": "abcd123456",
"ora_dc_retry_count": 2
},
{
"ora_dc_collection_url": "https://your_end_pont_2/",
"ora_dc_account_guid": "xyzabc1234",
"ora_dc_retry_count": 3
}
---------------
Add as many end points as per your need
---------------
],
"ora_dc_send_interval_millis": "5000",
"ora_dc_enabled": "true"
}
}

Note: The configurations which are not added in oracle.json file will have the default values.

After steps 2 & 3 your Application class looks like below

import android.app.Application;
importcom.oracle.cx.mobilesdk.persistent.ORACoreDataContainer;
publicclass TestApplication extends Application {
@Override
publicvoid onCreate() {
super.onCreate();
//This is to initialize the SDK
ORABaseDataCollector.setApplication(this);
//This is to load oracle.json to SDK
ORACoreDataContainer container = new ORACoreDataContainer(this);
container.loadFromConfigFile();
}
}

Note: If you are using older version and upgraded to newer one and want to use oracle.json file for loading config, you need to put config_version as higher than the version mentioned in loadConfig(map, version) method.

4. Logging - Enable / Disable logs

Deprecated:
Using DEBUG config is deprecated and will be removed in future releases. Instead use new ORALogger api which is explained below for logging.

The Oracle CX Core SDK contains lot of log statements across the code. This logs can be used to analyze the flow when you run across the issues. The logs are categorized into different levels. ORALogger provides api to enable or disable the logs.

Below are the different log levels used in the SDK:

  • VERBOSE
  • DEBUG
  • INFO
  • WARN
  • ERROR
  • NONE

setLogLevel(int logLevel) method is used to set the log level. If you set any log level, it will show log messages of that level and as well as the message levels lower in the list. For example if you set log level INFO, it will show all INFO, WARN, and ERROR messages.

Note: The default log level set by sdk is DEBUG.

If you want to disable all the log messages, set the log level to NONE.

Below is the sample code to set the log level

ORALogger.setLogLevel(ORALogger.INFO);

Below is the sample code to disable the logs

ORALogger.setLogLevel(ORALogger.NONE);

Your project is now configured to use The Oracle CX Core SDK.

5. Common Actions

This guide provides sample code for a couple of common actions you might take with the SDK, such as triggering events and pausing/resuming event sending.

Triggering Event

There are several convenience methods in Oracle CX Core SDK to trigger a particular event(i.e. button click etc). Here's an example of how to send an event

Map <String, String> customData = new HashMap<String, String>();
customData.put("custom", "data");
customData.put("ORA.ad", "advertisement");
ORAEventMap eventMap = new ORAEventMap("dcsuri", "oraTi", "oraPi", "oraSys", "oraDl", customData);
ORABaseDataCollector.getInstance().triggerEvent(eventMap);

The values you specify for eventPath, eventDesc, eventType, customData, and contentGroup in ORAEventMap provide data that can be accessed in Oracle Infinity reporting. Note that the minimal suggested data for these event methods is an eventPath such as /MyApplication/Settings/Save_Credentials_Screen, an eventDesc such as Restaurant Details Screen and an eventType such as view or click. Some methods require additional data such as a product SKU or a conversion event name.

Triggering Event Immediately

The above triggerEvent() method will create and stores an event in the local database. Based on the config ORABaseConfigSettings.SEND_INTERVAL_MILLIS value, it will fetch the events from the database and send them to collection servers. This process takes a couple of seconds(based on the config) to reach event info to the server. But there are cases, we need to send event info immediately to the server without storing in the database. To serve this case, we can use triggerEventImmediately. In the case of internet non-availability during the call, we can use the config ORABaseConfigSettings.IMMEDIATE_EVENT_STORING_ENABLED to save the event data into the database. Here’s an example of how to send an immediate event.

final ORAEventMap eventMap = new ORAEventMap(DCSURI, DESCRIPTION, DESCRIPTION, ORA_SYS, ORA_DL, null);
dataCollector.triggerEventImmediately(eventMap);

Trigger Event Automatically

In above sections we have explained how to send an event to sever manually. But it is possible to send an event automatically based on system behavior like when application started, application went to background or foreground. In its default configuration, Oracle CX Core SDK logs nothing. Automatic events can be logged by setting the respective config settings to true. Below are some of the configurations.

By setting these config values to true will enable automatic event triggering. See Application Life Cycle Methods and Android Push Notification support for more details about automatic events

6. Disabling Data Collection & Pausing/Resuming Event Sending

Oracle CX Core SDK data collection can be disabled at any time. You may want to disable data collection in the application to ensure no data is collected.

To disable collection:

ORACoreDataContainer container = new ORACoreDataContainer(context);
container.putValue(ORABaseConfigSettings.ENABLED, "false");

Here’s an example of how to pause then resume event sending:

// Pause
ORABaseDataCollector.getInstance().pauseEventTransmission();
// Resume
ORABaseDataCollector.getInstance().resumeEventTransmission();