Integrate the mParticle Android SDK before starting with MoEngage Kit Integration. Refer to the developer documentation and Kit integration documentation for more information. Skip this step if mParticle Android SDK is already integrated into the application.
MoEngage Kit Integration
SDK Installation
Installing using Catalog
Integrating MoEngage SDK using a Version Catalog is the recommended way of integration, refer to the Configure Version Catalog document to configure a catalog if not done already. Once you have configured the catalog add the dependency in the app/build.gradle file as shown below
dependencies {
...
implementation("com.moengage:mparticle-android-integration-moengage:$sdkVersion")
implementation("com.mparticle:android-kit-base:5.58.3")
}
replace $sdkVersion with latest kit version
Dependencies Installation
MoEngage SDK depends on the following Jetpack libraries provided by Google for its functioning, make sure you add them if it isn't already present in the application.
implementation("androidx.core:core:1.13.1")
implementation("androidx.appcompat:appcompat:1.6.1")
implementation("androidx.lifecycle:lifecycle-process:2.7.0")
Refer to the Android SDK Configuration documentation to know more about the build config and other libraries used by the SDK.
Configure MoEngage SDK
Get Workspace ID (earlier App ID) from the Settings Page Dashboard --> Settings --> Account --> General and configure the MoEngage SDK in the Application class's onCreate() before initializing the mParticle Kit.
val moEngageBuilder = MoEngage.Builder(this, "WORKSPACE_ID", [YOUR_DATA_CENTER])
MoEngage.configureForDefaultInstance(moEngageBuilder, IntegrationPartner.M_PARTICLE)
MoEngage.Builder moEngageBuilder = new MoEngage.Builder(this, "WORKSPACE_ID", [YOUR_DATA_CENTER]);
MoEngage.configureForDefaultInstance(moEngageBuilder, IntegrationPartner.M_PARTICLE);
Add MoEngage SDK to mParticle SDK
MoEngage Kit needs to be added as a kit during initializing the mParticle SDK.
// 1167 is Unique ID for the MoEngage Kit
val options = MParticleOptions.builder(this)
.credentials("YOU MPARTICLE API KEY", "YOUR MPARTICLE API SECRET")
.configuration(KitOptions().addKit(1167, MoEngageKit::class.java))
.build()
MParticle.start(options)
// 1167 is Unique ID for the MoEngage Kit
MParticleOptions options = MParticleOptions.builder(this)
.credentials(M_PARTICLE_API_KEY, M_PARTICLE_API_SECRET)
.configuration(new KitOptions().addKit(1167, MoEngageKit.class))
.build();
MParticle.start(options);
Exclude MoEngage Storage File from Auto-Backup
The auto backup service of Andriod periodically backs up the Shared Preference file, Database files, and so on.
For more information, refer to Auto Backup.
The backup results in MoEngage SDK identifiers to be backed up and restored after re-install.
The restoration of the identifier results in your data being corrupted and the user not being reachable using push notifications.
To ensure data is not corrupted after a backup is restored, opt out of MoEngage SDK storage files.
Refer to the Exclude MoEngage Storage File from Auto-Backup document to configure this.
Handling Push Notifications
Copy the Server Key from the FCM console and add it to the MoEngage Dashboard (Not sure where to find the Server Key refer to Getting FCM Server Key). To upload it, navigate to MoEngage Dashboard --> Settings --> Channel --> Push --> Mobile Push --> Android and add the Server Key and package name.
warning |
Important Ensure you add the keys both in the Test and Live environment. |
Adding metadata for push notification
Metadata regarding the notification is required to show push notifications where the small icon and large icon drawable are mandatory.
For more information about API references for all the possible options, refer to NotificationConfig.
Use the configureNotificationMetaData() to transfer the configuration to the SDK.
val moEngageBuilder = MoEngage.Builder(this, "WORKSPACE_ID", [YOUR_DATA_CENTER])
.configureNotificationMetaData(NotificationConfig(R.drawable.small_icon, R.drawable.large_icon))
MoEngage.configureForDefaultInstance(moEngageBuilder, IntegrationPartner.M_PARTICLE)
MoEngage.Builder moEngageBuilder = new MoEngage.Builder(this, "WORKSPACE_ID", [YOUR_DATA_CENTER])
.configureNotificationMetaData(new NotificationConfig(R.drawable.small_icon, R.drawable.large_icon));
MoEngage.configureForDefaultInstance(moEngageBuilder, IntegrationPartner.M_PARTICLE);
Ensure that the SDK is configured with the metadata in the onCreate() of the Application class for push notifications to work.
info |
Notification Small Icon Guidelines Notification small icon should be flat, pictured face on, and must be white on a transparent background. |
Configuring Firebase Cloud Messaging
Configuring with mParticle SDK
mParticle SDK provides a way to handle the registration of push token and receive push notifications at the mParticle SDK. Refer Push integration doc for the configuration option.
Configuring with MoEngage SDK or with Application
Check the MoEngage Push integration doc to configure the FCM with MoEngage SDK or if you want to handle it independently.
For more information on features provided in MoEngage Android SDK refer to the following links:
mParticle SDK Usage
Refer to the developer documentation for detailed usage.
User Management
Check IDSync documentation from the mParticle developer integration document to manage the user state in the application.
Event Tracking
Use logEvent to track the custom and commerce events from mParticle SDK. mParticle SDK will send the event to MoEngage Kit (if configured from mParticle Dashboard) with associated profiles.
User Attribute Tracking
mParticle SDK provides setUserAttributeList to set the user attributes. Either you can set the mParticle standard attributes or custom attributes both are passed to MoEngage Kit and mapped accordingly at MoEngage SDK.
Sample Implementation
Refer to this GitHub repository for a sample implementation