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 in Ihre App integrieren. Es ist jedoch 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 einen Wechsel zur NPM-Integrationsmethode in Betracht ziehen, die SDK-Bibliotheken lokal auf Ihrer Website speichert und einige Probleme im Zusammenhang mit Werbeblockern vermeiden kann.

Standard-Feed-UI

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

In diesem Beispiel möchten wir den Content-Cards-Feed in <div id="feed"></div> platzieren. Wir verwenden drei Buttons, um den Feed auszublenden, einzublenden oder umzuschalten (d. h. je nach aktuellem Status aus- oder einzublenden).

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 angeben, werden alle Content Cards in einer Seitenleiste mit fester Position auf der rechten Seite der Seite angezeigt. Andernfalls wird der Feed in der angegebenen Option parentNode platziert.

In der SDK-Referenzdokumentation finden Sie weitere Informationen zum Umschalten von Content Cards.

Content Cards im Web testen

Sie können Ihre Content-Cards-Integration mit den Entwicklertools Ihres Browsers testen.

1. Erstellen Sie eine Content-Card-Kampagne 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 Browser-Konsole. In Chrome rechtsklicken Sie auf die Seite, wählen Sie Untersuchen und dann den Tab Konsole.
4. Führen Sie diese Befehle in der Konsole aus:
   • window.braze.getCachedContentCards()
   • window.braze.toggleContentCards()

Kartentypen und Eigenschaften

Das Content-Cards-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

Um Content-Card-Daten zu protokollieren, siehe Analytics protokollieren.

Basis-Kartenmodell

Alle Content Cards haben diese gemeinsamen Eigenschaften:

Nur Bild

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

Bildunterschrift

CaptionedImage-Karten sind anklickbare Bilder in voller Größe mit begleitendem beschreibendem Text.

Klassisch

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

Kontrollgruppe

Wenn Sie den standardmäßigen Content-Cards-Feed verwenden, werden Impressionen und Klicks automatisch getrackt.

Wenn Sie eine angepasste Integration für Content Cards verwenden, müssen Sie Impressionen protokollieren, wenn eine Kontrollgruppen-Karte gesehen worden wäre. Achten Sie darauf, dass Sie bei der Protokollierung der Impressionen in einem A/B-Test auch die Kontrollgruppen-Karten berücksichtigen. Diese Karten sind leer, und obwohl sie von den Nutzer:innen nicht gesehen werden, sollten Sie dennoch Impressionen protokollieren, um zu vergleichen, wie sie im Vergleich zu Nicht-Kontrollkarten abschneiden.

Um festzustellen, ob sich eine Content Card in der Kontrollgruppe für einen A/B-Test befindet, prüfen Sie die Eigenschaft card.isControl (Web SDK v4.5.0+) oder prüfen Sie, ob die Karte eine Instanz des Typs ControlCard ist (card instanceof braze.ControlCard).

Karten-Methoden

Standard-Feed-Methoden

Verwenden Sie diese Methoden, wenn Sie Content Cards mit der standardmäßigen Braze-Feed-UI anzeigen:

Methoden für angepasste Feeds

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

Weitere Einzelheiten 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 Karten verwenden, um Inhalte über Seitenladevorgänge hinweg beizubehalten

Da subscribeToContentCardsUpdates() seinen Callback nur bei neuen Updates aufruft (z. B. beim Sitzungsstart), können Karten aus Ihrem angepassten Feed verschwinden, wenn eine:ein Nutzer:in die Seite während einer Sitzung aktualisiert. Um dies zu verhindern, verwenden Sie getCachedContentCards(), um Karten sofort aus dem lokalen Cache zu rendern, zusammen mit 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 getrackt. Sie müssen jedes Event manuell protokollieren:

• Impressionen: Rufen Sie logContentCardImpressions([card1, card2, ...]) mit einem Array von Kartenobjekten auf, wenn Karten für die:den Nutzer:in sichtbar werden.
• Klicks: Rufen Sie logContentCardClick(card) auf, wenn eine:ein Nutzer:in mit einer Karte interagiert.
• Klick-Verhalten: Rufen Sie handleBrazeAction(card.url) auf, um die konfigurierte Klick-Aktion der Karte 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 Kartendaten transformieren oder rekonstruieren (z. B. durch Serialisierung und Deserialisierung), werden Klicks nicht protokolliert und Sie sehen den Fehler: „card must be a Card object.“

Google Tag Manager verwenden

Google Tag Manager funktioniert, indem das Braze CDN (eine Version unseres Web SDK) direkt in den Code Ihrer Website eingespeist wird. Das bedeutet, dass alle SDK-Methoden genauso verfügbar sind, als hätten Sie das SDK ohne Google Tag Manager integriert – außer bei 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 ein Upgrade auf die neueste Version des Braze Web SDK durchzuführen, führen Sie die folgenden drei Schritte im Google Tag Manager-Dashboard aus:

1. Tag-Template aktualisieren
   Rufen Sie die Seite Templates in Ihrem Workspace auf. Hier sollten Sie ein Symbol sehen, das anzeigt, 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
   Nachdem Sie das Tag-Template aktualisiert haben, bearbeiten Sie das Braze-Initialisierungs-Tag und aktualisieren die SDK-Version auf die neueste Version im Format major.minor. 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
   Vergewissern Sie sich, dass die neue SDK-Version funktioniert, indem Sie das Debugging-Tool von Google Tag Manager verwenden, 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 Sie Debug-Nachrichten in der JavaScript-Konsole Ihrer Webseite protokollieren können.

Debugging-Modus aufrufen

Eine weitere Möglichkeit, Ihre Google Tag Manager-Integration zu debuggen, ist die Verwendung der Google-Funktion Vorschaumodus.

Auf diese Weise können Sie feststellen, welche Werte von der Datenebene Ihrer Webseite an die einzelnen ausgelösten Braze-Tags gesendet werden, und Sie erfahren, welche Tags ausgelöst wurden und welche nicht.

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) vor dem Braze Initialization-Tag ausgelöst wird. 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].
3. Wählen Sie Ihr Braze Initialization-Tag als Setup-Tag.

Dies stellt sicher, dass das SDK vollständig initialisiert ist, bevor Aktions-Tags versuchen, Daten an Braze zu senden.

Ausführliche Protokollierung aktivieren

Um detaillierte Protokolle für die Fehlerbehebung zu erfassen, können Sie die ausführliche Protokollierung in Ihrer Google Tag Manager-Integration aktivieren. Diese Protokolle erscheinen im Tab Console der Entwicklertools Ihres Browsers.

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