Configuration Manager - iOS
Overview
The Core module can be used to manage the configuration for other modules within the Oracle CX Mobile SDK. This section guides you on adding the configuration for a new module in the SDK. The Core module contains the base capability required for all modules within the Oracle CX Mobile SDK such as storing, transmitting events to data collection servers and so on. So any new module in the Oracle CX Mobile SDK must add the Core module as a dependency to leverage those capabilities.
Creating a new module configuration
A new module typically has a set of classes with each class managing different capabilities. You can use the oracle.json file to load your configurations for the module. To create a new configuration for a module, you must first create a subclass of ORAConfigSetting class and override all its methods. The following are steps to create a configuration for a new module:
-
Create a new class which is a subclass of
ORAConfigSetting -
Override all the methods of
ORAConfigSetting -
Create a new class that is a subclass of
ORABaseDataContainer -
Implement
getModuleId&getConfig: methods -
Create an instance of a newly created class & define
putValue:forKeymethod to persist the data
Step 1
Create a new class which is a subclass of ORAConfigSetting
@interface ConfigHTTPBackgroundTaskEnabled : ORAConfigSetting
@end
class ConfigHTTPBackgroundTaskEnabled: ORAConfigSetting {
}
Step 2
Override all the methods of ORAConfigSetting
@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 a new class that is a subclass of ORABaseDataContainer
@interface YourDataContainer : ORABaseDataContainer
@end
class YourDataContainer: ORABaseDataContainer {
}
Step 4
Implement getModuleId & getConfig: methods
Get-Module ID method implementation
- (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
- (ORAConfigSetting *)getConfig:(NSString *)key {
if ([key isEqualToString:@"http_background_task"]) { //the key from the above ConfigHTTPBackgroundTaskEnabled class
return [ConfigHTTPBackgroundTaskEnabled new];
} else if ([key isEqualToString:@"my_config_key_1"]) {
return [MyConfigClassOne new];
} else if ([key isEqualToString:@"my_config_key_2"]) {
return [MyConfigClassTwo new];
}
}
func getConfig(_ key: String?) -> ORAConfigSetting? {
if (key == "http_background_task") {
//the key from the above ConfigHTTPBackgroundTaskEnabled class
return ConfigHTTPBackgroundTaskEnabled()
} else if (key == "my_config_key_1") {
return MyConfigClassOne()
} else if (key == "my_config_key_2") {
return MyConfigClassTwo()
}
}
You can check all your configurations for the key and return the appropriate ORAConfigSetting class instance.
Step 5
Create an instance of newly created class & define putValue:forKey method to persist the data
To persist the configuration in Core module, you need to use putValue:forKey: method. To retrieve the configuration from the Core module, you need to use, getValueForKey: method. Create an instance of YourDataContainer class and call put and get methods.
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)
Retrieving persisted configuration from the Core module
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 any module configurations, we need to use the oracle.json file. The following snippet contains a sample oracle.json file with configuration for the Core, Infinity, and the new modules. In the following JSON, the keys, ORACORE & ORAANALYTICS are the module IDs of Core & Infinity modules respectively. You should use the unique module ID that is returned by the getModuleID() method while adding the configuration to the oracle.json file.
{
"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"
}
}
Once the oracle.json setup is complete with your new module configurations, you can load the configurations into Core module persistent storage with the following code:
YourDataContainer *container = [[YourDataContainer alloc] init];
[container loadConfigFromFile];
var container = YourDataContainer()
container.loadConfigFromFile()
Difference between oracle.json and putValue() method
The oracle.json file is provided to store all modules config data at a centralized place. The config data in this file will be loaded based on the config_version value. The new values updated in the config file will be stored if the config_version value is greater than the previous version. At the same time putValue() method also can be used to modify the config value at run time.
Here the putValue() method has the highest priority than oracle.json. This means, if any config value which is presented in the oracle.json file is updated using the putValue() method, the oracle.json file value will be overridden with the new value.