Using the Core Module - Android

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

Android version and API compatibility

Getting Started

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

1. Download the Core module

2. Import the Core module into your mobile application project

3. Add the Core module as dependency in your mobile application project

4. Configure and initialize the module

Downloading the Core module

Note: The Infinity module version 1.1.2 or later works only with the Core module version 1.1.3 or later.

Download the Core module from here.

Importing the Core module and adding it as a dependency

Once the Core module is downloaded it must be into the mobile app project and added as a dependency. For a step-by-step guide to importing and adding the module as dependency into the project, please check here.

After the Core module is added to your Android project, the below steps must be completed to begin using the module.

1. Configuring the Core module

2. Initializing the Core module

Configuring the Core module

The Core module has been designed to work independently with all the product modules. All features of the Core module can be leveraged by any of the product modules except for event data transmission to the server. The Core module can be configured in the following way:

Using the oracle.json file

You can use various configuration parameters to control the functionality of the Core module, such as the following.

The complete list of parameters that can be used to configure the Core module are available here.

Create the oracle.json file with the following code.

{
    "config_version": "1.0",
    "ORACORE": {
        "ora_dc_http_connect_timeout_millis": "10000",
        "ora_dc_http_read_timeout_millis": "5000",
        "ora_dc_app_start_auto_enabled": true
    }
}
	

Once the configuration is set, place the oracle.json file in the application assets folder of your mobile application project. After adding the oracle.json, you need to call the loadFromConfigFile() method with the ORACoreDataContainer instance.

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

We recommend to call the loadFromConfigFile() method at the start of your application from the Application class.

After the above steps, your Application class must look like this.

import android.app.Application;
import com.oracle.cx.mobilesdk.persistent.ORACoreDataContainer;
public class TestApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        //This method initializes the SDK
        ORABaseDataCollector.setApplication(this);
        //This code helps to load oracle.json file to the SDK
        ORACoreDataContainer container = new ORACoreDataContainer(this);
        container.loadFromConfigFile();
    }
}

Initializing the Core module

It is mandatory to initialize the Core module, otherwise, all calls to Core module will throw IllegalStateException with an error message.

The Core module can be initialized using one of the below methods. The Core module needs Application context to initialize. There are two ways to pass Application context to the module.

Method 1

Initializing using the ORABaseDataCollector.setApplication() method

ORABaseDataCollector has a static method setApplication(), that accepts android.app.Application as a parameter. This method has to be called before calling any other method in the core module. It is recommended to call this method in the Android application class, which is the starting point of Android application.

Initializing using the ORABaseDataCollector.setApplication() method

import android.app.Application;
import com.oracle.cx.mobilesdk.ORABaseDataCollector;
public class TestApplication extends Application {
 
@Override
public void onCreate() {
super.onCreate();
ORABaseDataCollector.setApplication(this);
}
}

Method 2

Initializing by extending the ORABaseApplication class

The Core module has the ORABaseApplication class, that internally extends the Application class. You can extend your application class from ORABaseApplication also. This class needs to be added to the Android Manifest file.

Initializing by extending the ORABaseApplication class

import com.oracle.cx.mobilesdk.ORABaseApplication;
package com.sample.testapp;
public class TestApplication extends ORABaseApplication {
 
@Override
public void onCreate() {
super.onCreate();
}
}

Updating the AndroidManifest.xml

You should update your AndroidManifest.xml file to add the details of the Test Application.

Updating the AndroidManifest.xml

<manifest xmlns: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>

Enable logging settings

The Core module provides a logging framework that allows developers to easily create logs for testing and debugging your mobile application.

When logging is enabled, the Core module generates log statements for the executed code. These logs can be used to analyze the application flow when you run into issues with the execution. The logs are categorized into different buckets.

Below are the different log levels used in the SDK:

The ORALogger class provides the necessary methods to enable or disable the logs.

The setLogLevel method is used to set the log level. When the log level is set, it will show the log messages for that level as well as the logs for all the levels lower in the list.

For example if you set log level INFO, it will collect the logs for INFO, WARN, and ERROR levels. The default log level is set as DEBUG. If you want to disable all the log messages, set the log level to NONE.

Set Log Level

ORALogger.setLogLevel(ORALogger.INFO);

The Core module is now configured and now we can start configuring the product modules.

Behavior data tracking

To enable behavior data tracking and transfer, the following settings must be configured in the Core module. These settings must be added to the oracle.json file.

After adding the above, your oracle.json will look like the following:

{
    "config_version": "1.0",
    "ORACORE": {
        "ora_dc_end_point_config": [
            {
                "ora_dc_collection_url": "https://dc.oracleinfinity.io/v3/",
                "ora_dc_account_guid": "your_account_guid",
                "ora_dc_retry_count": "2"
            }
        ],
        "ora_dc_send_interval_millis": "10000"
    }
}

Replace the "your_account_guid" in the above snippet, with the id from your account. The "your_account_guid" could be found in the Infinity portal in your profile drop-down as highlighted in amber below.

This section guides the developers on capturing and triggering events and pausing/resuming event capture.

The Core module has convenience methods that help to trigger events to capture behavior data. A sample snippet of the triggerEvent() method to capture behavior data given here for reference.

Trigger 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. Some of the convenience methods require additional arguments, which will be detailed in the relevant sections of the document. The triggerEvent() method helps to track events, batch them and store them on the local database. Based on the configuration set for the Core module, the events are transmitted to the data collection servers. If the carrier signal is not available during the transmission process, the Core module can be configured to store the events locally.

Real-time event tracking

The Core module can be used to capture events and transmit them in real time. The triggerEventImmediately() method can be used to transmit the event immediately after capturing it. If the carrier signal is not available during the transmission process, the Core module can be configured to store the events locally.

Trigger Event Immediately

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

Tracking events automatically

The Core module can be configured to capture certain types of events automatically. These types of events include mobile application life-cycle events such as app start event, app background events and so on. The activity from the time an app is launched and enters into a device's memory to when it is exited and released from memory is referred to as the app's lifecycle. The events in the app's lifecycle can be captured automatically by enabling configuration in the Core module. Some of the sample parameters for tracking the events automatically are as follows:

• APP_START_AUTO_ENABLED (ora_dc_app_start_auto_enabled)

• FOREGROUND_AUTO_ENABLED(ora_dc_foreground_auto_enabled)

• ACTIVITY_AUTO_ENABLED(ora_dc_activity_auto_enabled)

• ERROR_AUTO_ENABLED(ora_dc_error_auto_enabled)

• FRAGMENT_AUTO_ENABLED(ora_dc_fragment_auto_enabled)

• PUSH_AUTO_ENABLED(ora_dc_push_auto_enabled)

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

Now the Core module is ready for starting to track events in the mobile application.