Configuration
The Configuration extension is built into the Mobile Core extension. It provides several different APIs for you to setup the configuration either remotely in the Data Collection UI or locally.
Configure with App ID per environment
When you configure a mobile property, a unique environment ID is generated that the SDK uses to retrieve your configuration. This ID is generated when an app configuration is created and published to a given environment. The app is first launched and then the SDK retrieves and uses this Adobe-hosted configuration.
As best practice, you should configure a mobile property in the Data Collection UI and use environment IDs to configure your application. Follow the steps in the tutorial on setting up a mobile property if you need to create a new Experience Platform App.
After the configuration is retrieved when the app is initially launched, the configuration is stored in local cache. The SDK tries to refresh the configuration every cold launch or when a new session is detected. If there is no change or a network request error occurs while downloading the configuration file, the cached configuration will be used.
The unique environment ID from the Data Collection UI can be configured with the SDK using the following:
Swift
Syntax
Copied to your clipboardstatic func configureWith(appId: String)
Example
Copied to your clipboardMobileCore.configureWith(appId: "1423ae38-8385-8963-8693-28375403491d")
Objective-C
Syntax
Copied to your clipboard+ (void) configureWithAppId: (NSString* appId);
Example
Copied to your clipboard[AEPMobileCore configureWithAppId: @"1423ae38-8385-8963-8693-28375403491d"];
Alternatively, you can also place the environment ID in your iOS project's Info.plist with the ADBMobileAppID key. When the SDK is initialized, the environment ID is automatically read from the Info.plist file and the associated configuration.
Java
Syntax
Copied to your clipboardpublic static void configureWithAppID(@NonNull final String appId);
Example
Copied to your clipboardMobileCore.configureWithAppId("1423ae38-8385-8963-8693-28375403491d");
Swift
Syntax
Copied to your clipboardstatic func configureWith(appId: String)
Example
Copied to your clipboardMobileCore.configureWith(appId: "1423ae38-8385-8963-8693-28375403491d")
Objective-C
Syntax
Copied to your clipboard+ (void) configureWithAppId: (NSString* appId);
Example
Copied to your clipboard[AEPMobileCore configureWithAppId: @"1423ae38-8385-8963-8693-28375403491d"];
Alternatively, you can also place the environment ID in your iOS project's Info.plist with the ADBMobileAppID key. When the SDK is initialized, the environment ID is automatically read from the Info.plist file and the associated configuration.
Programmatic updates to configuration
You can also update the configuration programmatically by passing configuration keys and values to override the existing configuration.
Keys that are not found on the current configuration are added when this method is followed. Null values are allowed and replace existing configuration values.
Do not use this API to update the build.environment or any key with an environment prefix, because it can lead to unexpected behavior. For more information, read Environment-aware configuration properties.
Swift
Syntax
Copied to your clipboard@objc(updateConfiguration:)static func updateConfigurationWith(configDict: [String: Any])
Example
Copied to your clipboardlet updatedConfig = ["global.privacy":"optedout"]MobileCore.updateConfigurationWith(configDict: updatedConfig)
Objective-C
Syntax
Copied to your clipboard+ (void) updateConfiguration: (NSDictionary* __nullable) config;
Example
Copied to your clipboardNSDictionary *updatedConfig = @{@"global.privacy":@"optedout"};[AEPMobileCore updateConfiguration:updatedConfig];
Java
Syntax
Copied to your clipboardpublic static void updateConfiguration(@NonNull final Map<String, Object> configMap);
Example
Copied to your clipboardHashMap<String, Object> data = new HashMap<String, Object>();data.put("global.privacy", "optedout");MobileCore.updateConfiguration(data);
Swift
Syntax
Copied to your clipboard@objc(updateConfiguration:)static func updateConfigurationWith(configDict: [String: Any])
Example
Copied to your clipboardlet updatedConfig = ["global.privacy":"optedout"]MobileCore.updateConfigurationWith(configDict: updatedConfig)
Objective-C
Syntax
Copied to your clipboard+ (void) updateConfiguration: (NSDictionary* __nullable) config;
Example
Copied to your clipboardNSDictionary *updatedConfig = @{@"global.privacy":@"optedout"};[AEPMobileCore updateConfiguration:updatedConfig];
Clearing programmatic updates to the configuration
You can clear any programmatic updates made to the configuration via the clearUpdatedConfiguration API. This will clear programmatic updates to configuration made via the updateConfiguration(configMap)(Android)/ updateConfigurationWith(configDict:)(iOS) API. It will also clear any updates to the MobilePrivacyStatus(Android)/ PrivacyStatus(iOS) made via setPrivacyStatus(privacyStatus)(Android)/ setPrivacyStatus(_ status:)(iOS).
For implementation details, please refer to Configuration API reference.
Using a bundled file configuration
Applications which need to get data from the SDK early in the application lifecycle should use a bundled file configuration. This will allow the SDK to properly process events before a remote configuration is downloaded, using the bundled configuration in early, app launch scenarios. If you are going to use a bundled file configuration to help with early app processing, it is strongly recommended that you also use bundled rules.
Please note that the configuration that is downloaded by using the Configure with App ID per environment approach, will overwrite the bundled configuration once it is downloaded, allowing you to always keep a more up-to-date configuration remotely, without needing an app update.
To use a bundled configuration, follow the steps below:
- Download your JSON configuration file from the following URL: https://assets.adobedtm.com/PASTE-ENVIRONMENT-ID.json, replacing PASTE-ENVIRONMENT-ID with your mobile property environment ID.
- Rename the JSON file to “ADBMobileConfig.json”.
- iOS: Place the file anywhere that it is accessible in your app bundle. Android: Place the file in the assets folder.
You can also load a different ADBMobileConfig.json file by using the ConfigureWithFileInPath method. The Adobe Experience Platform SDKs will attempt to load the file from the given path and parse its JSON contents. Previous programmatic configuration changes that were set by using the UpdateConfiguration method are applied on the bundled file's configuration before setting the new configuration to the Adobe Experience Platform SDKs. If a file-read error or JSON parsing error occurs, no configuration changes are made.
To pass in a bundled path and file name:
Java
Syntax
Copied to your clipboardpublic static void configureWithFileInPath(@NonNull final String filePath)
Example
Copied to your clipboard// Case 1: to use ADBMobileConfig.json in the assets folder// No code is needed// Case 2: to use a config json from a absolute path:MobileCore.configureWithFileInPath("absolute/path/to/exampleJSONfile.json");// Case 3: to use a config json in Assets folderMobileCore.configureWithFileInAssets("exampleJSONfile.json");
Swift
Syntax
Copied to your clipboardstatic func configureWith(filePath: String)
Example
Copied to your clipboardlet filePath = Bundle.main.path(forResource: "ExampleJSONFile", ofType: "json")if let filePath = filePath {MobileCore.configureWith(filePath: filePath)}
Objective-C
Syntax
Copied to your clipboard+ (void) configureWithFilePath: (NSString* __nullable) filepath;
Example
Copied to your clipboardNSString *filePath = [[NSBundle mainBundle] pathForResource:@"ExampleJSONFile" ofType:@"json"];[AEPMobileCore configureWithFilePath: filePath];
Java
Syntax
Copied to your clipboardpublic static void configureWithFileInPath(@NonNull final String filePath)
Example
Copied to your clipboard// Case 1: to use ADBMobileConfig.json in the assets folder// No code is needed// Case 2: to use a config json from a absolute path:MobileCore.configureWithFileInPath("absolute/path/to/exampleJSONfile.json");// Case 3: to use a config json in Assets folderMobileCore.configureWithFileInAssets("exampleJSONfile.json");
Swift
Syntax
Copied to your clipboardstatic func configureWith(filePath: String)
Example
Copied to your clipboardlet filePath = Bundle.main.path(forResource: "ExampleJSONFile", ofType: "json")if let filePath = filePath {MobileCore.configureWith(filePath: filePath)}
Objective-C
Syntax
Copied to your clipboard+ (void) configureWithFilePath: (NSString* __nullable) filepath;
Example
Copied to your clipboardNSString *filePath = [[NSBundle mainBundle] pathForResource:@"ExampleJSONFile" ofType:@"json"];[AEPMobileCore configureWithFilePath: filePath];
Environment-aware configuration properties
Some extension developers might use different configuration values based on their environment, and the generated configuration might have several entries for the same property. For example, the Adobe Campaign Standard extension has different endpoints for development, staging, and production servers. Here is an example of a raw configuration that supports multiple build environments:
Copied to your clipboard{"myExtension.server": "mydomain.com","__dev__myExtension.server": "mydomain.dev.com","__stage__myExtension.server": "mydomain.stage.com"}
Each time a remote configuration is generated in the Data Collection UI, a build.environment value is set. This value is based on the environment that you are publishing. When the remote configuration is downloaded, the Configuration extension considers the value in build.environment and provides only the non-prefixed version for the current environment in the shared state.
Here is a modification of the previous example, which now includes build.environment:
Copied to your clipboard{"build.environment": "dev","myExtension.server": "mydomain.com","__dev__myExtension.server": "mydomain.dev.com","__stage__myExtension.server": "mydomain.stage.com"}
Here is the resulting shared state from the Configuration extension:
Copied to your clipboard{"build.environment": "dev","myExtension.server": "mydomain.dev.com"}
Sample configuration
Here's a sample JSON file for the SDK:
Copied to your clipboard{"experienceCloud.org": "3CE342C75100435B0A490D4C@AdobeOrg","target.clientCode": "yourclientcode","target.timeout": 5,"audience.server": "omniture.demdex.net","audience.timeout": 5,"analytics.rsids": "mobilersidsample","analytics.server": "obumobile1.sc.omtrdc.net","analytics.aamForwardingEnabled": false,"analytics.offlineEnabled": true,"analytics.batchLimit": 0,"analytics.backdatePreviousSessionInfo": false,"global.privacy": "optedin","lifecycle.sessionTimeout": 300,"rules.url": "https://link.to.rules/test.zip"}
