Self-handled cards give you the flexibility of creating Card Campaigns on the MoEngage Platform and displaying the cards anywhere inside the application. SDK provides APIs to fetch the campaign's data using which you can create your own view for cards.
SDK Installation
Installing using Catalog
Integration 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(moengage.cardsCore)
}
Alternatively, you can add the dependency using Artifact ID as described in Installation using Artifact ID. However, installation using Catalog ID is the recommended approach as installing using Artifact ID may lead to version mismatch if mapped incorrectly.
Implementing Self Handled Cards
Use the below APIs to fetch the card's data and build your own UI. The SDK provides both blocking and async APIs for fetching the data. In this document, we have just added the blocking APIs, refer to the API reference for MoECardHelper for the async APIs.
Notify on Section Load/Unload
You can show the cards on a separate screen or a section of the screen. When the cards screen/section is loaded call onCardSectionLoaded() and call onCardSectionUnloaded() when the screen/section is no longer visible or going to background.
// call on section or screen load
MoECardHelper.onCardSectionLoaded(context,listener);
// call when the section is no longer visible or going to background.
MoECardHelper.onCardSectionUnloaded(context);
// call on section or screen load
MoECardHelper.INSTANCE.onCardSectionLoaded(context,listener);
// call when the section is no longer visible or going to background.
MoECardHelper.INSTANCE.onCardSectionUnloaded(context);
Fetch Categories
To fetch all the categories for which cards are configured, use the getCardCategories() API.
MoECardHelper.getCardCategories(context)
MoECardHelper.INSTANCE.getCardCategories(context);
Additionally, you can optionally have an All category which would be like a superset of other categories. Use the isAllCategoryEnabled() API.
MoECardHelper.isAllCategoryEnabled(context)
MoECardHelper.INSTANCE.isAllCategoryEnabled(context);
Fetch Cards for Categories
To fetch cards eligible for display for a specific category, use the getCardsForCategory() API
MoECardHelper.getCardsForCategory(context, "[YOUR_CATEGORY]")
MoECardHelper.INSTANCE.getCardsForCategory(context, "[YOUR_CATEGORY]");
To fetch all the cards eligible for display irrespective of the category, pass the category CARD_CATEGORY_ALL as shown below
MoECardHelper.getCardsForCategory(context, CARDS_CATEGORY_ALL)
MoECardHelper.INSTANCE.getCardsForCategory(context, MoECardsCoreConstants.CARDS_CATEGORY_ALL);
Refer to the documentation of the Card model to know more about the fields and data present.
Instead of using separate APIs to fetch the Cards and categories, you can use the getCardsInfo() API to fetch all the information in one go
MoECardHelper.getCardsInfo(context)
MoECardHelper.INSTANCE.getCardsInfo(context);
Widget and Widget Id Mapping
Basic Card/Illustration Card
Widget Id | Widget Type | Widget Information |
0 | Image (WidgetType.IMAGE) | Image widget in the card. |
1 | Text (WidgetType.TEXT) | Header text for the card. |
2 | Text (WidgetType.TEXT) | Message text for the card. |
3 | Button (WidgetType.Button) | Call to action(CTA) for the card. |
Track Statistics for Cards
Since the UI/display of the cards is controlled by the application to track statistics on delivery, display, and click, we need the application to notify the SDK.
Delivered
To track delivery to the card section of the application, call the cardDelivered() API when the cards section of the application is loaded.
MoECardHelper.cardDelivered(context)
MoECardHelper.INSTANCE.cardDelivered(context);
Impression
Call the cardShown() API when a specific card is visible on the screen.
MoECardHelper.cardShown(context, card)
MoECardHelper.INSTANCE.cardShown(context, card);
Click
Call the cardClicked() API whenever a user clicks on a card, along with the card object widget identifier for the UI element clicked should also be passed.
MoECardHelper.cardClicked(context, card, widgetId)
MoECardHelper.INSTANCE.cardClicked(context, card, widgetId);
Delete Card
Call the deleteCard() API to delete a card
MoECardHelper.deleteCard(context, card)
MoECardHelper.INSTANCE.deleteCard(context, card);
To delete a list of cards, use deleteCards() API.
Refresh Cards from the Server
Use the fetchCards() API to refresh cards from the MoEngage server if required.
MoECardHelper.fetchCards(Context, CardAvailableListener)
MoECardHelper.INSTANCE.fetchCards(Context, CardAvailableListener);
info |
Note
|
Please take a look at the documentation for a complete guide on available helper APIs.