Skip to main content

​
Overview

The MoEngage Android SDK provides a secure framework for delivering personalized campaigns. It simplifies integration by handling user identity and authentication internally, eliminating the need to manage API secrets or manual HTTPS calls. This allows you to fetch and track personalized campaign info directly through a streamlined, native interface.
PrerequisitesBefore you can fetch personalized experiences, ensure you have completed the following:
  • Ensure you have integrated the BOM into your Android SDK. For more information, refer to Install using BOM.
  • Initialization: Call the SDK initialize() method within your application entry point ( onCreate() on Android. For more information on initialization, refer to SDK Initialization.

​
Integration MoEngage Personalization

To begin using MoEngage Personalization in your application, once you have configured the BOM, add the required artifact in the app/build.gradle file as shown below:
build.gradle.kts(kotlin)
dependencies {
    implementation 'com.moengage:personalization-core'
}

​
Implementation Workflow

The MoEPersonalizeHelper SDK object is designed to simplify the retrieval and interaction with dynamic, personalized content. Below is a breakdown of the code divided by its primary responsibilities.

​
1. Fetch Meta Experience

Ensure you invoke the metadata call prior to fetching a specific payload or experience. You can use this call to fetch all experience keys under the provided status, providing the context necessary to properly configure subsequent requests. 
MoEPersonalizeHelper.fetchExperiencesMeta(
        context = context,
        status = listOf(ExperienceStatus.ACTIVE),
        onSuccess = { metadata ->
            println("Success: $metadata")
        },
        onFailure = { reason, message ->
            println("Failure: $reason")
        }
    )
Ensure you call fetchExperiencesMeta first to retrieve the experience key you need. The onSuccess callback returns an ExperienceCampaignsMetadata object containing all necessary metadata for campaign execution in the main thread. Conversely, the onFailure callback provides a RequestFailureReasonCode and an optional message to identify the specific reason for the request’s failure.

​
2. Fetch Personalized Content

Once the metadata is fetched, you can retrieve the actual personalized payloads. The SDK provides methods to fetch either a single experience or multiple experiences simultaneously.
EXPERIENCE_KEY is the unique key that is used in the experience campaign while creating the campaign on the MoEngage dashboard. You can fetch these keys using the fetchExperiencesMeta call.
// Fetch Single Experience Payload
    MoEPersonalizeHelper.fetchExperience(
        context = context,
        // EXPERIENCE_KEY must be one of the keys returned in the fetchExperiencesMeta call.
        experienceKey = EXPERIENCE_KEY,
        attributes = mapOf("customOptionalAttributeKey" to "customOptionalAttributeValue"),
        onSuccess = { campaignsResult ->
            println("Success: $campaignsResult")
        },
        onFailure = { reason, message ->
            println("Failure: $reason")
        }
    )

    // Fetch Multiple Experience Payload
    MoEPersonalizeHelper.fetchExperiences(
        context = context,
        // EXPERIENCE_KEY must be one of the keys returned in the fetchExperiencesMeta call.
        experienceKeys = setOf("EXPERIENCE_KEYS"),
        attributes = mapOf("customOptionalAttributeKey" to "customOptionalAttributeValue"),
        onSuccess = { campaignsResult ->
            println("Success: $campaignsResult")
        },
        onFailure = { reason, message ->
            println("Failure: $reason")
        }
    )
The onSuccess callback returns an ExperienceCampaignsResult object containing all necessary metadata for campaign execution in the main thread. Conversely, the onFailure callback provides a RequestFailureReasonCode and an optional message to identify the specific reason for the request’s failure. You can fetch :
  • Single Experiences: Retrieve a specific payload using a single experienceKey.
  • Bulk Experiences: Retrieve multiple payloads at once by passing a Set<String> of experienceKeys.
Use Cases: Contextual Targeting: You can pass a map of attributes (e.g., current_page: “home”, cart_value: “500”) during the fetch call. This allows MoEngage SDK to serve real-time, state-dependent content (such as a “Free Shipping” banner when the cart value is high enough).

​
3. Track Impressions

After fetching and rendering the personalized content on the UI, it is essential to track user interactions to measure campaign performance. To measure performance, you must track when an experience is shown. This requires a campaignEntity. You can use these methods to log “Impressions” (experienceShown / experiencesShown) when the UI renders the content.

​
3a. Track Impressions for Experience Campaigns

  // campaignEntity are placeholders for the campaign objects returned by the fetchExperiences function. They contain the metadata and payload required by the SDK to attribute impressions and clicks to the correct campaign.
    MoEPersonalizeHelper.experiencesShown(context, listOf(campaignEntity))
    MoEPersonalizeHelper.experienceShown(context, campaignEntity)

​
3b. Track Impressions for Offering Campaigns

Offerings are specific, personalized items (such as a product recommendation or a coupon) contained within a campaign. 
 // offeringPayload is the specific data object extracted from an campaignEntity using the unique offering key assigned during campaign creation. It enables tracking at the offering campaign, which is essential when an experience contains multiple offerings within a single payload.
    MoEPersonalizeHelper.offeringShown(context, offeringPayload)
    MoEPersonalizeHelper.offeringsShown(
        context,
        listOf(offeringPayload1, offeringPayload2)
    )

​
4. Track Clicks

​
4a. Track Clicks for Experience Campaigns

You can use these methods to log “Clicks” (experienceClicked) when the user interacts with the rendered UI element. 
// campaignEntity are placeholders for the campaign objects returned by the fetchExperiences function. They contain the metadata and payload required by the SDK to attribute impressions and clicks to the correct campaign.
    MoEPersonalizeHelper.experienceClicked(context, campaignEntity)

​
4b. Track Clicks for Offering Campaigns

Offerings are specific, personalized items (such as a product recommendation or a coupon) contained within a campaign. 
// offeringPayload is the placeholder for the specific "Offering" payload extracted from inside a campaignEntity. You can use these objects when you want to track interactions at the individual item level rather than the whole campaign.
    // campaignEntity are placeholders for the campaign objects returned by the fetchExperiences function. They contain the metadata and payload required by the SDK to attribute impressions and clicks to the correct campaign.
    MoEPersonalizeHelper.offeringClicked(
        context,
        campaignEntity,
        offeringPayload
    )
You can use these Offering-specific functions only if the data is part of an offering payload. For all other experience data, use the standard experience shown/clicked functions.
For more information, refer to the API documentation.

​
FAQs

No. The SDK returns raw JSON payloads. You are responsible for parsing the data and building the UI components (e.g., banners or carousels).
No. The SDK does not download or cache media assets. Use a standard media loading library to handle images, videos, or fonts referenced in the JSON.
Yes. You can fetch up to 25 experiences in a single call. If you exceed this, the SDK returns the 25 most recently updated experiences and notifies you of the unfulfilled keys.
The SDK returns an empty payload along with a standardized error code (e.g., NETWORK_ERROR). For more information on all the errors, refer here.