Passer au contenu

Enregistrer les analyses

Lors de la création d’une interface utilisateur personnalisée pour les Content Cards, vous devez enregistrer manuellement les données analytiques telles que les impressions, les clics et les rejets, car cela n’est géré automatiquement que pour les modèles de cartes par défaut. L’enregistrement de ces événements fait partie intégrante de l’intégration des Content Cards et est essentiel pour garantir l’exactitude des rapports et de la facturation des Campaigns. Pour ce faire, alimentez votre interface utilisateur personnalisée avec les données provenant des modèles de données Braze, puis enregistrez manuellement les événements. Une fois que vous avez compris comment enregistrer les données analytiques, vous pouvez découvrir les façons courantes dont les clients de Braze créent des Content Cards personnalisées.

Journalisation des analyses

Lors du déploiement de vos Content Cards personnalisées, vous pouvez analyser les objets Content Card et en extraire les données utiles telles que title, cardDescription et imageUrl. Vous pouvez ensuite utiliser les données du modèle obtenu pour alimenter votre interface utilisateur personnalisée.

Pour obtenir les modèles de données des Content Cards, abonnez-vous aux mises à jour des Content Cards. Deux propriétés méritent une attention particulière :

  • id : Représente la chaîne d’identification de la Content Card. Il s’agit de l’identifiant unique utilisé pour journaliser les analyses à partir de Content Cards personnalisées.
  • extras : Englobe toutes les paires clé-valeur du tableau de bord de Braze.

Toutes les propriétés en dehors de id et extras sont facultatives pour l’analyse des Content Cards personnalisées. Pour plus d’informations sur le modèle de données, consultez l’article d’intégration de chaque plateforme : Android, iOS, Web.

Enregistrez une fonction de rappel avec subscribeToContentCardsEvents() pour recevoir les cartes en cache et les mises à jour lorsque les cartes sont actualisées.




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

// - Available in version 7.0.0+
braze.subscribeToContentCardsEvents((event) => {
  switch (event.type) {
    case braze.ChannelEventType.CACHE_REPLAY:
    case braze.ChannelEventType.CACHE_LOAD:
    case braze.ChannelEventType.DATA_UPDATED: {
      const cards = event.cacheSnapshot.contentCards.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.
        }
      });
      break;
    }
    case braze.ChannelEventType.ERROR:
      // Check `event.reason` and `event.retryState`
      break;
  }
});

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

Utilisez subscribeToContentCardsEvents à partir de la version 7.0.0 du SDK Web. subscribeToContentCardsUpdates est l’ancien modèle, déprécié à partir de la version 7.0.0.

Pour la liste complète des événements que vous pouvez recevoir, consultez Créer des Content Cards.

Étape 1 : Créer une variable d’abonnement privée

Pour vous abonner aux événements de carte, déclarez d’abord une variable privée dans votre classe personnalisée pour stocker votre abonné :




// - Available in version 44.0.0+
private IEventSubscriber<ContentCardsEvent> mContentCardsEventSubscriber;

private IEventSubscriber<ContentCardsUpdatedEvent> mContentCardsUpdatedSubscriber;

Étape 2 : S’abonner aux événements

Ajoutez ensuite le code suivant pour vous abonner aux événements Content Card de Braze, généralement dans la méthode Activity.onCreate() de votre activité Content Cards personnalisée :




// - Available in version 44.0.0+
// Remove the previous subscriber before rebuilding a new one with our new activity.
Braze.getInstance(context).removeSingleSubscription(mContentCardsEventSubscriber, ContentCardsEvent.class);
mContentCardsEventSubscriber = new IEventSubscriber<ContentCardsEvent>() {
    @Override
    public void trigger(ContentCardsEvent event) {
        if (event instanceof ContentCardsEvent.CacheReplay) {
            handleCards(((ContentCardsEvent.CacheReplay) event).getCacheSnapshot());
        } else if (event instanceof ContentCardsEvent.CacheLoad) {
            handleCards(((ContentCardsEvent.CacheLoad) event).getCacheSnapshot());
        } else if (event instanceof ContentCardsEvent.DataUpdated) {
            handleCards(((ContentCardsEvent.DataUpdated) event).getCacheSnapshot());
        }
    }
};
Braze.getInstance(context).subscribeToContentCardsEvents(mContentCardsEventSubscriber);
Braze.getInstance(context).requestContentCardsRefresh();

// 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<Card> allCards = event.getAllCards();
    }
};
Braze.getInstance(context).subscribeToContentCardsUpdates(mContentCardsUpdatedSubscriber);
Braze.getInstance(context).requestContentCardsRefresh();

private void handleCards(ContentCardsCacheSnapshot cacheSnapshot) {
    List<Card> allCards = cacheSnapshot.getCards();
}

Étape 3 : Se désabonner

Nous vous recommandons également de vous désabonner lorsque votre activité personnalisée n’est plus visible. Ajoutez le code suivant à la méthode de cycle de vie onDestroy() de votre activité :




// - Available in version 44.0.0+
Braze.getInstance(context).removeSingleSubscription(mContentCardsEventSubscriber, ContentCardsEvent.class);

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

Étape 1 : Créer une variable d’abonnement privée

Pour vous abonner aux événements de carte, déclarez d’abord une variable privée dans votre classe personnalisée pour stocker votre abonné :




// - Available in version 44.0.0+
private var contentCardsEventSubscriber: IEventSubscriber<ContentCardsEvent>? = null

private var contentCardsUpdatedSubscriber: IEventSubscriber<ContentCardsUpdatedEvent>? = null

Étape 2 : S’abonner aux événements

Ajoutez ensuite le code suivant pour vous abonner aux événements Content Card de Braze, généralement dans la méthode Activity.onCreate() de votre activité Content Cards personnalisée :




// - Available in version 44.0.0+
// Remove the previous subscriber before rebuilding a new one with our new activity.
Braze.getInstance(context).removeSingleSubscription(contentCardsEventSubscriber, ContentCardsEvent::class.java)
contentCardsEventSubscriber = IEventSubscriber { event ->
    when (event) {
        is ContentCardsEvent.CacheReplay -> handleCards(event.cacheSnapshot)
        is ContentCardsEvent.CacheLoad -> handleCards(event.cacheSnapshot)
        is ContentCardsEvent.DataUpdated -> handleCards(event.cacheSnapshot)
        else -> {}
    }
}
Braze.getInstance(context).subscribeToContentCardsEvents(contentCardsEventSubscriber)
Braze.getInstance(context).requestContentCardsRefresh()

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

private fun handleCards(cacheSnapshot: ContentCardsCacheSnapshot) {
    val allCards = cacheSnapshot.cards
}

Étape 3 : Se désabonner

Nous vous recommandons également de vous désabonner lorsque votre activité personnalisée n’est plus visible. Ajoutez le code suivant à la méthode de cycle de vie onDestroy() de votre activité :




// - Available in version 44.0.0+
Braze.getInstance(context).removeSingleSubscription(contentCardsEventSubscriber, ContentCardsEvent::class.java)

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

Pour savoir quand chaque événement se déclenche et ce que signifient chaque raison de mise à jour, état de nouvelle tentative, action d’analyse et raison d’erreur, consultez Abonnements aux événements.

Utilisez subscribeToContentCardsEvents à partir de la version 44.0.0 du SDK Android. subscribeToContentCardsUpdates est l’ancien modèle, déprécié à partir de la version 44.0.0.

Pour accéder au modèle de données des Content Cards, appelez contentCards.cards sur votre instance braze.




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

De plus, vous pouvez vous abonner aux événements Content Cards pour observer les changements de cache, les analyses et les erreurs. Vous pouvez le faire de deux manières :

  1. En conservant un annulable ; ou
  2. En conservant un AsyncStream.

Annulable




// - Available in version 19.0.0+
// This subscription is maintained through a Braze cancellable, which will observe for events 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.subscribeToEvents { [weak self] event in
  switch event {
  case .cacheReplay(let cacheSnapshot):
    // Initial cache snapshot, delivered immediately after subscribing
    break
  case .cacheLoad(let cacheSnapshot):
    // Cache loaded at the start of a user session (for example, after `changeUser()`)
    break
  case .dataUpdated(let cacheSnapshot, let reason):
    // Cache changed after the initial replay
    break
  case .impressionEvent(let card, let action):
    break
  case .clickEvent(let card, let action):
    break
  case .dismissEvent(let card, let action):
    break
  case .error(let reason, let retryState):
    break
  }
}

let cancellable = AppDelegate.braze?.contentCards.subscribeToUpdates { [weak self] contentCards in
  // Implement your completion handler to respond to updates in `contentCards`.
}

AsyncStream




// - Available in version 19.0.0+
Task {
  for await event in AppDelegate.braze?.contentCards.eventsStream ?? AsyncStream { _ in } {
    // Same switch statement as the cancellable example above.
  }
}

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

Utilisez subscribeToEvents(_:) ou eventsStream à partir de la version 19.0.0 du SDK Swift. subscribeToUpdates(_:) et cardsStream sont l’ancien modèle, déprécié à partir de la version 19.0.0.

Pour savoir quand chaque événement se déclenche et ce que signifient chaque raison de mise à jour, état de nouvelle tentative, action d’analyse et raison d’erreur, consultez Abonnements aux événements.

Accesseurs d’instantanés non bloquants

Utilisez ces méthodes pour lire l’état actuel du cache sans bloquer le thread appelant. Chaque gestionnaire de complétion est toujours distribué sur le thread principal.




// 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.
}






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

De plus, si vous souhaitez vous abonner aux événements Content Cards, vous pouvez appeler subscribeToEvents:. Chaque type d’événement est relié à sa propre classe (par exemple, BRZContentCardsDataUpdatedEvent), que vous pouvez distinguer avec isKindOfClass:. La relecture initiale du cache et les mises à jour de données ultérieures sont toutes deux reliées à BRZContentCardsDataUpdatedEvent ; vérifiez reason par rapport à BRZContentCardsDataUpdatedEvent.cacheReplayReason pour les différencier :




// - Available in version 19.0.0+
// This subscription is maintained through a Braze cancellable, which will continue to observe for events until the subscription is cancelled.
BRZCancellable *cancellable = [self.braze.contentCards subscribeToEvents:^(BRZContentCardsEvent *event) {
  if ([event isKindOfClass:[BRZContentCardsDataUpdatedEvent class]]) {
    BRZContentCardsDataUpdatedEvent *updated = (BRZContentCardsDataUpdatedEvent *)event;
    if (updated.reason == BRZContentCardsDataUpdatedEvent.cacheReplayReason) {
      // Initial cache snapshot, delivered immediately after subscribing
    } else {
      // Cache changed after the initial replay
    }
  } else if ([event isKindOfClass:[BRZContentCardsCacheLoadEvent class]]) {
    // Cache loaded at the start of a user session (for example, after `changeUser()`)
  }
}];

BRZCancellable *cancellable = [self.braze.contentCards subscribeToUpdates:^(NSArray<BRZContentCardRaw *> *contentCards) {
  // Implement your completion handler to respond to updates in `contentCards`.
}];

Utilisez subscribeToEvents: à partir de la version 19.0.0 du SDK Swift. subscribeToUpdates: est l’ancien modèle, déprécié à partir de la version 19.0.0.

Pour lire l’état actuel du cache sans bloquer le thread appelant, utilisez les méthodes suivantes. Chaque gestionnaire de complétion est distribué sur le thread principal.




// 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.
}];

Pour écouter les mises à jour, abonnez-vous aux événements de mise à jour des Content Cards :




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.
    }
  });
});

Pour obtenir les données Content Cards les plus récentes en cache :




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

const cachedCards = await Braze.getCachedContentCards();

Pour demander une actualisation manuelle des Content Cards depuis les serveurs Braze :




Braze.requestContentCardsRefresh();

Journalisation des événements

La journalisation d’indicateurs importants tels que les impressions, les clics et les fermetures est rapide et simple. Définissez un écouteur de clic personnalisé pour gérer manuellement ces analyses.

Journalisez les événements d’impression lorsque les cartes sont vues par les utilisateurs à l’aide de logContentCardImpressions :




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

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

Journalisez les événements de clic sur les cartes lorsque les utilisateurs interagissent avec une carte à l’aide de logContentCardClick :




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

braze.logContentCardClick(card);

Le BrazeManager peut référencer les dépendances du SDK Braze, telles que la liste de tableaux d’objets Content Cards, pour obtenir l’objet Card et appeler les méthodes de journalisation de Braze. Utilisez la classe de base ContentCardable pour référencer facilement les données et les fournir au BrazeManager.

Pour journaliser une impression ou un clic sur une carte, appelez Card.logClick() ou Card.logImpression() respectivement.

Vous pouvez journaliser manuellement ou marquer une Content Card comme « fermée » dans Braze pour une carte spécifique avec isDismissed. Si une carte est déjà marquée comme fermée, elle ne peut pas être marquée à nouveau comme fermée.

Pour créer un écouteur de clic personnalisé, créez une classe qui implémente IContentCardsActionListener et enregistrez-la avec BrazeContentCardsManager. Implémentez la méthode onContentCardClicked(), qui sera appelée lorsque l’utilisateur clique sur une Content Card. Ensuite, indiquez à Braze d’utiliser votre écouteur de clic pour les Content Cards.

Par exemple :




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) {

  }
});

Par exemple :




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

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

  }
}

Implémentez le protocole BrazeContentCardUIViewControllerDelegate et définissez votre objet délégué comme la propriété delegate de votre BrazeContentCardUI.ViewController. Ce délégué gérera la transmission des données de votre objet personnalisé vers Braze pour journalisation. Pour un exemple, consultez le tutoriel de l’interface utilisateur Content Cards.




// 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
}






// 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;
}

Journalisez les événements d’impression lorsque les cartes sont vues par les utilisateurs :




Braze.logContentCardImpression(card.id);

Journalisez les événements de clic sur les cartes lorsque les utilisateurs interagissent avec une carte :




Braze.logContentCardClicked(card.id);

Journalisez les événements de fermeture lorsqu’un utilisateur ferme une carte :




Braze.logContentCardDismissed(card.id);

Gestion du comportement au clic

Lorsqu’un utilisateur clique sur une Content Card dans un flux personnalisé, le comportement au clic (comme la navigation vers une URL, la création de liens profonds ou l’enregistrement d’un événement personnalisé) n’est pas géré automatiquement. Utilisez handleBrazeAction pour traiter l’URL de la carte et exécuter l’action au clic configurée, y compris les actions Braze (URLs brazeActions://).




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);
  }
}
Paramètre Description
url Une URL valide, ou une URL d’action Braze valide avec le schéma brazeActions://.
openLinkInNewTab (Facultatif) Indique si l’URL doit s’ouvrir dans un nouvel onglet. La valeur par défaut est false.

Le comportement au clic est géré automatiquement par l’interface utilisateur par défaut des Content Cards. Pour les implémentations personnalisées, utilisez l’interface IContentCardsActionListener décrite dans Journalisation des analyses.

Le comportement au clic est géré automatiquement par l’interface utilisateur par défaut des Content Cards. Pour les implémentations personnalisées, utilisez le protocole BrazeContentCardUIViewControllerDelegate décrit dans Journalisation des analyses.

Lorsqu’un utilisateur clique sur une Content Card dans un flux personnalisé, le comportement au clic n’est pas géré automatiquement. Après avoir enregistré le clic avec Braze.logContentCardClicked(cardId), appelez Braze.processContentCardClickAction(cardId) pour traiter les deep links, les URL et les actions brazeActions://. Pour la référence des méthodes, consultez Content Cards React Native.




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

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

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

Rejets uniques supérieurs aux impressions uniques

Si les rejets uniques dépassent les impressions uniques, votre intégration personnalisée de Content Cards a enregistré des rejets sans enregistrer les impressions pour ces mêmes cartes. L’interface par défaut des Content Cards de Braze enregistre les deux automatiquement, ce décalage n’apparaît donc que lorsque vous utilisez une interface personnalisée.

Enregistrez une impression chaque fois que vous affichez une carte, et enregistrez un rejet lorsque l’utilisateur la ferme. Pour les noms de méthodes et des exemples, consultez les sections par plateforme ci-dessous.

Analyses manquantes pour les Content Cards

Si les Content Cards s’affichent correctement dans votre application mais que vous ne recevez systématiquement aucune donnée analytique (impressions, clics, etc.), il s’agit probablement d’un problème d’intégration SDK.

  • Vues personnalisées de Content Cards (Android, iOS, Web) : L’interface par défaut de Braze enregistre automatiquement les impressions et les clics sur toutes les plateformes. Si vous utilisez une vue ou un déploiement personnalisé de Content Cards, vous devez appeler explicitement les méthodes d’enregistrement appropriées dans votre application. Consultez Enregistrer les analyses pour votre plateforme. Pour les déploiements Web personnalisés en particulier, vérifiez que le SDK Web de Braze est chargé, consultez la console du navigateur pour détecter d’éventuelles erreurs et assurez-vous que les données des cartes sont bien reçues.
  • Initialisation du SDK et identification de l’utilisateur : Assurez-vous que le SDK est entièrement initialisé avant d’afficher les cartes. Les événements sont silencieusement ignorés (et non mis en file d’attente) si le SDK n’est pas initialisé, s’il est en mode d’initialisation différée ou s’il est désactivé pour le RGPD. Le SDK enregistre bien les analyses pour les utilisateurs anonymes, mais les indicateurs du tableau de bord comme « impressions quotidiennes uniques » nécessitent une identité utilisateur résolue. Appelez donc changeUser avant l’affichage des cartes dans la mesure du possible.

ID de Content Card

Chaque envoi d’une Campaign à un destinataire génère un nouvel ID de Content Card. Si le même utilisateur reçoit la Campaign à nouveau lors d’un envoi ultérieur, Braze attribue un nouvel ID. Référencez l’id de la carte lorsque vous enregistrez les impressions, les clics et les rejets dans vos déploiements personnalisés.

Documentation pour la plateforme d'engagement client Braze.

Ressources
Mentions légales
Entreprise
© 2026 Braze, Inc. Tous droits réservés.
Vérification du statut Braze
New Stuff!