Configure app cards

The App Cards module provides a complete card-based messaging solution for the Insider Flutter Plugin. It enables developers to retrieve card campaigns, manage read/unread/delete status, handle deeplink actions, and log analytics events (clicks and views).

This documentation covers the App Cards API (FlutterInsiderAppCards), the current architecture. The legacy v1 API (getMessageCenterDataWithIdentifiers) is a separate, older interface for retrieving push notification payloads as a notification center. If you are building a new integration, use the App Cards API.

Prerequisites

• Insider Flutter Plugin flutter_insider: 5.0.0 or later

• SDK must be initialized via FlutterInsider.Instance.init(...) before accessing App Cards.

Access

The FlutterInsiderAppCards client is obtained through the main SDK singleton.

final appCards = FlutterInsider.Instance.appCards;

The appCards getter is lazily initialized and always returns a valid instance. If the SDK is not initialized, operations will report an InsiderAppCardsException with code sdkNotInitialized, and void methods (view, click, clickButton) will silently forward the failure to the native SDK.

Async Model

Flutter App Cards APIs use Future-based async methods instead of callback interfaces. Methods that can fail throw InsiderAppCardsException; void methods (view, click, clickButton) are fire-and-forget and never throw.

// Async method — await or use .then(...)
final response = await FlutterInsider.Instance.appCards.getCampaigns();

// Void method — fire-and-forget
FlutterInsider.Instance.appCards.view(card);

Error Handling

InsiderAppCardsException

All App Cards operations report errors via InsiderAppCardsException, which implements Exception and exposes a typed error code via error.code.

Example

try {
  final response = await FlutterInsider.Instance.appCards.getCampaigns();
  // ...
} on InsiderAppCardsException catch (e) {
  switch (e.error.code) {
    case InsiderAppCardsErrorCode.sdkNotInitialized:
      // SDK not initialized
      break;
    case InsiderAppCardsErrorCode.networkError:
      // Retry later
      break;
    case InsiderAppCardsErrorCode.serverError:
      // Server issue
      break;
    default:
      // Handle other errors
      break;
  }
}

Core Types

InsiderAppCardCampaignsResponse

Model class representing an app cards campaign response. Contains a list of card items.

InsiderAppCard

Model class representing a single card in the campaign response.

Convenience Methods

InsiderAppCardContent

Model class containing the title and description of a card.

InsiderAppCardImage

Model class representing an image within a card.

InsiderAppCardButton

Model class representing a button in a card.

Convenience Methods

InsiderAppCardAction (Abstract)

Abstract base class for all app card action models.

Action Types

InsiderAppCardDeeplinkAction

Deep link action with support for URL schemes, internal browser, and external browser URLs.

Getters

InsiderAppCardOpenSettingsAction

Opens the OS-level settings screen for the application. No additional fields.

InsiderAppCardFeedbackAction

Triggers the Insider in-app feedback flow. No additional fields.

InsiderAppCardType

Constants class for card type identifiers.

InsiderAppCardActionType

Constants class for action type identifiers.

Available Methods

getCampaigns

This method retrieves the app card campaigns for the current user.

Method signature

Future<InsiderAppCardCampaignsResponse?> getCampaigns()

Method example

final appCards = FlutterInsider.Instance.appCards;

try {
  final response = await appCards.getCampaigns();
  final cards = response?.appCards ?? [];

  for (final card in cards) {
    print('Card ID: ${card.id}');
    print('Is Read: ${card.isRead}');

    final content = card.content;
    if (content != null) {
      print('Title: ${content.title}');
    }
  }
} on InsiderAppCardsException catch (e) {
  print('Failed to get campaigns: ${e.error.code}');
}

markAsRead

This method marks one or more cards as read.

Method signature

Future<void> markAsRead(List<String> appCardIds)

Method example

final appCards = FlutterInsider.Instance.appCards;
final ids = ['card-001', 'card-002'];

try {
  await appCards.markAsRead(ids);
  print('Cards marked as read successfully');
} on InsiderAppCardsException catch (e) {
  print('Failed to mark as read: ${e.error.code}');
}

markAsUnread

This method marks one or more cards as unread.

Method signature

Future<void> markAsUnread(List<String> appCardIds)

Method example

final appCards = FlutterInsider.Instance.appCards;
final ids = ['card-001'];

try {
  await appCards.markAsUnread(ids);
  print('Cards marked as unread successfully');
} on InsiderAppCardsException catch (e) {
  print('Failed to mark as unread: ${e.error.code}');
}

You can also use the convenience methods card.markAsRead() and card.markAsUnread() directly on an InsiderAppCard instance to mark a single card.

delete

This method deletes one or more cards from the current user's campaigns. Deleted cards are permanently removed.

Method signature

Future<void> delete(List<String> appCardIds)

Method example

final appCards = FlutterInsider.Instance.appCards;
final ids = ['card-001'];

try {
  await appCards.delete(ids);
  print('Cards deleted successfully');
} on InsiderAppCardsException catch (e) {
  print('Failed to delete cards: ${e.error.code}');
}

You can also use the convenience method card.delete() directly on an InsiderAppCard instance to delete a single card.

click

This method logs a click conversion event for a card.

Method signature

void click(InsiderAppCard appCard)

Method example

// Using the FlutterInsiderAppCards client directly
FlutterInsider.Instance.appCards.click(card);

// Or using the convenience method on the card
card.click();

view

This method logs a view conversion event for a card.

Method signature

void view(InsiderAppCard appCard)

Method example

// Using the FlutterInsiderAppCards client directly
FlutterInsider.Instance.appCards.view(card);

// Or using the convenience method on the card
card.view();

clickButton

This method logs a button click action event.

Method signature

void clickButton(InsiderAppCardButton button)

Method example

// Using the FlutterInsiderAppCards client directly
FlutterInsider.Instance.appCards.clickButton(button);

// Or using the convenience method on the button
button.click();

Full Integration Example

Below is a complete example showing how to retrieve, display, interact with, and manage cards.

final appCards = FlutterInsider.Instance.appCards;

try {
  final response = await appCards.getCampaigns();
  final cards = response?.appCards ?? [];

  for (final card in cards) {
    // Log view event
    card.view();

    // Display card content
    final content = card.content;
    if (content != null) {
      displayCard(content.title, content.description);
    }

    // Display images
    final images = card.images;
    if (images != null) {
      for (final image in images) {
        loadImage(image.url);
      }
    }

    // Handle buttons
    final buttons = card.buttons;
    if (buttons != null) {
      for (final button in buttons) {
        addButton(button.text, () => button.click());
      }
    }

    // Handle card-level action
    final action = card.action;
    if (action is InsiderAppCardDeeplinkAction) {
      final url = action.url;
      print('Action URL: $url Type: ${action.actionType}');
    }

    // Mark as read when user views
    if (!card.isRead) {
      try {
        await card.markAsRead();
        print('Marked as read: ${card.id}');
      } on InsiderAppCardsException catch (e) {
        print('Failed to mark as read: ${e.error.code}');
      }
    }
  }
} on InsiderAppCardsException catch (e) {
  print('Failed to get campaigns: ${e.error.code}');
}