Create targeted or automated App Inbox/NewsFeed messages that can be grouped into various categories, and target your users with different updates or offers that can stay in the Inbox/Feed over a designated period of time. For more information, refer to 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.cardsUi)
}
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.
SDK Dependency on Glide for Image and GIF Loading
SDK uses Glide for loading images and gifs. Ensure you add Glide to your application in case you don't have it already. SDK is compiled using library version 4.9.0. We recommend you use the same version or higher in your application.
Adding the UI Component
You can integrate the card UI into your application either by inflating the activity provided by the SDK or attaching the Fragment provided by the SDK to an existing Activity in the application.
Integrating using Activity
The SDK manifest has declared the CardActivity in the manifest file, and nothing additional is required until and unless you want to customize the theme of the Activity or any other launch property.
The default declaration is as below.
<activity
android:name="com.moengage.cards.ui.CardActivity"
android:label="@string/moe_card_feed_title"
android:theme="@style/MoECardTheme.NoActionBar"
/>
For more information about how to customize, refer to Customisation.
Integrating using Fragment
To integrate the Card UI as a fragment, you can inflate the CardFragment from the appropriate place inside your application.
UI Customizations
SDK provides a certain set of UI customizations.
Activity Customization
If you are integrating the activity provided by the SDK, you can customize the label, theme, etc.
To customize the theme label you can either re-declare the activity in your app's manifest and provide the desired theme or label.
Alternatively, you can override the SDK defaults as described below.
Activity Label
The default label for the activity is Inbox. In case you want to change the label add the moe_card_feed_title string in your strings.xml file with the label name.
<string name="moe_card_feed_title">[YOUR_LABEL_NAME]</string>
Activity Theme
The default theme applied to the Activity is MoECardTheme.NoActionBar.
The following is the theme definition.
<style name="MoECardTheme" parent="Theme.AppCompat.Light" />
<style name="MoECardTheme.NoActionBar">
<item name="windowActionBar">false</item>
<item name="windowNoTitle">true</item>
<item name="colorPrimary">@color/moe_card_color_primary</item>
<item name="colorPrimaryDark">@color/moe_card_color_primary_dark</item>
<item name="colorAccent">@color/moe_card_color_accent</item>
<item name="colorControlNormal">@color/moe_card_control_color</item>
</style>
<style name="MoETheme.AppBarOverlay" parent="ThemeOverlay.AppCompat.Light" />
<style name="MoETheme.PopupOverlay" parent="ThemeOverlay.AppCompat.Light" />
<!-- Theme customisation -->
<color name="moe_card_color_accent">#1C64D0</color>
<color name="moe_card_color_primary_dark">@color/moe_black</color>
<color name="moe_card_color_primary">@color/moe_white</color>
<color name="moe_card_control_color">@color/moe_black</color>
To customize the theme override any of the color attributes.
To override, define the attribute with the same name in the colors.xml file of the application and specify the desired color.
For example, if you want to customize the accent color define moe_card_color_accent in your application color.xml as described and replace [YOUR_COLOR] with the desired color.
<color name="moe_card_color_accent">[YOUR_COLOR]</color>
Activity Toolbar
The CardActvity has a toolbar in the layout with the below style. In case you want to customize any of the properties, override the below style completely, or you can override the individual items are well.
<style name="MoECardToolbarTextStyle" parent="TextAppearance.Widget.AppCompat.Toolbar.Title">
<item name="android:textColor">@color/moe_card_toolbar_text_color</item>
<item name="android:fontFamily">@font/roboto</item>
<item name="android:textSize">@dimen/moe_card_tab_font_size</item>
</style>
The background color of the toolbar is set to the primary color of the theme.
Tab Customisation
The Card UI is built with a tab layout, following is the list of customization options provided by the SDK.
- Text Appearance
- Font
- Text Size
- Tab Text-color selected/unselected
- Tab background-color selected/unselected
To customize the properties, you can override the styles or color attributes defined by the SDK in your application colors.xml or styles.xml file.
<style name="MoECardTabTextStyle">
<item name="android:textColor">@color/moe_card_toolbar_text_color</item>
<item name="android:fontFamily">@font/roboto</item>
<item name="android:textSize">@dimen/moe_card_tab_font_size</item>
</style>
<color name="moe_card_tab_selected_text_color">#1C64D0</color>
<color name="moe_card_tab_unselected_text_color">#8E8E8E</color>
<color name="moe_card_tab_background_selected">@color/moe_white</color>
<color name="moe_card_tab_background_unselected">@color/moe_white</color>
Text Customization
Each card has three text fields and a button
- Header
- Message
- Call to Action Button(CTA)
- Timestamp
The default style for each of these components can be overridden by overriding the below styles completely or overriding the individual items.
Certain styling components like color and text formatting (like bold, italic, etc.) for these fields are customizable from the MoEngage Dashboard, while others, like font and text size fixed on the SDK side. Values for these can be overridden and will be applied to all cards.
info |
Note The color defined in these styles are default colors and will be overridden by the colors selected during campaign creation. |
<!-- Header style -->
<style name="MoECardHeaderTextStyle">
<item name="android:textSize">@dimen/moe_card_header_font_size</item>
<item name="android:singleLine">true</item>
<item name="android:ellipsize">marquee</item>
<item name="android:textColor">@color/moe_card_header_color</item>
<item name="android:fontFamily">@font/roboto</item>
</style>
<!-- Message style -->
<style name="MoECardMessageTextStyle">
<item name="android:textSize">@dimen/moe_card_content_font_size</item>
<item name="android:maxLines">3</item>
<item name="android:ellipsize">end</item>
<item name="android:textColor">@color/moe_card_message_color</item>
<item name="android:fontFamily">@font/roboto</item>
</style>
<!-- Button style -->
<style name="MoECardCtaStyle">
<item name="android:textColor">@color/moe_card_cta_color</item>
<item name="android:fontFamily">@font/roboto</item>
<item name="android:textSize">@dimen/moe_card_cta_font_size</item>
<item name="android:singleLine">true</item>
<item name="android:ellipsize">marquee</item>
<item name="android:textAllCaps">false</item>
<item name="android:background">@android:color/transparent</item>
<item name="android:foreground">?android:attr/selectableItemBackground</item>
</style>
<!-- Timestamp Style -->
<style name="MoECardTimeTextStyle">
<item name="android:textSize">@dimen/moe_card_time_font_size</item>
<item name="android:singleLine">true</item>
<item name="android:ellipsize">marquee</item>
<item name="android:textColor">@color/moe_card_timestamp_color</item>
<item name="android:fontFamily">@font/roboto</item>
</style>
<!-- Text Color -->
<color name="moe_card_header_color">#424242</color>
<color name="moe_card_message_color">#616161</color>
<color name="moe_card_timestamp_color">#9E9E9E</color>
Timestamp format Customization
The default format for the timestamp shown on each card is MMM dd, hh:mm a this can be customized by passing the custom format to configureCards() of the MoEngage.Builder object while initializing the SDK.
Card Customization
You can customize the following properties for a given card
- Un-clicked Indicator Color
- Card Background Color (overridden by the color selected during the campaign creation)
Override the below color resources in the colors.xml to use the desired color.
<color name="moe_card_unclicked_indicator_color">#5956D6</color>
<color name="moe_card_background_color">@color/moe_white</color>
Empty State
If the inbox does not contain any cards, SDK shows an empty screen with an image and message, as shown below.
The image and message can be customized if required.
Image Customization
To customize the image, pass in the resource id of the image in the configureCards() API MoEngage.Builder object while initializing the SDK.
Message Customisation
To customize the message, override the moe_card_no_message_available in your applications strings.xml file.
<string name="moe_card_no_message_available">[YOUR_STRING_GOES_HERE]</string>
Customize Delete Text
To customize the message of the delete button, override the below string resource in the strings.xml of your application.
<string name="moe_card_delete_title">[YOUR_STRING_GOES_HERE]</string>
Disable Pull to Refresh
By default, the Card Activity/Fragment has the pull to refresh feature enabled, you can disable pull to refresh using the configureCards() API in the MoEngage.Builder.
APIs
Unclicked Count
The SDK provides an API to fetch the number of cards which hasn't been clicked by the users. To get the count, you can use the below APIs.
// Call this API on worker thread as it reads from a file.
MoECardHelper.getUnClickedCardCount(context)
// This API returns the count asynchronously in the listener passed as a parameter.
MoECardHelper.getUnClickedCardCountAsync(context, listener)
// Call this API on worker thread as it reads from a file.
MoECardHelper.INSTANCE.getUnClickedCardCount(context);
// This API returns the count asynchronously in the listener passed as a parameter.
MoECardHelper.INSTANCE.getUnClickedCardCountAsync(context, listener);
Refer to the documentation of MoECardHelper.getUnClickedCardCount() and MoECardHelper.getUnClickedCardCountAsync() for more information.
New Card Count
The SDK provides an API to get the new cards for the user on the device. To get the count, use the below API.
// Call this API on worker thread as it reads from a file.
MoECardHelper.getNewCardCount(context)
// This API returns the count asynchronously in the listener passed as a parameter.
MoECardHelper.getNewCardCountAsync(context, listener)
// Call this API on worker thread as it reads from a file.
MoECardHelper.INSTANCE.getNewCardCount(context);
// This API returns the count asynchronously in the listener passed as a parameter.
MoECardHelper.INSTANCE.getNewCardCountAsync(context, listener);
Refer to the documentation of MoECardHelper.getNewCardCount() and MoECardHelper.getNewCardCountAsync() for more information.
Callbacks
The SDK provides callbacks when
- Cards are successfully synced on application launch/foreground
- The card is clicked by the user
Sync Callback
To get a callback for sync completion on application launch/foreground implement the SyncCompleteListener interface and register for the callback using MoECardHelper.setSyncCompleteListener().
Click Callback
To get a callback on the card, click implement the OnCardClickListener interface and register for the callback using the MoECardUiHelper.setClickListener().