Content Cards

Hinweis

Diese Anleitung verwendet Codebeispiele aus dem Braze Web SDK 4.0.0+. Um ein Upgrade auf die neueste Web SDK-Version durchzuführen, siehe SDK Upgrade Guide.

Voraussetzungen

Bevor Sie Content Cards verwenden können, müssen Sie das Braze Web SDK integrieren. Es ist keine zusätzliche Einrichtung erforderlich. Wenn Sie stattdessen eine eigene UI erstellen möchten, lesen Sie den Leitfaden zur Anpassung von Content Cards.

Hinweis

Einige Werbeblocker und Browser-Datenschutzerweiterungen können das Braze Web SDK-Skript oder zugehörige Netzwerkanfragen blockieren, was dazu führen kann, dass Content Cards nicht geladen werden. Wenn Sie die CDN-Integrationsmethode verwenden, sollten Sie zur NPM-Integrationsmethode wechseln, die SDK-Bibliotheken lokal auf Ihrer Website speichert und einige Probleme im Zusammenhang mit Werbeblockern vermeiden kann.

Standard-Feed-UI

Um die enthaltene Content-Cards-UI zu verwenden, müssen Sie angeben, wo der Feed auf Ihrer Website angezeigt werden soll.

In diesem Beispiel haben wir ein <div id="feed"></div>, in das wir den Content-Cards-Feed platzieren möchten. Wir verwenden drei Buttons, um den Feed auszublenden, anzuzeigen oder umzuschalten (basierend auf seinem aktuellen Status aus- oder einblenden).

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>

Wenn Sie die Methoden toggleContentCards(parentNode, filterFunction) und showContentCards(parentNode, filterFunction) verwenden und keine Argumente übergeben werden, werden alle Content Cards in einer fixierten Seitenleiste auf der Seite angezeigt. Andernfalls wird der Feed in der angegebenen parentNode-Option platziert.

Weitere Informationen finden Sie in der SDK-Referenzdokumentation zum Umschalten von Content Cards.

Content Cards im Web testen

Sie können Ihre Content-Cards-Integration mithilfe der Entwickler:innen-Tools Ihres Browsers testen.

1. Erstellen Sie eine Content-Card-Campaign und richten Sie sie auf Ihre:n Testnutzer:in aus.
2. Melden Sie sich auf der Website an, auf der Ihre Web-SDK-Integration eingerichtet ist.
3. Öffnen Sie die Browserkonsole. In Chrome klicken Sie mit der rechten Maustaste auf die Seite, wählen Sie Untersuchen und dann den Tab Konsole aus.
4. Führen Sie diese Befehle in der Konsole aus:
   • window.braze.getCachedContentCards()
   • window.braze.toggleContentCards()

Card-Typen und Eigenschaften

Das Content-Card-Datenmodell ist im Web SDK verfügbar und bietet die folgenden Content-Card-Typen: ImageOnly, CaptionedImage und ClassicCard. Jeder Typ erbt gemeinsame Eigenschaften von einem Basismodell Card und hat die folgenden zusätzlichen Eigenschaften.

Tipp

Informationen zum Protokollieren von Content-Card-Daten finden Sie unter Analytics protokollieren.

Basis-Card-Modell

Alle Content Cards haben diese gemeinsamen Eigenschaften:

Nur Bild

ImageOnly-Cards sind anklickbare Bilder in voller Größe.

Bild mit Untertitel

CaptionedImage-Cards sind anklickbare Bilder in voller Größe mit beschreibendem Begleittext.

Klassisch

Das ClassicCard-Modell kann ein Bild ohne Text oder einen Text mit Bild enthalten.

Bildformate

Content-Card-Bilder (einschließlich GIFs) werden mit Standard-HTML-<img>-Tags gerendert. Die GIF-Unterstützung hängt von den Fähigkeiten des Browsers der Nutzer:innen ab und erfordert keine Mindestversion des Web SDK. Alle modernen Browser unterstützen die GIF-Wiedergabe nativ.

Kontrollgruppe

Wenn Sie den Standard-Feed für Content Cards verwenden, werden Impressionen und Klicks automatisch erfasst.

Wenn Sie eine angepasste Integration für Content Cards verwenden, müssen Sie Impressionen protokollieren, wenn eine Kontroll-Card angezeigt worden wäre. Stellen Sie dabei sicher, dass Sie Kontroll-Cards beim Protokollieren von Impressionen in einem A/B-Test berücksichtigen. Diese Cards sind leer, und obwohl sie von den Nutzer:innen nicht gesehen werden, sollten Sie dennoch Impressionen protokollieren, um ihre Performance mit Nicht-Kontroll-Cards vergleichen zu können.

Um festzustellen, ob eine Content-Card zur Kontrollgruppe eines A/B-Tests gehört, prüfen Sie die Eigenschaft card.isControl (Web SDK v4.5.0+) oder überprüfen Sie, ob die Card eine ControlCard-Instanz ist (card instanceof braze.ControlCard).

Card-Methoden

Standard-Feed-Methoden

Verwenden Sie diese Methoden, wenn Sie Content Cards mit der Standard-Feed-UI von Braze anzeigen:

Angepasste Feed-Methoden

Verwenden Sie diese Methoden, wenn Sie Ihre eigene Content-Card-UI erstellen:

Weitere Details finden Sie in der SDK-Referenzdokumentation.

Best Practices

Methoden in der richtigen Reihenfolge aufrufen

Bei angepassten Feeds werden Content Cards nur beim Sitzungsstart aktualisiert, wenn subscribeToContentCardsUpdates() vor openSession() aufgerufen wird. Rufen Sie Ihre Braze-Methoden in dieser Reihenfolge auf:

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();

Gecachte Cards verwenden, um Inhalte über Seitenladevorgänge hinweg beizubehalten

Da subscribeToContentCardsUpdates() seinen Callback nur aufruft, wenn neue Updates vorliegen (z. B. beim Sitzungsstart), können Cards aus Ihrem angepassten Feed verschwinden, wenn Nutzer:innen die Seite mitten in einer Sitzung aktualisieren. Um dies zu verhindern, verwenden Sie getCachedContentCards(), um Cards sofort aus dem lokalen Cache zu rendern, zusätzlich zu Ihrem Abo für neue 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);
});

Analytics für angepasste Feeds protokollieren

Bei Verwendung einer angepassten UI werden Impressionen, Klicks und Schließungen nicht automatisch erfasst. Sie müssen jedes Ereignis manuell protokollieren:

• Impressionen: Rufen Sie logContentCardImpressions([card1, card2, ...]) mit einem Array von Card-Objekten auf, wenn Cards für die Nutzer:innen sichtbar werden.
• Klicks: Rufen Sie logContentCardClick(card) auf, wenn Nutzer:innen mit einer Card interagieren.
• Klickverhalten: Rufen Sie handleBrazeAction(card.url) auf, um die konfigurierte Klickaktion der Card auszuführen (z. B. Navigation zu einer URL oder Protokollierung eines angepassten Events).

Warnung

Das an logContentCardClick() übergebene Argument muss ein originales Braze-Card-Objekt sein. Wenn Sie die Card-Daten transformieren oder rekonstruieren (z. B. durch Serialisierung und Deserialisierung), werden Klicks nicht protokolliert und Sie sehen den Fehler: „card must be a Card object.“

Verwendung von Google Tag Manager

Google Tag Manager funktioniert, indem das Braze CDN (eine Version unseres Web-SDK) direkt in Ihren Website-Code eingespeist wird. Das bedeutet, dass alle SDK-Methoden verfügbar sind, genau wie bei einer Integration des SDK ohne Google Tag Manager – mit Ausnahme der Implementierung von Content Cards.

Content Cards einrichten

• google tag manager
• manuell

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

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

Templates upgraden

Um auf die neueste Version des Braze Web SDK zu upgraden, führen Sie die folgenden drei Schritte in Ihrem Google Tag Manager-Dashboard aus:

1. Tag-Template aktualisieren
   Gehen Sie zur Seite Templates in Ihrem Workspace. Hier sollten Sie ein Symbol sehen, das darauf hinweist, dass ein Update verfügbar ist.
   
   
   
   Klicken Sie auf dieses Symbol und klicken Sie nach Überprüfung der Änderung auf Accept Update.
   
   
   
   
2. Versionsnummer aktualisieren
   Sobald Ihr Tag-Template aktualisiert wurde, bearbeiten Sie das Braze Initialization Tag und aktualisieren Sie die SDK-Version auf die neueste major.minor-Version. Wenn die neueste Version beispielsweise 4.1.2 ist, geben Sie 4.1 ein. Sie können eine Liste der SDK-Versionen in unserem Changelog einsehen.
   
   
   
   
3. QA und Veröffentlichung
   Überprüfen Sie die neue SDK-Version mit dem Debugging-Tool von Google Tag Manager, bevor Sie ein Update für Ihren Tag-Container veröffentlichen.

Fehlerbehebung

Tag-Debugging aktivieren

Jedes Braze-Tag-Template verfügt über ein optionales Kontrollkästchen GTM Tag Debugging, mit dem Debug-Nachrichten in der JavaScript-Konsole Ihrer Webseite protokolliert werden können.

Debug-Modus aufrufen

Eine weitere Möglichkeit, das Debugging Ihrer Google Tag Manager-Integration zu unterstützen, ist die Verwendung des Vorschaumodus von Google.

Dies hilft dabei, zu identifizieren, welche Werte von der Datenschicht Ihrer Webseite an jedes ausgelöste Braze-Tag gesendet werden, und erklärt auch, welche Tags ausgelöst oder nicht ausgelöst wurden.

Tag-Reihenfolge für angepasste Events überprüfen

Wenn angepasste Events oder andere Aktionen nicht in Braze protokolliert werden, ist eine häufige Ursache eine Race-Condition, bei der ein Aktions-Tag (z. B. Custom Event oder Purchase) ausgelöst wird, bevor das Braze Initialization-Tag abgeschlossen ist. Um dies zu beheben, konfigurieren Sie die Tag-Reihenfolge in GTM:

1. Öffnen Sie das Aktions-Tag, das nicht korrekt protokolliert wird.
2. Wählen Sie unter Advanced Settings > Tag Sequencing die Option A tag that fires before [this tag] aus.
3. Wählen Sie Ihr Braze Initialization-Tag als Setup-Tag aus.

Dadurch wird sichergestellt, dass das SDK vollständig initialisiert ist, bevor Aktions-Tags versuchen, Daten an Braze zu senden.

Ausführliches Logging aktivieren

Um detaillierte Protokolle für die Fehlerbehebung zu erfassen, können Sie ausführliches Logging für Ihre Google Tag Manager-Integration aktivieren. Diese Protokolle werden im Tab Console der Entwicklertools Ihres Browsers angezeigt.

Navigieren Sie in Ihrer Google Tag Manager-Integration zu Ihrem Braze Initialization Tag und wählen Sie Enable Web SDK Logging aus.