Self Handled Cards

Build custom card views in your iOS app using the MoEngage self-handled cards SDK and APIs.

Self-handled cards give you the flexibility to create card campaigns on the MoEngage Platform and display the cards anywhere within the application. The SDK provides APIs to fetch the campaign’s data, which allows you to create your own custom view for the cards.

SDK Installation

Install using Swift Package Manager

MoEngageCards is supported through SPM from SDK version 3.2.0. To integrate use the following git hub url link and set the branch as master or version as 4.0.0 and above https://github.com/moengage/MoEngage-iOS-Cards.git

Install using CocoaPod

Information

CocoaPods is being deprecated. MoEngage recommends using Swift Package Manager for all new integrations. For detailed info on cocoapods, refer to CocoaPods Integration Guide.

Integrate the MoEngageCards framework by adding the dependency in the podfile as shown below.

Ruby

pod 'MoEngage-iOS-SDK/Cards',

Now run pod install to install the framework.

Manual Integration

Manual Integration

To integrate the MoEngageCards SDK manually to your project follow this doc.

Notify on Section Load

You can show the cards on a separate screen or a section of the screen. When the cards screen/section is loaded call onCardSectionLoaded()

If you are using a UIViewController as the cards page, call onCardSectionLoaded() inside viewWillAppear(_:) to ensure cards are synced each time the screen becomes visible.

Swift

MoEngageSDKCards.sharedInstance.onCardSectionLoaded(forAppID: "Your Workspace Id") { data in
   print("Card section loaded, hasUpdates: \(data?.hasUpdates ?? false)")
}

Use the below APIs to fetch the card’s data and build your own UI.

Fetch Categories

To fetch all the categories for which cards are configured use the API getCardsCategories(forAppID:withCompletionBlock:)

Swift

MoEngageSDKCards.sharedInstance.getCardsCategories { categories, accountMeta in
   print("Fetched Cards Categories \(categories)")
}

Fetch Cards for Categories

To fetch cards eligible for display for a specific category use the API getCards(forCategory:forAppID:withCompletionBlock:)

Swift

MoEngageSDKCards.sharedInstance.getCards(forCategory: "CATEGORY") { cards, accountMeta in
   print("Fetched cards for given category")
}

Instead of using separate APIs to fetch the Cards and categories you can use the method getCardsData(forAppID:withCompletionBlock:) to fetch all the information in one go.

Swift

MoEngageSDKCards.sharedInstance.getCardsData { cardsData, accountMeta in
   print("Cards category \(cardsData?.cardCategories)")
   print("Cards Data \(cardsData?.cards)")
}

Track Statistics for Cards

Since the UI/display of the cards is controlled by the application to track statistics on delivery, display, click we need the application to notify the SDK.

Delivered

To track delivery to the card section of the application use the API cardDelivered(_:forAppID:) when the cards section of the application is loaded by passing the instance of MoEngageCardCampaign.

Swift

MoEngageSDKCards.sharedInstance.cardDelivered(cardCampaign, forAppID: "YOUR Workspace ID")   

Impression

Call the method cardShown(_:forAppID:) when a specific card is visible on the screen.

Swift

MoEngageSDKCards.sharedInstance.cardShown(cardCampaign, forAppID: "YOUR Workspace ID")

Click

Call the method cardClicked(_:withWidgetID:forAppID:) whenever a user clicks on a card, along with the card object widget identifier for the UI element clicked should also be passed.

Swift

MoEngageSDKCards.sharedInstance.cardClicked(cardCampaign, withWidgetID: widgetID);

Delete Card

Call the method deleteCards(_:forAppID:andCompletionBlock:) to delete a card by passing an array of MoEngageCardCampaign as parameter.

Swift

MoEngageSDKCards.sharedInstance.deleteCards([cards]) { isDeleted, accountMeta in
   print("Card deletion was \(isDeleted)")
}

The above API has an overloaded method that accepts a list of cards to be deleted.

Fetch Cards from the Server

Use the fetchCards(forAppID:withCompletion:) API to refresh cards from the MoEngage server if required, MoEngageCardData is provided in callback with refreshed MoEngageCardCampaign in cards property and account meta-data MoEngageAccountMeta in accountMeta.

Swift

MoEngageSDKCards.sharedInstance.fetchCards { data in
   print("Refreshed cards: \(data?.cards) for account \(data?.accountMeta)")
}

Note

The SDK caches cards and rate-limits server calls. fetchCards() hit the server at most once every 5 minutes. If called more frequently, the existing cached cards are returned via the callback.

FAQs

How do I handle near-real-time card updates (e.g., replacing a survey card after submission)?

For use cases requiring immediate UI updates based on user actions, we recommend the following execution pattern:

1. Initial Load: On screen load, call fetchCards() to pull the latest cards from the server.
2. Trigger Update: After the user action (like a survey submission), call onCardSectionLoaded(). This method returns a hasUpdates flag in its completion handler.
3. Refresh UI: If hasUpdates is true, call getCards(forCategory:) or getCardsData() to retrieve the refreshed cards from local storage and update your view.

What is the difference between onCardSectionLoaded() and fetchCards()?

While both APIs involve fetching card data, they serve different purposes within the card lifecycle:

Feature	onCardSectionLoaded()	fetchCards()
Use Case	Recommended for standard card inbox screens.	One-time force refresh outside the normal lifecycle.
Sync	Tracks impressions automatically.	Does not handle impression tracking.
Callback	Provides a hasUpdates flag in the completion handler.	Standard success/error completion.