Using the Oracle CX Infinity Module for Android

This section serves a quick guide for integrating the Infinity module with your Android mobile applications.

In this topic:

Android version and API compatibility

Android Version API Version
Android 11 30
Android 10 29
Android 9 (Pie) 28
Android 8 - 8.1 (Oreo) 26 - 27

Getting Started

Follow the below steps to integrate the Infinity module with your mobile application.

  1. Download the Core and Infinity modules
  2. Import the Core and Infinity modules into your mobile application project
  3. Add the Core and Infinity modules as dependencies in your mobile application project
  4. Configure and initialize the modules

Downloading the Core and Infinity modules

The Infinity module leverages some of the capabilities from the Core module. So, for the Infinity module to work as expected, the Core module must be downloaded and imported to your mobile application project.

Download the Core module and Infinity modules from here.

The Infinity module collects the events from the mobile application based on user interactions and transmits the events to the Core module. The Core module appends the default parameters captured by it with the events received by it from the Infinity module. The Core module then batches the events and transmits the events to the data collection servers. So the Infinity module does not work without the Core module. To set-up the Core module, please follow the documentation available here.

Importing the modules and adding the modules as dependencies

Once the modules are downloaded they need to be imported into the mobile app project and added as dependencies. For a step-by-step guide to importing and adding the modules as dependencies into the project, please check here.

Adding the mandatory configuration to Core Module of your project

Note: If you have already configured the Core module, skip this step and head on to the next step to configure the Infinity module.

After importing and adding the modules as dependencies, the Core module must be configured to be used with the Infinity module. The Core module is configured by creating a JSON file ([oracle.json]) and adding it to the assets directory of the project.

The configuration that needs to be set in the [oracle.json] file includes the below parameters. These parameters are used to configure the details of the Infinity servers to which data is to be sent.

Data Object Parameter Mandatory/Optional Sample Value Description Remarks
ora_dc_end_point_config Mandatory Endpoint details to which collected data must be sent You can configure any number of endpoints. The same payload can be sent to multiple endpoints for downstream processing
ora_dc_collection_url Mandatory https://dc.oracleinfinity.io/v3/ Destination to which data should be sent
ora_dc_account_guid Mandatory guid221281 Unique identifier for customers on Infinity systems
ora_dc_retry_count Optional 2 Number of attempts for posting data to endpoints in the event of failure
ora_dc_modules Optional [ “infy” ] Oracle CX modules list

oracle.json

{
				"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_modules": [
				"infy"
				],
				"ora_dc_send_interval_millis": "5000",
				"ora_dc_enabled": "true"
				},
				"ORAINFINITY": {
				//Add analytics related configurations here
				}
				}

You can control the behavior of the Core module, by editing the configuration settings available for the Core module.

Configuring the Infinity Module

Configurations are the settings of the Module that govern the behavior of the module. The configuration of the Infinity Module is done by one of the below methods

  • Using oracle.json file as described in the previous section to configure
  • Programmatic configuration

Configuring the Infinity module using the oracle.json file

The configuration for the Infinity module is added to the oracle.json file under the ORAINFINITY object. This configuration needs to be added to the same oracle.json file that is used for the Core module.

The list of parameters that can be configured are given here.

oracle.json - ORAINFINITY

"ORAINFINITY": {
				//Add analytics related configurations here
				"ora_dc_video_load_auto_enabled": "true",
				"ora_dc_video_load_meta_auto_enabled" : "false"
				}

Once the oracle.json file is added to assets folder, the json file must be called from the loadFromConfigFile() method to load the file to be used by the SDK.

loadFromConfigFile

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

Note: If we call the loadFromConfigFile method using ORAInfinityDataContainer instance then it is NOT require to call the same method using ORABaseDataCollector instance. We will internally take care of calling loadFromConfigFile using ORABaseDataCollector instance.

Programmatic Configuration of the Infinity module

The Infinity Module has ORAInfinityDataContainer and ORAInfinityConfigSettings classes. These classes provide the list of configurations available in the Core module.

To set the configuration settings for use with your mobile application, you can use the putValue() method in the ORAInfinityDataContainer class. The putValue() method inserts the key and value of the configuration to store.

To configure the Infinity module programmatically

  1. Create object for ORAInfinityDataContainer.
  2. To set or update a configuration, call the endpoint:
        ORAInfinityDataContainer.putValue(final IORAConfigSetting key, final String value)
  3. To retrieve configuration, call the endpoint:
        ORAInfinityDataContainer.getValue(IORAConfigSetting key)

The list of parameters that can be configured are given here.

Sample Code for configuring VIDEO_LOAD_AUTO_ENABLED parameter

ORAInfinityDataContainer container = new ORAInfinityDataContainer(context);
container.putValue(ORAInfinityConfigSettings.VIDEO_LOAD_AUTO_ENABLED, "true");

Initializing the Infinity Module

The Infinity module needs to be initialized for using it along side the Core module. The instructions for using the Core module in you mobile application project are shared here.

The application context is needed to initialize the Infinity module. The initialization can be done in 2 ways.

  1. Extending the ORAApplication
  2. Using ORADataCollector.setApplication() method

Extending the ORAApplication

Modify the main class that extends the Application by replacing “Application” with ORAApplication as shown below. The following code snippet automates the capture of various application and activity life-cycle events.

package com.oracle.pike.piketestapp;
import com.oracle.infinity.analytics.ORAApplication;    //Import the ORAApplication class
 
public class PikeApplication extends ORAApplication{    //Change Application to ORAApplication
    @Override
    public void onCreate(){
        super.onCreate();
    }
}

Using ORADataCollector.setApplication() method

Another way to initialize the Infinity module is by calling the ORADataCollector.setApplication() method. This initialization must be done before calling any of the event methods. Add the call to the setApplication() method as the first line in the onCreate function in the Main application as shown below.

public class HelloWorld extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        ORADataCollector.setApplication(this);   
        ...
    }
    ...
}

Additional permissions

Sometimes additional permissions are needed to perform other tracking tasks or to track location information from the device. You can edit the AndroidManifest.xml to add the necessary permissions.

Sample AndroidManifest.xml file with permissions

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.oracle.helloworld"
          android:versionCode="1"
          android:versionName="1.0">
    <application android:icon="@drawable/icon" android:label="@string/app_name">
        <activity android:name=".HelloWorld" android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
<!-- Permissions to access location data -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
</manifest>

The Infinity Module is now configured for use in the mobile application project.

Capturing behavior data

Once the Infinity module is initialized, you can use the Infinity module to capture behavior data. Any behavior data event can be captured using the following function.

Sample Trigger Event

final ORAEventMeta eventMeta = new ORAEventMeta(eventPath, eventDesc, eventType, customData);
ORADataCollector.getInstance().triggerScreenViewEvent(eventMeta, "Content Group");

The values specified for eventPath, eventDesc, eventType, customData, and contentGroup can be accessed for creating reports or dashboards in Oracle Infinity Analytics.

To pass custom data specific to your mobile application, you can use the customParams argument. The customParams argument is a Map object with string-type key-value pairs. You can create the key-value pairs and pass them as custom parameters in any method.

Sample code for Custom Data

import java.util.*;
Map <String, String> customData = new HashMap<String, String>();
customData.put("custom", "data");
customData.put("ORA.ad", "advertisement");
final ORAEventMeta eventMeta = new ORAEventMeta(eventPath, eventDesc, eventType, customData);
ORADataCollector.getInstance().triggerScreenViewEvent(eventMeta, "Content Group");

Next steps

Android Behavior Data Collection Methods

Android Video Behavior Data Collection Methods