Setting Core Configuration

Configurations are the settings for the module to work. Settings are either mandatory or optional. In this topic, we explain how to set configurations in the Oracle CX Core SDK, and their corresponding functions. These configurations can also determine how to store configurations from other modules.

Oracle CX Core SDK Configuration Settings

If you integrate the library using the recommended settings, you should not need to make any modifications beyond specifying the END_POINT_CONFIG. However, you can use the documented configuration settings to customize the operations of the Oracle CX Core SDK. Configuration information for the library is stored as strings starting with ora_dc_ in the oracle.json file and settable programmatically using the putValue() method. All settings are stored as strings and all keys are defined as constants in the ORABaseConfigKeys.

There are two ways to set config settings:

1. Using oracle.json file

Setting configurations can be done at design time by using the oracle.json file. In addition to the required settings in this file (such as END_POINT_CONFIG), you may add entries for any of the config settings. Simply edit the oracle.json file and set the key to the chosen config key and the value to an appropriate value. This oracle.json file should be added in application's assets folder.

For example, to configure the SDK to only send events when the device is connected to wifi, add this entry to the json file:

{
"config_version": "1.0",
"ORACORE": {
"ora_dc_end_point_config": [
{
"ora_dc_collection_url": "https://dc.oracleinfinity.io/v3/",
"ora_dc_account_guid": "abcd1234xy",
"ora_dc_retry_count": 2
}
],
"ora_dc_only_send_over_wifi": `true`
}
}

In above json file, there are two configurations are added. One is ora_dc_end_point_config which is mandatory to work with Oracle CX Core SDK. The value for this key is a json array string. The other configuration is ora_dc_only_send_over_wifi which is optional and its value is boolean string. You can add as many configs based on your requirement.

Once the oracle.json file is added to assets folder, to load that file to SDK, you need to call loadFromConfigFile() method as below.

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

Structure of oracle.json file

Below is the skelton of oracle.json file

{
"config_version": "version in x.y format",
"MODULE_ONE_ID": {
"module1_key1": "value1",
"module1_key2": "value2"
},
"MODULE_TWO_ID": {
"module2_key1": "value1",
"module2_key2": "value2"
}
}

config_version

The first entry in the oracle.json should be config_version. The json must and should contain this key. The value for this is a decimal number in x.y format.

This config_version value plays an important role while updating/modifying the oracle.json key/values. When you want to update any configuration value, the config_version value should be increased. If the config_version value is increased to higher than earlier version then only the new config value will be stored.

For example current value for config_version is 1.0, and the value for module1_key1 is value1. If you want to change the module1_key1 value to value2, you also need to change the config_version to 1.1. If the config_version is not incremented, the new config value will not be stored.

After the config_version, you need to place the module's config data. Each module will have its own module id. That modules config data will be added under that module id.

ORACORE is the module id for Oracle CX Core SDK. All core related configurations should go under this module id. You can add any number of the module's configurations to the oracle.json file.

Once module id and its related configs are added to the oracle.json file, you need to call the loadFromConfigFile() with respective container instance.

For example to load core config data from oracle.json, you need to call coredataContainer.loadFromConfigFile() method.

2. Setting Configuration Programmatically

Here we see how to set configuration settings programmatically in core module. In Oracle CX Core SDK we have given a configuration class ORACoreDataContainer and Enum ORABaseConfigSettings class which provides list of configurations available in SDK.

To set config settings within your app, you can use the putValue() method in the ORACoreDataContainer class. The method takes a key and a value to store.

Here are the steps and example to setting the configurations. battery threshold config value:

  1. Create object for ORACoreDataContainer.
  2. To set/update config, call ORACoreDataContainer.putValue(final IORAConfigSetting key, final String value)
  3. To get config, call ORACoreDataContainer.getValue(IORAConfigSetting key)

Here is the example to setting the battery threshold config value:

// Set the minimum battery charge percent to 15% and persist the change
ORACoreDataContainer container = new ORACoreDataContainer(context);
container.putValue(ORABaseConfigSettings.BATTERY_MIN_CHG_PERCENT, "15");

Configuration Settings

The following settings control the behavior of the Oracle CX Core SDK. Changing the values associated with any of them will change the behavior of the SDK as explained under each setting’s “Description”.

ENABLED

  • Description: Enables or disables event collection and transmission in the SDK.
  • String Literal: ora_dc_enabled
  • Default Value: true
  • Acceptable Values: boolean as a string — true or false. If this config setting is set to 'false', then the SDK will no longer collect events, store events, send events to servers.

SEND_UNIQUE_ID_ENABLED

  • Description: Controls whether or not a unique ID (from the device) is sent along with every event.
  • String Literal: ora_dc_send_unique_id_enabled
  • Default Value: true
  • Acceptable Values: boolean as a string — true or false

MAX_PERSISTED_EVENTS

  • Description: The maximum number of events to store locally on the device. If new events are generated while the event store is full, the oldest events will be permanently deleted.
  • String Literal: ora_dc_event_table_size_maximum
  • Default Value: "5000"
  • Acceptable Values: integer as a string — (Any valid positive integer value)

SEND_INTERVAL_MILLIS

  • Description: Time (in milliseconds) between stored events being transmitted to the data collection servers. If no events are queued, nothing is transmitted and new send event is scheduled.
  • String Literal: ora_dc_send_interval_millis
  • Default Value: "60000"
  • Acceptable Values: integer as a string — (any valid positive integer value)

AUTO_SEND_THRESHOLD_PERCENT

  • Description: Percentage of the event store capacity (defined in the Max Persisted Events configuration setting) at which events will be automatically sent to the data collection servers. This setting expects an integer from 0 to 100, inclusive.
  • String Literal: ora_dc_auto_send_threshold_percent
  • Default Value: "80"
  • Acceptable Values: integer as a string — (an integer from "0" to "100" inclusive)

EVENTS_PER_SEND

  • Description: Events are collected and sent in batches to the data collection servers. This setting controls the number of events to send in a single batch.
  • String Literal: ora_dc_event_send_maximum
  • Default Value: "250"
  • Acceptable Values: integer as a string — (an integer from "1" to "250" inclusive)

END_POINT_CONFIG

  • Description: The collection end point config data. The config data should be the valid JSON array format.
  • String Literal: ora_dc_end_point_config
  • Default Value: []
  • Acceptable Values: A valid JSON array string in the below format [{ "ora_dc_collection_url": "https://dc.oracleinfinity.io/v3/", "ora_dc_account_guid": "horuts00i6", "ora_dc_retry_count": "2" }] ora_dc_collection_url: a valid URL string including the protocol(http:// or https://) ora_dc_account_guid: Account GUID string ora_dc_retry_count: Retry count if any error occurs 'ora_dc_collection_url' & 'ora_dc_account_guid' are mandatory fields. Other fields if you don't pass default values will be taken.

HTTP_CONNECT_TIMEOUT_MILLIS

  • Description: Controls the maximum amount of time (in milliseconds) to pass before abandoning a Oracle SDK-related HTTP request.
  • String Literal: ora_dc_http_connect_timeout_millis
  • Default Value: "10000"
  • Acceptable Values: integer as a string — (any valid positive integer value)

HTTP_READ_TIMEOUT_MILLIS

  • Description: Controls the maximum amount of time to wait (in milliseconds) for a response from a Oracle SDK-related HTTP connection.
  • String Literal: ora_dc_http_read_timeout_millis
  • Default Value: "30000"
  • Acceptable Values: integer as a string — (any valid positive integer value)

BATTERY_CHECK_MILLIS

  • Description: Controls how often (in milliseconds) the battery should be checked for sufficient capacity to transmit events to data collection. In an Android environment, checking the battery can in itself drain the battery further. For this reason, this setting should be set sufficiently high to avoid undue battery use.
  • String Literal: ora_dc_battery_check_millis
  • Default Value: "300000" (5 minutes)
  • Acceptable Values: integer as a string — (Any valid positive integer value)

BATTERY_MIN_CHG_PERCENT

  • Description: Controls at what battery level to stop event transmission. When the battery level falls below this level, event transmission to the data collection servers is disabled. After Android reports that battery power is restored to a level above this threshold, event transmission will resume.
  • String Literal: ora_dc_battery_min_charge_percent
  • Default Value: "20"
  • Acceptable Values: integer as a string — representation of any integer between "0" and "100", inclusive.

REFERRER_CHECK_TIMEOUT_MILLIS

  • Description: Specifies how long (in milliseconds) the data collector will wait for the Android Play Store to send the REFERRER after application installation and launch.
  • Default Value: "5000" (5 seconds)
  • Acceptable Values: *integer as a string* — representation of an integer

MAX_SESSION_MILLIS

  • Description: Controls the maximum amount of time (in milliseconds) to wait before forcing a new session to start.
  • String Literal: ora_dc_max_session_millis
  • Default Value: "28800000" (8 hours)
  • Acceptable Values: integer as a string — (any valid positive integer value)

SESSION_TIMEOUT_MILLIS

  • Description: Controls the maximum amount of time (in milliseconds) since the last event before forcing a new session to start.
  • String Literal: ora_dc_session_timeout_millis
  • Default Value: "1800000" (30 minutes)
  • Acceptable Values: integer as a string — (any valid positive integer value)

APP_NAME

  • Description: Contains the application name of your app. If present, this value will be used in lieu of context.getApplicationInfo().labelRes
  • String Literal: ora_dc_app_name
  • Default Value: none
  • Acceptable Values: string — Any string

APP_VERSION

  • Description: Contains the application version of your app. If present, this value will be used in lieu of context.getPackageManager().getPackageInfo(context.getPackageName())
  • String Literal: ora_dc_app_version
  • Default Value: none
  • Acceptable Values: string — Any string

ONLY_SEND_OVER_WIFI

  • Description: Controls whether events are sent when wifi is unavailable.
  • String Literal: ora_dc_only_send_over_wifi
  • Default Value: false
  • Acceptable Values: boolean as a string — true or false

REPORT_LOCATION_ENABLED

  • Description: When enabled (and CoreLocation services in the application are enabled), sends geo location coordinates with every event. In order to receive location updates from NETWORK_PROVIDER or GPS_PROVIDER, you must request user permission by declaring either the ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION permission, respectively, in your Android manifest file. The SDK will not request authorization unilaterally. It will only use this information if it is already authorized in your application.
  • String Literal: ora_dc_report_location_enabled
  • Default Value: false
  • Acceptable Values: boolean as a string — true or false

MASK_IP_ENABLED

  • Description: Enable/Disable masking the IP address of the mobile client. When set to true (enabled), the dcsipa parameter will be set to "1" on every event. The collection servers use this setting to mask the IP address. For IPv4, only the first three octets will be recorded, with the last octet set to 000. For IPv6, the last octet will also be set to 0.
  • String Literal: ora_dc_mask_ip_enabled
  • Default Value: false
  • Acceptable Values: boolean as a string — true or false

EXTRA_PARAMS

  • Description: Extra key/value pairs (parameters) that are passed as part of the payload of every event. If set, these key/value pairs will be sent along with every event. Format the query parameters as valid JSON e.g.: {foo:bar,fee:fum}. You may alternatively use quoted strings {"foo":"bar","fee":"fum"}, but the quotes will be ignored when read from the config settings. If you will be using complex strings, such as those containing spaces, you must escape-quote the strings: {\"This string\\":\"contains multiple words, separated by spaces\\","fee":"fum"}.
  • String Literal: ora_dc_extra_params
  • Default Value: empty string
  • Acceptable Values: comma separated key=value string formatted as JSON {"key1":"value1","key2":"value2",...} If values are set in this setting and key/value pairs with the same keys (name collision) are passed in using the ORAConfigSetting.EXTRA_PARAMS.setValue() method: parameter, the customParams will take precedence over values in this setting. All keys in key-value pairs will be cast to lower case automatically. The values will remain in the case in which they are set.

IMMEDIATE_EVENT_STORING_ENABLED

  • Description: Enable/Disable immediate event storing. When set to 'true' (enabled), the event is storing in database when internet connection is missing or battery level is low. When set to 'false' (disabled), the event should not be saved in database and should be sent immediately. To trigger event immediate need to call ORABaseDataCollector.getInstance(getContext()).triggerEventImmediately(...) method.
  • String Literal: ora_dc_immediate_event_storing_enabled
  • Default Value: true
  • Acceptable Values: boolean as a string — true or false

APP_START_AUTO_ENABLED

  • Description: Controls whether or not app start and terminate events will be logged automatically.
  • String Literal: ora_dc_app_start_auto_enabled
  • Default Value: true
  • Acceptable Values: boolean as a string — true or false

ERROR_AUTO_ENABLED

  • Description: Controls whether or not application error events will be logged automatically.
  • String Literal: ora_dc_error_auto_enabled
  • Default Value: true
  • Acceptable Values: boolean as a string — true or false

ACTIVITY_AUTO_ENABLED

  • Description: Controls whether or not activity lifecycle events will be logged automatically. See the [Automatic Events Guide][AutoEvents] for more details on automatic events.
  • String Literal: ora_dc_activity_auto_enabled
  • Default Value: true
  • Acceptable Values: boolean as a string — true or false

FRAGMENT_AUTO_ENABLED

  • Description: Controls whether or not fragment lifecycle events will be logged automatically. See the [Automatic Events Guide][AutoEvents] for more details on automatic events.
  • String Literal: ora_dc_fragment_auto_enabled
  • Default Value: true
  • Acceptable Values: boolean as a string — true or false

PUSH_AUTO_ENABLED

  • Description: Controls whether or not push notification events will be logged automatically. See the [Automatic Events Guide][AutoEvents] for more details on automatic events.
  • String Literal: ora_dc_push_auto_enabled
  • Default Value: true
  • Acceptable Values: boolean as a string — true or false

FOREGROUND_AUTO_ENABLED

  • Description: Controls whether or not app foreground and background events will be logged automatically. See the [Automatic Events Guide][AutoEvents] for more details on automatic events.
  • String Literal: ora_dc_foreground_auto_enabled
  • Default Value: true
  • Acceptable Values: boolean as a string — true or false

SEND_SCREEN_VIEW_WITH_ACTIVITY_VIEW_ENABLED

  • Description: Enable/Disable sending a screen View event along with every automatic activity event. This only applies when automatic events are enabled.
  • String Literal: ora_dc_send_screen_view_with_activity_view_enabled
  • Default Value: false
  • Acceptable Values: boolean as a string — true or false

HTTP_THREAD_COUNT

  • Description: The maximum number of threads to be created for handling HTTP requests. If more requests than the number of threads, the remaining requests will be queued and executed after the current process
  • String Literal: ora_dc_http_thread_count
  • Default Value: "2"
  • Acceptable Values: integer as a string — (any valid positive integer value ranges from 1 to 15)

HTTP_BACKGROUND_TASK_ENABLED

  • Description: Controls whether or not HTTP requests are processed when application is in background.
  • String Literal: ora_dc_http_background_task_enabled
  • Default Value: false
  • Acceptable Values: boolean as a string — true or false