Cartes de contenu

Remarque

Ce guide utilise des exemples de code du SDK Web de Braze 4.0.0+. Pour passer à la dernière version du SDK Web, consultez le Guide de mise à niveau du SDK.

Conditions préalables

Avant de pouvoir utiliser les Content Cards, vous devez intégrer le SDK Web de Braze dans votre application. Cependant, aucune configuration supplémentaire n’est requise. Pour créer votre propre interface utilisateur, consultez le guide de personnalisation des Content Cards.

Remarque

Certains bloqueurs de publicités et extensions de confidentialité des navigateurs peuvent bloquer le script du SDK Web de Braze ou les requêtes réseau associées, ce qui peut empêcher le chargement des Content Cards. Si vous utilisez la méthode d’intégration par réseau de diffusion de contenu, envisagez de passer à la méthode d’intégration NPM, qui stocke les bibliothèques du SDK localement sur votre site web et peut éviter certains problèmes liés aux bloqueurs de publicités.

IU de flux standard

Pour utiliser l’IU de Content Cards incluse, vous devez spécifier où afficher le flux sur votre site web.

Dans cet exemple, nous avons un <div id="feed"></div> dans lequel nous voulons placer le flux de Content Cards. Nous utiliserons trois boutons pour masquer, afficher ou basculer le flux (masquer ou afficher en fonction de son état actuel).

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>

Lorsque vous utilisez les méthodes toggleContentCards(parentNode, filterFunction) et showContentCards(parentNode, filterFunction), si aucun argument n’est fourni, toutes les Content Cards seront affichées dans une barre latérale à position fixe sur le côté droit de la page. Sinon, le flux sera placé dans l’option parentNode spécifiée.

Consultez la documentation de référence du SDK pour plus d’informations sur le basculement des Content Cards.

Tester les Content Cards sur le web

Vous pouvez tester votre intégration de Content Cards à l’aide des outils de développement de votre navigateur.

1. Créez une campagne de Content Cards et ciblez votre utilisateur test.
2. Connectez-vous au site web qui intègre votre SDK Web.
3. Ouvrez la console de votre navigateur. Pour Chrome, faites un clic droit sur la page, sélectionnez Inspect, puis sélectionnez l’onglet Console.
4. Exécutez ces commandes dans la console :
   • window.braze.getCachedContentCards()
   • window.braze.toggleContentCards()

Types de cartes et propriétés

Le modèle de données des Content Cards est disponible dans le SDK Web et propose les types de Content Cards suivants : ImageOnly, CaptionedImage et ClassicCard. Chaque type hérite des propriétés communes d’un modèle de base Card et possède les propriétés supplémentaires suivantes.

Conseil

Pour enregistrer les données des Content Cards, consultez la section Enregistrement des analyses.

Modèle de carte de base

Toutes les Content Cards partagent ces propriétés :

Image uniquement

Les cartes ImageOnly sont des images cliquables en taille réelle.

Image avec légende

Les cartes CaptionedImage sont des images cliquables en taille réelle accompagnées d’un texte descriptif.

Classique

Le modèle ClassicCard peut contenir une image sans texte ou un texte avec image.

Groupe de contrôle

Si vous utilisez le flux par défaut des Content Cards, les impressions et les clics sont automatiquement suivis.

Si vous utilisez une intégration personnalisée pour les Content Cards, vous devez enregistrer les impressions lorsqu’une carte de contrôle aurait été vue. Dans ce cadre, veillez à gérer les cartes de contrôle lorsque vous enregistrez des impressions dans un test A/B. Ces cartes sont vierges et, bien qu’elles ne soient pas vues par les utilisateurs, vous devez tout de même enregistrer les impressions afin de comparer leurs performances à celles des cartes hors contrôle.

Pour déterminer si une Content Card se trouve dans le groupe de contrôle d’un test A/B, vérifiez la propriété card.isControl (SDK Web v4.5.0+) ou vérifiez si la carte est une instance de ControlCard (card instanceof braze.ControlCard).

Méthodes de carte

Méthodes de flux par défaut

Utilisez ces méthodes lorsque vous affichez les Content Cards avec l’IU par défaut de Braze :

Méthodes de flux personnalisé

Utilisez ces méthodes lorsque vous créez votre propre IU de Content Cards :

Pour plus de détails, reportez-vous à la documentation de référence du SDK.

Bonnes pratiques

Appeler les méthodes dans le bon ordre

Pour les flux personnalisés, les Content Cards ne sont rafraîchies au démarrage de la session que si subscribeToContentCardsUpdates() est appelée avant openSession(). Appelez vos méthodes Braze dans cet ordre :

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

Utiliser les cartes en cache pour conserver le contenu entre les chargements de page

Étant donné que subscribeToContentCardsUpdates() n’invoque son rappel que lorsqu’il y a de nouvelles mises à jour (par exemple au démarrage de la session), les cartes peuvent disparaître de votre flux personnalisé si un utilisateur actualise la page en cours de session. Pour éviter cela, utilisez getCachedContentCards() pour afficher immédiatement les cartes depuis le cache local, en complément de votre abonnement aux nouvelles mises à jour :

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

Enregistrer les analyses pour les flux personnalisés

Lorsque vous utilisez une IU personnalisée, les impressions, les clics et les rejets ne sont pas suivis automatiquement. Vous devez enregistrer chaque événement manuellement :

• Impressions : Appelez logContentCardImpressions([card1, card2, ...]) avec un tableau d’objets carte lorsque les cartes deviennent visibles pour l’utilisateur.
• Clics : Appelez logContentCardClick(card) lorsqu’un utilisateur interagit avec une carte.
• Comportement au clic : Appelez handleBrazeAction(card.url) pour exécuter l’action au clic configurée de la carte (comme naviguer vers une URL ou enregistrer un événement personnalisé).

Avertissement

L’argument passé à logContentCardClick() doit être un objet Card Braze original. Si vous transformez ou reconstruisez les données de la carte (par exemple, en sérialisant et désérialisant), les clics ne seront pas enregistrés et vous verrez l’erreur : « card must be a Card object. »

Utilisation de Google Tag Manager

Google Tag Manager fonctionne en injectant le CDN de Braze (une version de notre SDK Web) directement dans le code de votre site web, ce qui signifie que toutes les méthodes du SDK sont disponibles comme si vous aviez intégré le SDK sans Google Tag Manager, sauf lors de l’implémentation des Content Cards.

Mise en place des Content Cards

• google tag manager
• manuel

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

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

Mise à jour des modèles

Pour obtenir la dernière version du SDK Web de Braze, effectuez les trois étapes suivantes dans votre tableau de bord Google Tag Manager :

1. Mise à jour du modèle de balise
   Accédez à la page Templates de votre espace de travail. Vous devriez y voir une icône indiquant qu’une mise à jour est disponible.
   
   
   
   Cliquez sur cette icône et, après avoir examiné la modification, cliquez sur Accept Update.
   
   
   
   
2. Mise à jour du numéro de version
   Une fois votre modèle de balise mis à jour, modifiez la balise d’initialisation Braze et mettez à jour la version du SDK avec la version major.minor la plus récente. Par exemple, si la dernière version est 4.1.2, saisissez 4.1. Vous pouvez consulter la liste des versions du SDK dans notre journal des modifications.
   
   
   
   
3. AQ et publication
   Vérifiez que la nouvelle version du SDK fonctionne à l’aide de l’outil de débogage de Google Tag Manager avant de publier une mise à jour de votre conteneur de balises.

Résolution des problèmes

Activer le débogage de balise

Chaque modèle de balise Braze dispose d’une case à cocher facultative GTM Tag Debugging qui peut être utilisée pour enregistrer les messages de débogage dans la console JavaScript de votre page web.

Passer en mode débogage

Un autre moyen de déboguer votre intégration Google Tag Manager est d’utiliser la fonctionnalité de prévisualisation de Google.

Cela permet d’identifier les valeurs envoyées par la couche de données de votre page web à chaque balise Braze déclenchée et d’expliquer quelles balises ont été déclenchées ou non.

Vérifier le séquencement des balises pour les événements personnalisés

Si les événements personnalisés ou d’autres actions ne sont pas enregistrés dans Braze, une cause fréquente est une condition de concurrence où une balise d’action (comme Custom Event ou Purchase) se déclenche avant que la balise Braze Initialization ne soit terminée. Pour corriger cela, configurez le séquencement des balises dans GTM :

1. Ouvrez la balise d’action qui ne s’enregistre pas correctement.
2. Sous Advanced Settings > Tag Sequencing, sélectionnez A tag that fires before [this tag].
3. Choisissez votre balise Braze Initialization comme balise de configuration.

Cela garantit que le SDK est entièrement initialisé avant que les balises d’action ne tentent d’envoyer des données à Braze.

Activer la journalisation détaillée

Pour capturer des journaux détaillés à des fins de résolution des problèmes, vous pouvez activer la journalisation détaillée sur votre intégration Google Tag Manager. Ces journaux apparaîtront dans l’onglet Console des outils de développement de votre navigateur.

Dans votre intégration Google Tag Manager, accédez à votre balise d’initialisation Braze et sélectionnez Enable Web SDK Logging.