Implement Self-Handled Cards - Carousel Banners on App Home Page

Introduction

Applying carousel banners on the home page of your website is a great way to engage with your app users and promote specific offerings.

In this article, we will learn how we can use MoEngage Self-Handled Cards to build a banner carousel on your Android and iOS native apps and create Card campaigns to deliver targeted Cards to your app visitors through these banner carousels.

Expected Result

Users will see a carousel banner on the home page of your website:

Announcement Carousels.gif

Steps to Integrate

MoEngage self-handled Cards allow you to access the raw payload of the Card content. You can create components in your app to consume these payloads and display the Card content in a design and layout that works as an integrated component of your app.

The following steps will help you with the following:

  1. Cards Integration
  2. Cards UI Creation for each Category
  3. Parsing MoEngage Cards Payload and Feed into the Carousel UI
  4. Track Analytics

Step 1: Cards Integration

For Android

Add the following dependency in the app/build.gradle file and sync your project:

Java
dependencies {
...
implementation("com.moengage:cards-core:1.2.0")
}

For more information, refer to Self Handled Cards for Android native.

For iOS

Add the following dependency in the pod file and sync your project:

Java
pod 'MoEngageCards','~> 4.0.0'

For more information, refer to Self Handled Cards for iOS native.

Step 2: Cards UI Creation for each Category

Cards contain multiple categories and each category consists of two types of Cards as follows:

  • Basic
  • Illustration

In this document, we are going to see how the Illustration Card category of the Announcement type will appear and how we parse and render the data.

UI Creation in Android

In this example, Announcement type Cards are also called Carousel Type Cards because we are using them for Banners that scroll every 3 seconds. Here we will use SliderView to show the banners and add the following dependencies in the app/build.gradle file:

Java
dependencies {
implementation 'com.github.smarteist:autoimageslider:1.3.9'
implementation 'com.github.bumptech.glide:glide:4.11.0'
}

For more information and configurations available with the library, refer to Auto Image Slider in Android.

On implementing the code block above, the UI will look like below and based on the Cards Template value, we will enable and disable the layout accordingly, which we will be showing in the later part of the stage.

UI creation in Android.png

UI Creation in iOS

In this example, Announcement type Cards are also called Carousel Type Cards because we are using them for Banners that scroll every 3 seconds. Here we will use the ImageSlider to show the banners and add the following dependencies in the pod file.

Java
pod 'ImageSlideshow'#, '~> 1.9.0'

For more information and configurations available with the library, see Image Slideshow on Cocoapods.

Step 3: Parsing MoEngage Cards Payload and Feed into the Carousel UI

For Android

To fetch all the categories for which Cards are configured, use the getCardCategories() API.

In this example, we are using the getCardsForCategory() API to fetch the Cards that belong to Announcement Type.

Java
public List<Card> handleAnnouncement() {
return MoECardHelper.INSTANCE.getCardsForCategory(mContext, Constants.CATEGORY_ANNOUNCEMENT).getCards();
}

If the function above returns the data and not NULL, then it signifies that the Card is delivered successfully and to notify this to MoEngage SDK, you call the following API. This will help you later with analytics.

Java
MoECardHelper.INSTANCE.cardDelivered(context);

After we get the Cards data from the function above, we need to parse the data to extract the details and store it in a Model class which will be used to render into the UI as shown in the following code snippet:

Java
public CardModel parseCardData(Card card) {
String title, description;
CardModel cardModel = new CardModel();
cardModel.setCard(card);
Container container = card.getTemplate().getContainers().get(0);
cardModel.setCtaAction(container.getAction());
cardModel.setContainer(container);
if (card.getTemplate().getTemplateType() == TemplateType.ILLUSTRATION
cardModel.setItemViewType(Constants.CARD_ILLUSTRATION);
for (Widget widget : container.getWidgetList()) {
cardModel.setWidget(widget);
if (widget.getId() == 0 && widget.getWidgetType() == WidgetType.IMAGE) {

cardModel.setImageFromUrl(widget.getContent());
} else if (widget.getId() == 1 && widget.getWidgetType() == WidgetType.TEXT) {
title = widget.getContent();
cardModel.setTitle(title);
} else if (widget.getId() == 2 && widget.getWidgetType() == WidgetType.TEXT) {
if (widget.getContent().isEmpty()) {
Log.e(TAG, " : Widget text missing will not show widget.");
continue;
}
description = widget.getContent();
cardModel.setDescription(description);
} else if (widget.getId() == 3 && widget.getWidgetType() == WidgetType.BUTTON) {
if(!widget.getContent().isEmpty()) {
cardModel.setCtaName(widget.getContent());
}
}
}
String backgroundColor = Objects.requireNonNull(container.getStyle()).getBackgroundColor();
if (!backgroundColor.isEmpty()) {
cardModel.setBackgroundColor(backgroundColor);
}
return cardModel;
}

These parsed values are sent to the SliderAdapter to render in the UI as shown in the following Slider Adapter class file.

After the Cards are rendered properly in the UI, you can notify the same to MoEngage by calling the APIs given in the Self-handled Cards document for Android SDK.

step 3 android.png

For iOS

To fetch all the categories for which Cards are configured, use the getCardsCategories API. To fetch all the categories for which Cards are configured, use the getCardsCategories API.

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

for category in categories {
self.getCardData(category: category)
}
}

To get the Card data based on category, use the API getCards as shown below:

Swift
func getCardData(category: String) {
MoEngageSDKCards.sharedInstance.getCards(forCategory: category) { cards, accountMeta in
print("Fetched cards for given category")
if(category == "Announcements") {
var mSliderData = Array<NewCardModel>()
var mDataForAnnouncements = Array<MoEngageCardCampaign>()
mDataForAnnouncements = cards
for cardData in mDataForAnnouncements {
var cardModel = NewCardModel()
cardModel = parseData(cardData: cardData)
mSliderData.append(cardModel)
}
var afUrlSource = [SDWebImageSource(urlString: "https://images.unsplash.com/photo-1432679963831-2dab49187847?w=1080")!]
if(mSliderData.count > 0){
for cardData in mSliderData {
if(cardData.templateType == MoEngageCardTemplateType.illustration) {
afUrlSource.append(SDWebImageSource(urlString: cardData.imageFromUrl ?? "")!)
}
}
if(afUrlSource.count > 1) {
afUrlSource.remove(at: 0)
self.slideshow.setImageInputs(afUrlSource)
} else {
self.slideshow.setImageInputs(self.localSource)
}
} else {
self.slideshow.setImageInputs(self.localSource)
}
}
}

If the function above returns the data and not NULL, then it signifies that the Card is delivered successfully and to notify this to MoEngage SDK, you call this below API. This will help you later with analytics.

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

After we get the Cards data from the function above, we need to parse the data to extract the details and store it in a Model class, which will be used to render into the UI as shown in the following code snippet:

Swift
func parseData(cardData: MoEngageCardCampaign) -> NewCardModel {
let newCardModel = NewCardModel()
newCardModel.card = cardData
let container : MoEngageCardContainer = (cardData.templateData?.containers.first)!
newCardModel.container = container
newCardModel.ctaAction = container.actions
if(cardData.templateData?.type == MoEngageCardTemplateType.basic) {
newCardModel.itemViewType = "Basic"
} else {
newCardModel.itemViewType = "Illustration"
}
newCardModel.templateType = cardData.templateData?.type;
for widgetData in container.widgets {
newCardModel.widget = widgetData
if(widgetData.id == 0 && widgetData.type == MoEngageCardWidgetType.image) {
newCardModel.imageFromUrl = widgetData.content
} else if(widgetData.id == 1 && widgetData.type == MoEngageCardWidgetType.text) {
newCardModel.cardTitle = widgetData.content
} else if(widgetData.id == 2 && widgetData.type == MoEngageCardWidgetType.text) {
if(widgetData.content.isEmpty) {
print("Widget text missing will not show widget.")
continue
}
newCardModel.cardDescription = widgetData.content
} else if(widgetData.id == 3 && widgetData.type == MoEngageCardWidgetType.button) {
if(!widgetData.content.isEmpty) {
newCardModel.ctaAction = widgetData.actions
}
}
}
return newCardModel
}
}

These parsed values are sent to the ImageSlider to render it in the UI.

After the Cards are rendered properly in the UI, you can notify the same to MoEngage by calling the APIs given in the Self-handled Cards document for iOS SDK.

step 3 iOS.png

Step 4: Track Analytics

After the Cards are rendered properly in the UI, you can use MoEngage SDKs that provide APIs to fetch the Card's data, allowing you to track the usage and analytics of the Cards. To learn more, refer to the following documents:

Test Campaigns

Creating carousel Cards is similar to creating a Card campaign for your application. While you are creating Cards, navigate to the step Create view on your MoEngage dashboard and scroll down to the Test Card section. You can test the output of your newly created Card by selecting a custom attribute and its value for a test user.

Before Testing

before testing.png

Expected Result

Announcement Carousels.gif

The Test Card section enables you to view the campaign on a test device to ensure that your intended message is being conveyed in the desired way.

Recommendation for Additional Layouts

This document illustrated an example of creating carousel Cards using the Auto Image Slider in Android and Image Slideshow on Cocoapods in iOS. You can use the same method to create Cards with either Basic or Illustration template and parse the payload to build different UI layouts with different libraries.

Here are a few examples for layouts that can be used instead of carousels:

promotions.png updates.png others.png

Sample Cards Payload

You can populate any layout by parsing the Card payload into UI elements similar to how the content was parsed for the carousel use case we saw above. Here is a sample payload for a card:

JSON
"cards": [
            {
                "id": "640g66767676hh56565656_F_T_CA_AB_0_P_0_L_0_android",
                "platform": "android",
                "created_at": 1686051528,
                "updated_at": 1686051528,
                "meta_data": {
                    "cid": "647f136f28cd97f6106b86c4_F_T_CA_AB_0_P_0_L_0",
                    "moe_card_id": "640g66767676hh56565656_F_T_CA_AB_0_P_0_L_0_android",
                    "moe_campaign_name": "Demo Card Campaign",
                    "moe_delivery_type": "Event Triggered",
                    "moe_campaign_id": "647f136f28cd97f6106b86c4"
                },
                "template_data": {
                    "type": "basic",
                    "containers": [
                        {
                            "widgets": [
                                {
                                    "content": "https://image.moengage.com/apiqasanityreactmoengage/20230606110034350340RKQN5HScreenshot2023060614443597f7c44fa5c96f29b225c53b361750eadajpgcompapiqasanityreactmoengage.jpg",
                                    "type": "image",
                                    "id": 0
                                },
                                {
                                    "content": "<div>john.doe@example.com</div>",
                                    "type": "text",
                                    "id": 1
                                },
                                {
                                    "content": "<div>Sample</div>",
                                    "type": "text",
                                    "id": 2
                                },
                                {
                                    "content": "<div>Click </div>",
                                    "type": "button",
                                    "id": 3,
                                    "actions": [
                                        {
                                            "type": "deepLink",
                                            "name": "navigate",
                                            "value": "https://www.moengage.com",
                                            "kvPairs": {}
                                        }
                                    ]
                                }
                            ],
                            "style": {
                                "bgColor": "#4e3db0"
                            },
                            "type": "basic",
                            "id": 0,
                            "actions": []
                        }
                    ]
                },
                "user_activity": {
                    "is_clicked": false
                },
                "display_controls": {
                    "is_pin": true,
                    "expire_after_delivered": 2592000
                },
                "category": "Promotions"
            }
        ]
    }
}

Add Additional Keys in the Card Payload

The cards standard payload consists of card campaign details, expiry details, title, message, image and action. 

If you want to add additional data in the cards payload you recieve, you can add them as part of the Primary action for the card while creating the card campaign in the for for Key-Value pairs as seen below.

Screenshot 2024-05-14 at 2.37.41 PM.png

These K-V pairs will be part of the Card payload under action and can be parsed to be used in the self-handled cards UI.

Placement for Different Widgets in the App

In the example above, we used the Announcement Card category to filter cards that should be added to the Carousel Widget in the home page.

If you are implementing self-handled cards in multiple sections of your app (including multiple sections in the same page), we recommend using Card Categories to differentiate between the sections. This way, you can use the function Fetch cards for Categories to fetch only the relevant cards for that section.

To set card categories, raise a support ticket.

Conclusion

In this use case, we learnt how to use MoEngage Self-Handled Cards to build a banner carousel on your Android and iOS native apps and create Card campaigns to deliver targeted Cards to your app visitors through these banner carousels.

We also learnt how you can use a combination of different layouts, Card categories, and K-V pairs to implement any type of Interactive widgets as part of your users’ journey.

Previous

Next

Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?