Self Handled Cards

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

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

Installation

To add MoEngage Cards SDK to your application, edit the application’s pubspec.yaml file and add the below dependency to it:

pubspec.yaml

dependencies:
  moengage_cards: $latestVersion

$latestVersion refers to the latest version of the plugin.

Post including the dependency, run flutter pub get command in the terminal to install the dependency.

After installing the plugin, use the following platform-specific configuration.

This plugin is dependent on moengage_flutter plugin. Make sure you have installed the moengage_flutter plugin as well. Refer to the documentation for the same.

Android Installation

Add the following dependency in the app/build.gradle file.

build.gradle

dependencies {
    ...
  implementation("com.moengage:cards-core:$sdkVersion")
}

replace $sdkVersion with the appropriate SDK version. Minimum supported version 1.5.0.

iOS Installation

In the case of iOS, the native dependency is part of the Cards flutter SDK itself, so there is no need to include any additional dependency for supporting Cards.

Initialize Cards

MoEngage Cards module can be initialized in the widget where the cards module is being used. 

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.initialize();

Example

Dart

// Use Named Import otherwise MoEngage classes might be collided with classed in flutter/material.dart
 import 'package:moengage_cards/moengage_cards.dart' as moe;
class CardsScreen extends StatefulWidget {
  const CardsScreen({Key? key}) : super(key: key);
  @override
  State<CardsScreen> createState() => _CardsScreenState();
}
class _CardsScreenState extends State<CardsScreen>{
moe.MoEngageCards cards = moe.MoEngageCards("MOE_Workspace_ID");
  @override
  void initState() {
    super.initState();
    cards.initialize();
  }
}

Get Cards Info

Fetch All the cards campaign data that are eligible to show for the particular user which returns data as CardsInfo. For a complete list of data models please refer to the API documentation.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
CardsInfo cardsInfo = await cards.getCardsInfo();

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.

Refresh Cards

Use the refreshCards*()*** API to refresh cards on the User Demand. This API can be used to mimic Pull to refresh behavior.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.refreshCards((data) {  if (data?.hasUpdates == true) {    // Update UI  }});

Fetch Cards

Use the fetchCards*()*** API to fetch cards for the User. This API can be used to sync latest cards data.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.fetchCards().then((data) {  // Update UI});

Inbox Loaded

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

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.onCardsSectionLoaded((data) {
  if (data?.hasUpdates == true) {
    // Refresh UI
  }
});

Inbox UnLoaded

Call onCardSectionUnloaded() when the screen/section is no longer visible or going to the background.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
  cards.onCardsSectionUnLoaded();

Fetch Categories

To fetch all the categories for which cards are configured, use the getCardsCategories() API.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
List<String> categories = await cards.getCardsCategories();

All Cards Categories Enabled

To fetch all the categories for which cards are configured, use the isAllCategoryEnabled() API.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID); 
bool isAllCategoryEnabled = await cards.isAllCategoryEnabled();

Fetch Cards for Categories

To fetch cards eligible for display for a specific category use the getCardsForCategory() API.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID); 
int count = await cards.getCardsForCategory(category);

Get New Cards Count

To obtain the new cards count use getNewCardsCount() method as shown below:

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
int count = await cards.getNewCardsCount();

Card Shown

Call the cardShown() API to notify a card is shown to the user.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.cardShown(context, card); // Pass Card Object

Card Clicked

Call the cardClicked() API to notify a card is shown to the user.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.cardClicked(card, widgetId); // Pass Card Object

Delete Card

Call the deleteCard() API to delete a card.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.deleteCard(card); // Pass Card Object

Mark Card Delivered

To track delivery to the card section of the application call the cardDelivered() API when the cards section of the application is loaded.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.cardDelivered();

Delete Multiple Cards

Call the deleteCards() API to delete a card.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.deleteCards(context, cards); // Pass List of Cards

Get Unclicked Cards Count

To obtain the unclicked cards count use getUnClickedCardsCount() method as shown below.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
int count = await cards.getUnClickedCardsCount();

App Open Card Sync Listener

Set this listener to get a callback for card sync on the App opened. This listener should be set before calling initialize() API. In most cases, this API is not required.

Dart

MoEngageCards cards = MoEngageCards(YOUR_Workspace_ID);
cards.setAppOpenCardsSyncListener((data) {
  //Update UI
});
cards.initialize();

The hybrid framework does not support the MoEngage default Card. Only the Self-handled Card is supported.