Campaigns

Deliver targeted, rich notifications to users via an in-app notification feed powered by the CometChat Cards renderer.

CometChat Campaigns enables you to send rich, interactive notifications to users through an in-app notification feed. Each notification is rendered as a native card using the CometChat Cards library — supporting images, text, buttons, layouts, and interactive actions.

---

Overview

Campaigns delivers notifications as Card Schema JSON — a structured format that defines the visual layout of each notification card. The system consists of three layers:

1. CometChat Chat SDK — Fetches feed items, manages read/delivered state, provides real-time listeners, handles push notification tracking
2. CometChat Cards Library — Renders Card Schema JSON into native Android views (Jetpack Compose and XML Views)
3. CometChat UI Kit — Provides the ready-to-use CometChatNotificationFeed component that wires everything together

Architecture Flow

Dashboard / API → Campaign Created → Push + WebSocket Delivery
                                            ↓
                                     SDK: NotificationFeedRequest.fetchNext()
                                            ↓
                                     NotificationFeedItem.getContent() → Card Schema JSON
                                            ↓
                                     Cards Library: CometChatCardView / CometChatCardComposable
                                            ↓
                                     Native Rendered Card (images, text, buttons, layouts)
                                            ↓
                                     User taps button → ActionCallback → Your code handles it

---

How Cards Work

Each NotificationFeedItem from the SDK contains a content field — a JSONObject holding the Card Schema JSON. This JSON is passed directly to the CometChat Cards renderer which produces a native view.

The Cards library is a pure renderer:

• Input: Card Schema JSON string + theme mode + optional action callback
• Output: Native Android view hierarchy

It does not execute actions, manage message state, or call any SDK methods. When users tap interactive elements (buttons, links), the library emits the action to your callback. You decide what happens — open a URL, navigate to a chat, make an API call, etc.

Card Schema JSON Example

{
  "version": "1.0",
  "body": [
    { "type": "image", "id": "img_1", "url": "https://cdn.example.com/sale.jpg", "height": 180, "fit": "cover", "borderRadius": 8 },
    { "type": "text", "id": "txt_1", "content": "🎉 Flash Sale — 40% Off!", "variant": "heading2" },
    { "type": "text", "id": "txt_2", "content": "Limited time offer on all premium plans.", "variant": "body" },
    { "type": "button", "id": "btn_1", "label": "Claim Offer", "action": { "type": "openUrl", "url": "https://example.com/offer" }, "fullWidth": true }
  ],
  "style": { "background": {"light": "#FFFFFF", "dark": "#1E1E1E"}, "borderRadius": 12, "padding": 16 },
  "fallbackText": "Flash Sale — 40% Off! Claim your offer: https://example.com/offer"
}

The schema supports 20 element types (text, image, icon, avatar, badge, divider, spacer, chip, progressBar, codeBlock, markdown, row, column, grid, accordion, tabs, button, iconButton, link, table) and 9 action types (openUrl, chatWithUser, chatWithGroup, sendMessage, copyToClipboard, downloadFile, initiateCall, apiCall, customCallback).

---

How Cards Work in the UI Kit

The CometChatNotificationFeed component uses the CometChat Cards library internally to render each notification. Here’s what happens under the hood:

1. The component fetches NotificationFeedItem objects from the SDK
2. For each item, it extracts the content field (Card Schema JSON)
3. It passes the JSON to CometChatCardComposable (Compose) or CometChatCardView (XML) from the Cards library
4. The Cards renderer produces native UI — text, images, buttons, layouts — directly from the JSON
5. When users tap buttons/links inside a card, the action is emitted back to the component which handles navigation (open URL, navigate to chat, etc.)

You don’t need to interact with the Cards library directly when using CometChatNotificationFeed — it’s all wired up. But if you want to render cards outside the feed (e.g., a standalone card in a dialog), you can use the Cards library directly. See the SDK Campaigns documentation for standalone usage.

---

Handling Push Notifications for Campaigns

When a campaign push notification arrives via FCM, you should:

1. Report delivery — Call CometChat.markPushNotificationDelivered() in your FirebaseMessagingService
2. Report click — Call CometChat.markPushNotificationClicked() when the user taps the notification
3. Deep link — Use the announcement ID from the push payload to fetch the full item via CometChat.getNotificationFeedItem(id) and display it

// In FirebaseMessagingService.onMessageReceived()
val pushNotification = PushNotification.fromJson(data)
CometChat.markPushNotificationDelivered(pushNotification, ...)

// When user taps the notification
CometChat.markPushNotificationClicked(pushNotification, ...)

// Navigate to feed or show specific item
CometChat.getNotificationFeedItem(pushNotification.id, ...)

See the SDK Campaigns documentation for the complete push notification tracking API.

---

Sending Campaigns

Campaigns are created and managed from the CometChat Dashboard or via the REST API. The SDK and UI Kit are consumer-side — they display and interact with campaigns, not create them.

To send campaigns:

• Dashboard: Navigate to Campaigns → Create Campaign → Define audience, content (Card Schema), and delivery channel
• REST API: Use the Campaigns API to programmatically create and schedule campaigns

---

Using the UI Kit Component

The easiest way to add a notification feed to your app is the CometChatNotificationFeed component. It handles fetching, rendering, pagination, filtering, real-time updates, and engagement reporting out of the box.

Jetpack Compose

@Composable
fun NotificationsScreen() {
    CometChatNotificationFeed(
        modifier = Modifier.fillMaxSize(),
        onItemClick = { item ->
            // Handle item tap
        },
        onBackPress = { /* navigate back */ }
    )
}

Kotlin (XML Views)

<com.cometchat.uikit.kotlin.presentation.notificationfeed.ui.CometChatNotificationFeed
    android:id="@+id/notificationFeed"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

val feed = findViewById<CometChatNotificationFeed>(R.id.notificationFeed)
feed.init(this) // Pass ViewModelStoreOwner
feed.onItemClick = { item -> /* handle tap */ }

See the full CometChatNotificationFeed component documentation for all configuration options, styling, and customization.

---

Next Steps

SDK Campaigns API

Full API reference for feed items, categories, engagement, and push tracking

CometChatNotificationFeed

Ready-to-use component with filtering, real-time updates, and styling