Configuration Guide Document

Overview

The purpose of this document is to guide you on adding a new module configuration. The time the document is written it contains only Core and Infinity modules, where

• Core contains the main functionality for storing and sending events to Infinity Data Collection server and any new module should add it as a dependency to communicate to Infinity Data Collector.
• Infinity is a module Oracle should provide to the customers as part of Oracle One SDK(based on the agreement made). It has Core as a build dependency and implements main functionalities for Infinity Mobile Analytics.

Following the instructions described below you can add your own module (similar to Infinity) keeping Oracle CX Core principles.

Creating a new module configuration

A new module can have set of different classes with different features & configurations. If you would like to use the oracle.json file to load your configurations, you must follow Oracle CX Core configuration pattern. To create a new configuration, it is required to create a class which is subclass of ORAConfigSetting and override all of its methods. For complete implementation, please follow the below step by step code Steps.

To load your new configurations into Core SDK persistence store, it is required to create a new class by subclassing ORABaseDataContainer class. Below are the steps.

• Create a new class which is subclass of ORABaseDataContainer
• Override getModuleId & getConfig: methods
• In getModuleId method, return the module id string provided to you. For more info on implementation Get Module ID Implementation
• In getConfig: method, return the ORAConfigSetting class associated with the key passed. Get Config Implementation
• Create an instance of newly created class
• Use putValue:forKey method to persist the data. For more info on implementation Loading data

Steps to follow to persist data

Step 1

Create a new class which is subclass of ORAConfigSetting

• Objective-C
• Swift 5.1

@interface ConfigHTTPBackgroundTaskEnabled : ORAConfigSetting
@end

class ConfigHTTPBackgroundTaskEnabled: ORAConfigSetting {
}				

Override all the methods of ORAConfigSetting

• Objective-C
• Swift 5.1

@implementation ConfigHTTPBackgroundTaskEnabled

- (NSString *)keyDescription {
    return @"This configuration is used whether to run the HTTP request in the app background". //"Human readable form of the class";
}

- (NSString *)keyName {
    return @"http_background_task" //"Hard coded value of the class";
}

- (NSString *)getDefaultValue {
    return @"false";
}

- (BOOL)isValid:(NSString *)value {
    return true;
}
@end			

class ConfigHTTPBackgroundTaskEnabled {
    func keyDescription() -> String? {
        return "This configuration is used whether to run the HTTP request in the app background" //"Human readable form of the class"
    }

    func keyName() -> String? {
        return "http_background_task" //"Hard coded value of the class"
    }

    func getDefaultValue() -> String? {
        return "false"
    }
    
    func isValid(_ value: String?) -> Bool {
        return true
    }
}					

Step 3

Create class which is subclass of ORABaseDataContainer class to interact with put and get methods

• Objective-C
• Swift 5.1

@interface YourDataContainer : ORABaseDataContainer
@end						

class YourDataContainer: ORABaseDataContainer {
}			

Get Module ID implementation

Below is the implementation of getModuleId method

• Objective-C
• Swift 5.1

- (NSString *)getModuleId {
    return @"MY_MODULE_ID";
}					

func getModuleId() -> String? {
    return "MY_MODULE_ID"
}			

Important Note: Module id will allow only alphanumerics. No special characters are allowed. In case of invalid(empty or nil) module id, app will get terminated.

Get Config implementation

Below is the implementation of getConfig: method. You can check all your configurations for the key and return the appropriate ORAConfigSetting class instance.

• Objective-C
• Swift 5.1

Usage of putValue:forKey: and getValueForKey: methods

To persist the configuration in Core SDK, you need to use putValue:forKey: method. The method getValueForKey: will be used to retrieve the value for respective key. To use the above methods, we need to create an instance of YourDataContainer class and call put and get methods. Below is the implementation:

• Objective-C
• Swift 5.1

YourDataContainer *container = [[YourDataContainer alloc]init];
ConfigHTTPBackgroundTaskEnabled *setting = [[ConfigHTTPBackgroundTaskEnabled alloc]init];
[container putValue:@"true" forKey:setting]; 					

var container = YourDataContainer()
var setting = ConfigHTTPBackgroundTaskEnabled()
container.putValue("true", forKey: setting)		

GET

Sample code to get values using your container class

• Objective-C
• Swift 5.1

YourDataContainer *container = [[YourDataContainer alloc]init];
ConfigHTTPBackgroundTaskEnabled *setting = [[ConfigHTTPBackgroundTaskEnabled alloc]init];
NSString *value = [container getValueForKey:setting];

var container = YourDataContainer()
var setting = ConfigHTTPBackgroundTaskEnabled()
var value = container.getValueForKey(setting)			

Load Configurations via oracle.json file

To load Core, Analytics & any other module configurations, we need to use oracle.json file. Below is the structure of oracle.json to load few of the Core & Analytics configurations.

{
    "config_version": "1.0",
    "ORACORE": {
        "ora_dc_end_point_config": [{
            "ora_dc_collection_url": "http://dc.oracleinfinity.io/v3/",
            "ora_dc_account_guid": "your_guid",
            "ora_dc_retry_count": "2"
        }],
        "ora_dc_send_interval_millis": "3000",
        "ora_dc_app_start_auto_enabled": "true"
    },
    "ORAANALYTICS": {
        "ora_dc_video_play_auto_enabled": "true",
        "ora_dc_video_pct_inc": "70"
    }
}			
			

In the above JSON, the keys, ORACORE & ORAANALYTICS are the moduleId's of Core & Analytics respectively. The same keys(moduleIds) will be returned by the above getModuleId method Get Module ID Implementation

Now, to load your custom configurations of your module, you need to update the above oracle.json file with your moduleId key. Below is the sample implementation with moduleId MY_MODULE_ID & configuration key http_background_task

"MY_MODULE_ID": {
      "http_background_task" : "true"
 }

The final oracle.json file with your module configurations will look like:

{
    "config_version": "1.0",
    "ORACORE": {
        "ora_dc_end_point_config": [{
            "ora_dc_collection_url": "http://dc.oracleinfinity.io/v3/",
            "ora_dc_account_guid": "your_guid",
            "ora_dc_retry_count": "2"
        }],
        "ora_dc_send_interval_millis": "3000",
        "ora_dc_app_start_auto_enabled": "true"
    },
    "ORAANALYTICS": {
        "ora_dc_video_play_auto_enabled": "true",
        "ora_dc_video_pct_inc": "70"
    },
    "MY_MODULE_ID": {
        "http_background_task": "true"
    }
}			
			

The first entry in the oracle.json should be config_version. The JSON must 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 key to be incremented. Otherwise, SDK can't load the updated configurations.

For example current value for config_version is 1.0, and the value for http_background_task is "true". If you want to change the http_background_task value to "false", 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.

Once the oracle.json setup is done with your module configurations, we need to use the below code to load the configurations into Core SDK persistent storage.

• Objective-C
• Swift 5.1

YourDataContainer *container = [[YourDataContainer alloc] init];
[container loadConfig];					

var container = YourDataContainer()
container.loadConfig()