Content Cards

note

This guide uses code samples from the Braze Web SDK 4.0.0+. To upgrade to the latest Web SDK version, see SDK Upgrade Guide.

Prerequisites

Before you can use Content Cards, you’ll need to integrate the Braze Web SDK into your app. However, no additional setup is required. To build your own UI instead, see Content Card Customization Guide.

note

Some ad blockers and browser privacy extensions can block the Braze Web SDK script or related network requests, which can prevent Content Cards from loading. If you’re using the CDN integration method, consider switching to the NPM integration method, which stores SDK libraries locally on your website and can avoid some ad-blocker-related issues.

Standard feed UI

To use the included Content Cards UI, you’ll need to specify where to show the feed on your website.

In this example, we have a <div id="feed"></div> in which we want to place the Content Cards feed. We’ll use three buttons to hide, show, or toggle (hide or show based on its current state) the feed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<button id="toggle" type="button">Toggle Cards Feed</button>
<button id="hide" type="button">Hide Cards Feed</button>
<button id="show" type="button">Show Cards Feed</button>

<nav>
    <h1>Your Personalized Feed</h1>
    <div id="feed"></div>
</nav>

<script> 
   const toggle = document.getElementById("toggle");
   const hide = document.getElementById("hide");
   const show = document.getElementById("show");
   const feed = document.getElementById("feed");
    
   toggle.onclick = function(){
      braze.toggleContentCards(feed);    
   }
    
   hide.onclick = function(){
      braze.hideContentCards();
   }
    
   show.onclick = function(){
      braze.showContentCards(feed);    
   }
</script>

When using the toggleContentCards(parentNode, filterFunction) and showContentCards(parentNode, filterFunction) methods, if no arguments are provided, all Content Cards will be shown in a fixed-position sidebar on the right-hand side of the page. Otherwise, the feed will be placed in the specified parentNode option.

See the SDK reference docs for more information on Content Card toggling.

Testing Content Cards on the web

You can test your Content Cards integration using your browser’s developer tools.

1. Create a Content Card campaign and target your test user.
2. Log in to the website that has your Web SDK integration.
3. Open your browser console. For Chrome, right-click the page, select Inspect, then select the Console tab.
4. Run these commands in the console:
   • window.braze.getCachedContentCards()
   • window.braze.toggleContentCards()

Card types and properties

The Content Cards data model is available in the Web SDK and offers the following Content Card types: ImageOnly, CaptionedImage, and ClassicCard. Each type inherits common properties from a base model Card and has the following additional properties.

tip

To log Content Card data, see Logging analytics.

Base card model

All Content Cards have these shared properties:

Image only

ImageOnly cards are clickable full-sized images.

Captioned image

CaptionedImage cards are clickable, full-sized images with accompanying descriptive text.

Classic

The ClassicCard model can contain an image with no text or a text with image.

Control group

If you use the default Content Cards feed, impressions and clicks will be automatically tracked.

If you use a custom integration for Content Cards, you need need log impressions when a Control Card would have been seen. As part of this effort, make sure to handle Control cards when logging impressions in an A/B test. These cards are blank, and while they aren’t seen by users, you should still log impressions in order to compare how they perform against non-Control cards.

To determine if a Content Card is in the Control group for an A/B test, check the card.isControl property (Web SDK v4.5.0+) or check if the card is a ControlCard instance (card instanceof braze.ControlCard).

Card methods

Default feed methods

Use these methods when displaying Content Cards using the Braze default feed UI:

Custom feed methods

Use these methods when building your own Content Card UI:

For more details, refer to the SDK reference documentation.

Best practices

Call methods in the correct order

For custom feeds, Content Cards refresh only on session start if subscribeToContentCardsUpdates() is called before openSession(). Call your Braze methods in this order:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import * as braze from "@braze/web-sdk";

// Step 1: Initialize the SDK
braze.initialize("YOUR-API-KEY", { baseUrl: "YOUR-SDK-ENDPOINT" });

// Step 2: Subscribe to card updates
braze.subscribeToContentCardsUpdates((updates) => {
  const cards = updates.cards;
  renderCards(cards);
});

// Step 3: Identify the user
braze.changeUser("USER_ID");

// Step 4: Start the session
braze.openSession();

Use cached cards to persist content across page loads

Because subscribeToContentCardsUpdates() invokes only its callback when there are new updates (such as on session start), cards can disappear from your custom feed if a user refreshes the page mid-session. To prevent this, use getCachedContentCards() to immediately render cards from the local cache, alongside your subscription for new updates:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import * as braze from "@braze/web-sdk";

function renderCards(cards) {
  const container = document.getElementById("content-cards");
  container.textContent = "";
  const displayedCards = [];

  cards.forEach(card => {
    if (card instanceof braze.ClassicCard || card instanceof braze.CaptionedImage) {
      const cardElement = document.createElement("div");

      const h3 = document.createElement("h3");
      h3.textContent = card.title || "";
      cardElement.appendChild(h3);

      const p = document.createElement("p");
      p.textContent = card.description || "";
      cardElement.appendChild(p);

      if (card.imageUrl) {
        const img = document.createElement("img");
        img.src = card.imageUrl;
        img.alt = card.title || "";
        cardElement.appendChild(img);
      }

      if (card.url) {
        cardElement.addEventListener("click", () => {
          braze.logContentCardClick(card);
          braze.handleBrazeAction(card.url);
        });
      }

      container.appendChild(cardElement);
      displayedCards.push(card);
    }
  });

  if (displayedCards.length > 0) {
    braze.logContentCardImpressions(displayedCards);
  }
}

// Display cached cards immediately
const cached = braze.getCachedContentCards();
if (cached && cached.cards.length > 0) {
  renderCards(cached.cards);
}

// Subscribe to future updates
braze.subscribeToContentCardsUpdates((updates) => {
  renderCards(updates.cards);
});

Log analytics for custom feeds

When using a custom UI, impressions, clicks, and dismissals are not tracked automatically. You must log each event manually:

• Impressions: Call logContentCardImpressions([card1, card2, ...]) with an array of card objects when cards become visible to the user.
• Clicks: Call logContentCardClick(card) when a user interacts with a card.
• On-click behavior: Call handleBrazeAction(card.url) to execute the card’s configured on-click action (such as navigating to a URL or logging a custom event).

warning

The argument passed to logContentCardClick() must be an original Braze Card object. If you transform or reconstruct the card data (for example, by serializing and deserializing), clicks are not logged and you see the error: “card must be a Card object.”

Using Google Tag Manager

Google Tag Manager works by injecting the Braze CDN (a version of our Web SDK) directly into your website code, which means that all SDK methods are available just as if you had integrated the SDK without Google Tag Manager, except when implementing Content Cards.

Setting up Content Cards

• google tag manager
• manual

1
2
3
<script>
   window.braze.showContentCards();
</script>

1
2
3
body .ab-feed { 
    width: 800px;
}

Upgrading templates

To upgrade to the latest version of the Braze Web SDK, take the following three steps in your Google Tag Manager dashboard:

1. Update tag template
   Go to the Templates page within your workspace. Here you should see an icon indicating an update is available.
   
   
   
   Click that icon and after reviewing the change, click to Accept Update.
   
   
   
   
2. Update version number
   Once your tag template has been updated, edit the Braze Initialization Tag, and update the SDK version to the most recent major.minor version. For example, if the latest version is 4.1.2, enter 4.1. You can view a list of SDK versions in our changelog.
   
   
   
   
3. QA and publish
   Verify the new SDK version is working using Google Tag Manager’s debugging tool prior to publishing an update to your tag container.

Troubleshooting

Enable tag debugging

Each Braze tag template has an optional GTM Tag Debugging checkbox which can be used to log debug messages to your web page’s JavaScript console.

Enter debug mode

Another way to help debug your Google Tag Manager integration is using Google’s Preview mode feature.

This will help identify what values are being sent from your web page’s data layer to each triggered Braze tag and will also explain which tags were or were not triggered.

Verify tag sequencing for custom events

If custom events or other actions aren’t logging in Braze, a common cause is a race condition where an action tag (such as Custom Event or Purchase) fires before the Braze Initialization tag has completed. To fix this, configure tag sequencing in GTM:

1. Open the action tag that isn’t logging correctly.
2. Under Advanced Settings > Tag Sequencing, select A tag that fires before [this tag].
3. Choose your Braze Initialization tag as the setup tag.

This ensures the SDK is fully initialized before any action tags attempt to send data to Braze.

Enable verbose logging

To capture detailed logs for troubleshooting, you can enable verbose logging on your Google Tag Manager integration. These logs will appear in the Console tab of your browser’s developer tools.

In your Google Tag Manager integration, navigate to your Braze Initialization Tag and select Enable Web SDK Logging.