Daten der Content-Cards

Beim Erstellen einer angepassten UI für Content Cards müssen Sie Analytics wie Impressionen, Klicks und Ausblendungen manuell protokollieren, da dies nur für Standard-Kartenmodelle automatisch erfolgt. Die Protokollierung dieser Ereignisse ist ein Standardbestandteil der Integration von Content Cards und für eine genaue Campaign-Berichterstattung und Abrechnung unerlässlich. Füllen Sie dazu Ihre angepasste UI mit Daten aus den Braze-Datenmodellen und protokollieren Sie die Ereignisse anschließend manuell. Sobald Sie wissen, wie man Analytics protokolliert, können Sie sehen, wie Braze-Kund:innen häufig angepasste Content Cards erstellen.

Analytics protokollieren

Wenn Sie Ihre eigenen Content Cards implementieren, können Sie die Content-Card-Objekte parsen und deren Nutzdaten wie title, cardDescription und imageUrl extrahieren. Anschließend können Sie die resultierenden Modelldaten verwenden, um Ihre angepasste UI zu befüllen.

Um die Content-Card-Datenmodelle zu erhalten, abonnieren Sie Content-Card-Updates. Es gibt zwei Eigenschaften, auf die Sie besonders achten sollten:

• id: Repräsentiert den Content-Card-ID-String. Dies ist der eindeutige Bezeichner, der verwendet wird, um Analytics von angepassten Content Cards zu protokollieren.
• extras: Umfasst alle Schlüssel-Wert-Paare aus dem Braze-Dashboard.

Alle Eigenschaften außerhalb von id und extras sind für angepasste Content Cards optional zu parsen. Weitere Informationen zum Datenmodell finden Sie im Integrationsartikel der jeweiligen Plattform: Android, iOS, Web.

• web
• android
• swift
• react native

Registrieren Sie eine Callback-Funktion, um Updates zu abonnieren, wenn Cards aktualisiert werden.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import * as braze from "@braze/web-sdk";

braze.subscribeToContentCardsUpdates((updates) => {
  const cards = updates.cards;
// For example:
  cards.forEach(card => {
    if (card.isControl) {
      // Do not display the control card, but remember to call `logContentCardImpressions([card])`
    }
    else if (card instanceof braze.ClassicCard || card instanceof braze.CaptionedImage) {
      // Use `card.title`, `card.imageUrl`, etc.
    }
    else if (card instanceof braze.ImageOnly) {
      // Use `card.imageUrl`, etc.
    }
  })
});

braze.openSession();

Hinweis

Content Cards werden nur beim Sitzungsstart aktualisiert, wenn ein Abonnement-Request vor openSession() aufgerufen wird. Sie können den Feed auch jederzeit manuell aktualisieren.

• java
• kotlin

Schritt 1: Erstellen Sie eine private Abonnent-Variable

Um Card-Updates zu abonnieren, deklarieren Sie zunächst eine private Variable in Ihrer angepassten Klasse, um Ihren Abonnenten zu speichern:

1
2

// subscriber variable
private IEventSubscriber<ContentCardsUpdatedEvent> mContentCardsUpdatedSubscriber;

Schritt 2: Updates abonnieren

Fügen Sie als Nächstes den folgenden Code hinzu, um Content-Card-Updates von Braze zu abonnieren – typischerweise innerhalb der Activity.onCreate()-Methode Ihrer angepassten Content-Cards-Activity:

1
2
3
4
5
6
7
8
9
10
11
12
13

// Remove the previous subscriber before rebuilding a new one with our new activity.
Braze.getInstance(context).removeSingleSubscription(mContentCardsUpdatedSubscriber, ContentCardsUpdatedEvent.class);
mContentCardsUpdatedSubscriber = new IEventSubscriber<ContentCardsUpdatedEvent>() {
    @Override
    public void trigger(ContentCardsUpdatedEvent event) {
        // List of all Content Cards
        List<Card> allCards = event.getAllCards();

        // Your logic below
    }
};
Braze.getInstance(context).subscribeToContentCardsUpdates(mContentCardsUpdatedSubscriber);
Braze.getInstance(context).requestContentCardsRefresh();

Schritt 3: Abonnement beenden

Wir empfehlen außerdem, das Abonnement zu beenden, wenn Ihre angepasste Activity nicht mehr sichtbar ist. Fügen Sie den folgenden Code zur onDestroy()-Lifecycle-Methode Ihrer Activity hinzu:

1

Braze.getInstance(context).removeSingleSubscription(mContentCardsUpdatedSubscriber, ContentCardsUpdatedEvent.class);

Schritt 1: Erstellen Sie eine private Abonnent-Variable

Um Card-Updates zu abonnieren, deklarieren Sie zunächst eine private Variable in Ihrer angepassten Klasse, um Ihren Abonnenten zu speichern:

1

private var contentCardsUpdatedSubscriber: IEventSubscriber<ContentCardsUpdatedEvent>? = null

Schritt 2: Updates abonnieren

Fügen Sie als Nächstes den folgenden Code hinzu, um Content-Card-Updates von Braze zu abonnieren – typischerweise innerhalb der Activity.onCreate()-Methode Ihrer angepassten Content-Cards-Activity:

1
2
3
4
5
6
7
8
9
10

// Remove the previous subscriber before rebuilding a new one with our new activity.
Braze.getInstance(context).removeSingleSubscription(contentCardsUpdatedSubscriber, ContentCardsUpdatedEvent::class.java)
contentCardsUpdatedSubscriber = IEventSubscriber { event ->
  // List of all Content Cards
  val allCards = event.allCards

  // Your logic below
}
Braze.getInstance(context).subscribeToContentCardsUpdates(contentCardsUpdatedSubscriber)
Braze.getInstance(context).requestContentCardsRefresh(true)

Schritt 3: Abonnement beenden

Wir empfehlen außerdem, das Abonnement zu beenden, wenn Ihre angepasste Activity nicht mehr sichtbar ist. Fügen Sie den folgenden Code zur onDestroy()-Lifecycle-Methode Ihrer Activity hinzu:

1

Braze.getInstance(context).removeSingleSubscription(contentCardsUpdatedSubscriber, ContentCardsUpdatedEvent::class.java)

Um auf das Content-Cards-Datenmodell zuzugreifen, rufen Sie contentCards.cards auf Ihrer braze-Instanz auf.

• swift
• objective-c

1

let cards: [Braze.ContentCard] = AppDelegate.braze?.contentCards.cards

Hinweis

Das Lesen von contentCards.cards, contentCards.unviewedCards oder contentCards.lastUpdate blockiert den aufrufenden Thread, bis das SDK seine Operationen nach der Initialisierung abgeschlossen hat. Verwenden Sie die nicht-blockierenden Getter unter Nicht-blockierende Snapshot-Zugriffe für Hauptthread- oder latenzempfindliche Kontexte.

Zusätzlich können Sie auch ein Abonnement aufrechterhalten, um Änderungen an Ihren Content Cards zu beobachten. Dies ist auf zwei Arten möglich:

1. Über ein Cancellable; oder
2. Über einen AsyncStream.

Cancellable

1
2
3
4
5
6

// This subscription is maintained through a Braze cancellable, which will observe for changes until the subscription is cancelled.
// You must keep a strong reference to the cancellable to keep the subscription active.
// The subscription is canceled either when the cancellable is deinitialized or when you call its `.cancel()` method.
let cancellable = AppDelegate.braze?.contentCards.subscribeToUpdates { [weak self] contentCards in
  // Implement your completion handler to respond to updates in `contentCards`.
}

AsyncStream

1

let stream: AsyncStream<[Braze.ContentCard]> = AppDelegate.braze?.contentCards.cardsStream

Nicht-blockierende Snapshot-Zugriffe

Verwenden Sie diese Methoden, um den aktuellen gecachten Status zu lesen, ohne den aufrufenden Thread zu blockieren. Jeder Completion-Handler wird immer auf dem Hauptthread ausgeliefert.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// All cached cards.
AppDelegate.braze?.contentCards.getCachedContentCards { cards in
  // Use `cards` here.
}

// Unviewed cards only (excludes control cards).
AppDelegate.braze?.contentCards.getUnviewedCards { cards in
  // Use `cards` here.
}

// Date of the last server sync for the current user (nil until the first sync completes).
AppDelegate.braze?.contentCards.getLastUpdate { date in
  // Use `date` here.
}

1

NSArray<BRZContentCardRaw *> *contentCards = AppDelegate.braze.contentCards.cards;

Wenn Sie zusätzlich ein Abonnement für Ihre Content Cards aufrechterhalten möchten, können Sie subscribeToUpdates aufrufen:

1
2
3
4

// This subscription is maintained through Braze cancellable, which will continue to observe for changes until the subscription is cancelled.
BRZCancellable *cancellable = [self.braze.contentCards subscribeToUpdates:^(NSArray<BRZContentCardRaw *> *contentCards) {
  // Implement your completion handler to respond to updates in `contentCards`.
}];

Um den aktuellen gecachten Status zu lesen, ohne den aufrufenden Thread zu blockieren, verwenden Sie die folgenden Methoden. Jeder Completion-Handler wird auf dem Hauptthread ausgeliefert.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// All cached cards.
[AppDelegate.braze.contentCards getCachedContentCardsWithCompletion:^(NSArray<BRZContentCardRaw *> *cards) {
  // Use `cards` here.
}];

// Unviewed cards only (excludes control cards).
[AppDelegate.braze.contentCards getUnviewedCardsWithCompletion:^(NSArray<BRZContentCardRaw *> *cards) {
  // Use `cards` here.
}];

// Date of the last server sync for the current user (nil until the first sync completes).
[AppDelegate.braze.contentCards getLastUpdateWithCompletion:^(NSDate * _Nullable date) {
  // Use `date` here.
}];

Um auf Updates zu lauschen, abonnieren Sie Content-Card-Update-Events:

1
2
3
4
5
6
7
8
9
10

const subscription = Braze.addListener(Braze.Events.CONTENT_CARDS_UPDATED, (update) => {
  const cards = update.cards;
  cards.forEach(card => {
    if (card.isControl) {
      // Do not display the control card, but remember to log an impression
    } else {
      // Use card.title, card.cardDescription, card.image, etc.
    }
  });
});

Um die zuletzt gecachten Content-Card-Daten abzurufen:

1
2
3

import Braze from "@braze/react-native-sdk";

const cachedCards = await Braze.getCachedContentCards();

Um eine manuelle Aktualisierung der Content Cards von den Braze-Servern anzufordern:

1

Braze.requestContentCardsRefresh();

Events protokollieren

Das Protokollieren wertvoller Metriken wie Impressionen, Klicks und Schließungen ist schnell und einfach. Richten Sie einen angepassten Klick-Listener ein, um diese Analytics manuell zu verarbeiten.

• web
• android
• swift
• react native

Protokollieren Sie Impression-Events, wenn Cards von Nutzer:innen angezeigt werden, mit logContentCardImpressions:

1
2
3

import * as braze from "@braze/web-sdk";

braze.logContentCardImpressions([card1, card2, card3]);

Protokollieren Sie Card-Klick-Events, wenn Nutzer:innen mit einer Card interagieren, mit logContentCardClick:

1
2
3

import * as braze from "@braze/web-sdk";

braze.logContentCardClick(card);

Der BrazeManager kann auf Braze-SDK-Abhängigkeiten wie die Array-Liste der Content-Card-Objekte verweisen, um das Card-Objekt abzurufen und die Braze-Protokollierungsmethoden aufzurufen. Verwenden Sie die ContentCardable-Basisklasse, um einfach auf Daten zu verweisen und sie dem BrazeManager bereitzustellen.

Um eine Impression oder einen Klick auf eine Card zu protokollieren, rufen Sie Card.logClick() bzw. Card.logImpression() auf.

Sie können eine Content-Card manuell protokollieren oder für eine bestimmte Card bei Braze als „geschlossen“ markieren, indem Sie isDismissed verwenden. Wenn eine Card bereits als geschlossen markiert ist, kann sie nicht erneut als geschlossen markiert werden.

Um einen angepassten Klick-Listener zu erstellen, erstellen Sie eine Klasse, die IContentCardsActionListener implementiert, und registrieren Sie sie bei BrazeContentCardsManager. Implementieren Sie die Methode onContentCardClicked(), die aufgerufen wird, wenn Nutzer:innen auf eine Content-Card klicken. Weisen Sie dann Braze an, Ihren Content-Card-Klick-Listener zu verwenden.

• java
• kotlin

Zum Beispiel:

1
2
3
4
5
6
7
8
9
10
11

BrazeContentCardsManager.getInstance().setContentCardsActionListener(new IContentCardsActionListener() {
  @Override
  public boolean onContentCardClicked(Context context, Card card, IAction cardAction) {
    return false;
  }

  @Override
  public void onContentCardDismissed(Context context, Card card) {

  }
});

Zum Beispiel:

1
2
3
4
5
6
7
8
9

BrazeContentCardsManager.getInstance().contentCardsActionListener = object : IContentCardsActionListener {
  override fun onContentCardClicked(context: Context, card: Card, cardAction: IAction): Boolean {
    return false
  }

  override fun onContentCardDismissed(context: Context, card: Card) {

  }
}

Wichtig

Um Kontrollvarianten-Content-Cards in Ihrer angepassten UI zu verarbeiten, übergeben Sie Ihr com.braze.models.cards.Card-Objekt und rufen Sie dann die logImpression-Methode auf, wie Sie es bei jedem anderen Content-Card-Typ tun würden. Das Objekt protokolliert implizit eine Kontroll-Impression, um unsere Analytics darüber zu informieren, wann Nutzer:innen die Kontroll-Card gesehen hätten.

Implementieren Sie das Protokoll BrazeContentCardUIViewControllerDelegate und setzen Sie Ihr Delegate-Objekt als delegate-Eigenschaft Ihres BrazeContentCardUI.ViewController. Dieses Delegate übernimmt die Übergabe der Daten Ihres angepassten Objekts an Braze zur Protokollierung. Ein Beispiel finden Sie im Content Cards UI Tutorial.

• swift
• objective-c

1
2
3
4
5
6
7
8
9
10
11
12

// Set the delegate when creating the Content Cards controller
contentCardsController.delegate = delegate

// Method to implement in delegate
func contentCard(
    _ controller: BrazeContentCardUI.ViewController,
    shouldProcess clickAction: Braze.ContentCard.ClickAction,
    card: Braze.ContentCard
  ) -> Bool {
  // Intercept the content card click action here.
  return true
}

1
2
3
4
5
6
7
8
9
10

// Set the delegate when creating the Content Cards controller
contentCardsController.delegate = delegate;

// Method to implement in delegate
- (BOOL)contentCardController:(BRZContentCardUIViewController *)controller
                shouldProcess:(NSURL *)url
                         card:(BRZContentCardRaw *)card {
  // Intercept the content card click action here.
  return YES;
}

Wichtig

Um Kontrollvarianten-Content-Cards in Ihrer angepassten UI zu verarbeiten, übergeben Sie Ihr Braze.ContentCard.Control-Objekt und rufen Sie dann die logImpression-Methode auf, wie Sie es bei jedem anderen Content-Card-Typ tun würden. Das Objekt protokolliert implizit eine Kontroll-Impression, um unsere Analytics darüber zu informieren, wann Nutzer:innen die Kontroll-Card gesehen hätten.

Protokollieren Sie Impression-Events, wenn Cards von Nutzer:innen angezeigt werden:

1

Braze.logContentCardImpression(card.id);

Protokollieren Sie Card-Klick-Events, wenn Nutzer:innen mit einer Card interagieren:

1

Braze.logContentCardClicked(card.id);

Protokollieren Sie Schließ-Events, wenn Nutzer:innen eine Card schließen:

1

Braze.logContentCardDismissed(card.id);

Verhalten bei Klick-Aktionen

• web
• android
• swift
• react native

Wenn Nutzer:innen in einem angepassten Feed auf eine Content-Card klicken, wird das Klick-Verhalten (z. B. Navigation zu einer URL, Deeplinking oder Protokollierung eines angepassten Events) nicht automatisch verarbeitet. Verwenden Sie handleBrazeAction, um die URL der Card zu verarbeiten und die konfigurierte Klick-Aktion auszuführen, einschließlich Braze-Aktionen (brazeActions://-URLs).

1
2
3
4
5
6
7
8
9
10
11
12

import * as braze from "@braze/web-sdk";

// In your card click handler
function onCardClick(card) {
  // Log the click
  braze.logContentCardClick(card);

  // Handle the on-click behavior
  if (card.url) {
    braze.handleBrazeAction(card.url);
  }
}

Parameter	Beschreibung
url	Eine gültige URL oder eine gültige Braze-Aktions-URL mit dem Schema brazeActions://.
openLinkInNewTab	(Optional) Ob die URL in einem neuen Tab geöffnet werden soll. Standardwert ist false.

Wichtig

Wenn Sie handleBrazeAction() nicht aufrufen, werden die im Braze-Dashboard konfigurierten Klick-Verhalten (z. B. „Angepasstes Event protokollieren“ oder „Zu URL navigieren“) für Cards in einem angepassten Feed nicht ausgeführt.

Das Klick-Verhalten wird von der standardmäßigen Content-Cards-UI automatisch verarbeitet. Für angepasste Implementierungen verwenden Sie die Schnittstelle IContentCardsActionListener, die unter Analytics protokollieren beschrieben ist.

Das Klick-Verhalten wird von der standardmäßigen Content-Cards-UI automatisch verarbeitet. Für angepasste Implementierungen verwenden Sie das Protokoll BrazeContentCardUIViewControllerDelegate, das unter Analytics protokollieren beschrieben ist.

Wenn Nutzer:innen in einem angepassten Feed auf eine Content-Card klicken, wird das Klick-Verhalten nicht automatisch verarbeitet. Nachdem Sie den Klick mit Braze.logContentCardClicked(cardId) protokolliert haben, rufen Sie Braze.processContentCardClickAction(cardId) auf, um Deeplinks, URLs und brazeActions://-Aktionen zu verarbeiten. Eine Methodenreferenz finden Sie unter React Native Content Cards.

1
2
3
4
5
6
7
8
9

import Braze from "@braze/react-native-sdk";

function onCardPress(card) {
  Braze.logContentCardClicked(card.id);

  if (card.url) {
    Braze.processContentCardClickAction(card.id);
  }
}

Wichtig

Wenn Sie processContentCardClickAction() nicht aufrufen, werden die im Braze-Dashboard konfigurierten Klick-Verhalten für Cards in einem angepassten Feed nicht ausgeführt.