Encrypted Storage

By default, all the data stored by the SDK on the device is inside the application sandbox. This prevents other applications from accessing the data(both read and write). Due to compliance standards or any other use cases, you might want additionally encrypt the data stored on the SDK.

Keychain Set Up

To ensure the encryption works as expected, follow the below steps to set up the Keychain Sharing.

Turn on Keychain sharing in Xcode with the below steps: a. Select your app target and click the Signing & Capabilities tab. b. Turn on the Keychain Sharing capability.
Specify the Keychain group name
App ID Prefix and Keychain group name: Xcode automatically prefixes keychain groups with your team ID. This ensures that your groups are specific to your development team. In order to see how it works, click on the .entitlements file and look at the value of the Keychain Access Groups array.
Get your AppID: The App ID Prefix (also called Team ID) is a unique text identifier associated with your Apple developer account that allows the sharing of keychain and pasteboard items between your apps. Assume the AppID is AB123CDE45, Keychain group name is AB123CDE45.com.example.sharedItems. Pass the same keychain group name to the SDK in the step below.

Enabling Encryption

Enable storage encryption using the initialization method your app implements.

Config-Based Initialization
Manual Initialization

Return to the MoEngage config generator and generate your configuration again with storage encryption turned on:

Select Storage and Network Encryption at the features step, along with the modules you already use.
Under Security, set Enable Storage Encryption to Yes and enter your Keychain Group Name.
Select Generate the code, then replace the MoEngage dictionary in your Info.plist with the new output.

Regenerate rather than adding the keys by hand. Your dictionary already carries them, so pasted copies leave two entries for the same key. See Config-Based Initialization.

Set the storageConfig and keyChainConfig properties on your MoEngageSDKConfig object before you initialize the SDK.

let sdkConfig = MoEngageSDKConfig(appId: "YOUR_WORKSPACE_ID", dataCenter: DATA_CENTER)
sdkConfig.storageConfig = MoEngageStorageConfig(encryptionConfig: MoEngageStorageEncryptionConfig(isEncryptionEnabled: true))
sdkConfig.keyChainConfig = MoEngageKeyChainConfig(groupName: "AB123CDE45.com.example.sharedItems")

MoEngageSDKConfig *sdkConfig = [[MoEngageSDKConfig alloc] initWithAppId:@"YOUR_WORKSPACE_ID" dataCenter:DATA_CENTER];
sdkConfig.storageConfig = [[MoEngageStorageConfig alloc] initWithEncryptionConfig:[[MoEngageStorageEncryptionConfig alloc] initWithIsEncryptionEnabled:YES]];
sdkConfig.keyChainConfig = [[MoEngageKeyChainConfig alloc] initWithGroupName:@"AB123CDE45.com.example.sharedItems"];

NoteOnce storage encryption is enabled and a build is released to production(App Store), you should not disable encryption. Disabling the encryption after the build is released will result in a new user being created in the MoEngage system when the user updates the application.

When storage encryption is enabled, you must pass a valid keychain group to MoEngageKeyChainConfig. If the keychain group is missing or your app is not configured with the matching Keychain Sharing capability, the SDK throws a fatal exception and crashes the app in DEBUG builds. In release builds, storage encryption fails to initialize and the SDK falls back to unencrypted storage.
If these DEBUG validations crash your app while you upgrade, call MoEngageSDKCore.sharedInstance.disableIntegrationValidator() before initializing the SDK to opt out temporarily. Remove the call once the issues are fixed.

Encrypted Network Communication

By default, we use HTTPS protocol for all requests made from the SDK; HTTPS encrypts the requests by default. MoEngage SDK optionally adds another layer of encryption apart from the encryption done by HTTPS.

Enabling Encryption

Enable network encryption using the initialization method your app implements. Provide the keys for both the TEST and LIVE environments.

Config-Based Initialization
Manual Initialization

Return to the MoEngage config generator and generate your configuration again with network encryption turned on:

Select Storage and Network Encryption at the features step, along with the modules you already use.
Under Security, set Enable Network Encryption to Yes and enter the encryption keys for both environments.
Select Generate the code, then replace the MoEngage dictionary in your Info.plist with the new output.

Regenerate rather than adding the keys by hand. Your dictionary already carries them, so pasted copies leave two entries for the same key. See Config-Based Initialization.

Set the networkConfig.dataSecurityConfig property on your MoEngageSDKConfig object before you initialize the SDK.

let sdkConfig = MoEngageSDKConfig(appId: "YOUR_WORKSPACE_ID", dataCenter: DATA_CENTER)
sdkConfig.networkConfig = MoEngageNetworkRequestConfig(dataSecurityConfig: MoEngageNetworkDataSecurityConfig(isEncryptionEnabled: true, encryptionKeyDebug: "YOUR_TEST_ENVIRONMENT_ENCRYPTION_KEY", encryptionKeyRelease: "YOUR_LIVE_ENVIRONMENT_ENCRYPTION_KEY"))

MoEngageSDKConfig *sdkConfig = [[MoEngageSDKConfig alloc] initWithAppId:@"YOUR_WORKSPACE_ID" dataCenter:DATA_CENTER];
sdkConfig.networkConfig = [[MoEngageNetworkRequestConfig alloc] initWithDataSecurityConfig:[[MoEngageNetworkDataSecurityConfig alloc] initWithIsEncryptionEnabled:YES encryptionKeyDebug:@"YOUR_TEST_ENVIRONMENT_ENCRYPTION_KEY" encryptionKeyRelease:@"YOUR_LIVE_ENVIRONMENT_ENCRYPTION_KEY"]];

Note

When using encrypted network communication, we strongly recommend you enable Storage encryption as well.
Adding the above dependency and enabling the flag isn’t enough for this feature to work; there is some additional configuration required on our side to enable this feature completely. In case you want to use this feature, reach out to your account manager or the MoEngage Support team.

When network encryption is enabled, you must provide non-empty values for both EncryptionEncodedTestKey and EncryptionEncodedLiveKey. The consequence of a missing key for the active environment depends on your initialization method:

Config-based initialization: the whole MoEngage dictionary is invalid. The SDK does not initialize, in any build configuration, and the first MoEngage API call hits a fatalError.
Manual initialization: an empty key throws a fatal exception and crashes the app in DEBUG builds. In release builds, network requests fall back to standard HTTPS without the additional encryption layer.

SDKs

Add-On Security

Encrypted Storage

Keychain Set Up

Enabling Encryption

Encrypted Network Communication

Enabling Encryption