Skip to main content

​
Overview

The MoEngage iOS 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 information directly through a streamlined, native interface.
PrerequisiteBefore you can fetch personalized experiences, ensure you have called the SDK initialize() method within your application entry point ( didFinishLaunchingWithOptions on iOS). For more information, refer to SDK initialization.

​
Integration MoEngage Personalization

To install the MoEngagePersonalization through SPM, perform the following steps:
  1. Navigate to File > Add Package.
  2. Enter the appropriate repository URL:
  3. Select the master branch or your desired version.
  4. Click Add Package.
  5. Add the MoEngagePersonalization product to your app target.

​
Implementation Workflow

The MoEngageSDKPersonalize singleton is designed to simplify the retrieval and interaction with dynamic, personalized content on iOS. The SDK provides native Swift methods as well as Objective-C-compatible overloads.

​
1. Fetching Meta Experience

Before fetching any specific payload or experience, you must invoke the metadata call. This step provides the SDK with the necessary configuration and context to accurately process subsequent requests. The SDK offers dedicated methods for both Swift and Objective-C. 
public func fetchExperiencesMeta(
        status: [MoEngageExperienceStatus],
        onSuccess: @escaping MoEngageMetaSuccessCallback,
        onFailure: @escaping MoEngagePersonalizeFailureCallback,
        workspaceId: String? = nil
    )
The onSuccess callback returns an ExperienceCampaignsMetadata object containing all necessary metadata for campaign execution. Conversely, the onFailure callback provides a RequestFailureReasonCode and an optional message to identify the specific reason for the request’s failure. Always call the metadata fetch first to initialize core configurations based on the desired experience status. Use the standard method for Swift arrays, or the ObjC variant if passing raw NSNumber values from Objective-C code.

​
2. Fetch Personalized Content

Once metadata is fetched, you can retrieve the actual personalized payloads. You can fetch a single experience or multiple experiences simultaneously, with full support for contextual targeting. The code snippet below to fetch a single experience is compatible with both Swift and Objective-C implementations:
Objective-C
 @objc public func fetchExperience(
        experienceKey: String,
        attributes: [String: String] = [:],
        onSuccess: @escaping MoEngageExperienceSuccessCallback,
        onFailure: @escaping MoEngagePersonalizeFailureCallback,
        workspaceId: String? = nil
    )
To fetch multiple experiences: 
public func fetchExperiences(
        experienceKeys: Set<String>,// EXPERIENCE_KEY must be one of the keys returned in the fetchExperiencesMeta call. 
    // Using a key that is not part of the meta call or incorrect key will result in an invalid key error.
        attributes: [String: String] = [:],
        onSuccess: @escaping MoEngageExperienceSuccessCallback,
        onFailure: @escaping MoEngagePersonalizeFailureCallback,
        workspaceId: String? = nil
    )
The onSuccess callback returns an ExperienceCampaignsResult object containing all necessary metadata for campaign execution. 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. In Swift, pass a Set<String>. For Objective-C, use the fetchExperiencesObjC method which accepts an NSArray bridged as [String].
Use cases: Contextual Targeting: Pass a dictionary of attributes (e.g., [“current_page”: “home”, “cart_value”: “500”]) during the fetch. This enables real-time, state-dependent content delivery (e.g., showing a “Free Shipping” banner if the cart value meets a threshold).

​
3. Track Impressions

To accurately measure campaign performance, you must track user interactions after rendering the personalized content on the UI. The below-mentioned tracking code snippets are compatible with both Swift and Objective-C implementations.

​
3a. Track Impressions for Experience Campaigns

Objective-C
 // MARK: - Tracking
    
    /// Tracks impression for an experience.
    @objc public func trackExperienceShown(
        campaign: MoEngageExperienceCampaign, //campaign is a placeholder 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.
        workspaceId: String? = nil
    )
    
    /// Tracks impressions for multiple experiences.
    @objc public func trackExperiencesShown(
        campaigns: [MoEngageExperienceCampaign],
        workspaceId: String? = nil
    )
You can use these methods to log “Impressions” (trackExperienceShown / trackExperiencesShown) when the UI renders the content.

​
3b. Track Impressions for Offering Campaigns

Offerings are a distinct subtype of personalized content. The SDK provides dedicated tracking functions that accept offering-specific attributes. The below-mentioned tracking code snippets are compatible with both Swift and Objective-C implementations.
Objective-C
 // MARK: - Offering Tracking
  
    /// Tracks impression for an offering within an experience.
    @objc public func trackOfferingShown(
        offeringAttributes: [String:Any],
        workspaceId: String? = nil
    )
    
    /// Tracks impressions for multiple offerings.
    @objc public func trackOfferingsShown(
        offeringsAttributes:[[String: Any]],
        workspaceId: String? = nil
    )
These methods return specific offeringAttributes dictionaries to the server, providing highly granular analytics for custom offers.

​
4. Track Clicks

​
4a. Track Clicks for Experience Campaigns

Objective-C
 /// Tracks click for an experience.
    @objc public func trackExperienceClicked(
        campaign: MoEngageExperienceCampaign,
        workspaceId: String? = nil
    )
You can use these methods to log “Clicks” (trackExperienceClicked) when the user interacts with the UI element.

​
4b. Track Clicks for Offering Campaigns:

Offerings are a distinct subtype of personalized content. The SDK provides dedicated tracking functions that accept offering-specific attributes. The below-mentioned tracking code snippets are compatible with both Swift and Objective-C implementations.
Objective-C
  /// Tracks click for an offering.
    @objc public func trackOfferingClicked(
        campaign: MoEngageExperienceCampaign,
        offeringAttributes: [String: Any],
        workspaceId: String? = nil
    )
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.
These methods return specific offeringAttributes dictionaries to the server, providing highly granular analytics for custom offers. 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.