À propos du SDK Web Braze

Le SDK Web Braze vous permet de collecter des données analytiques et d’afficher des messages in-app enrichis, des notifications push et des messages Content Cards à vos utilisateurs Web. Pour plus d’informations, consultez la documentation de référence JavaScript de Braze.

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.

Intégrer le SDK Web

Vous pouvez intégrer le SDK Web Braze en utilisant les méthodes suivantes. Pour des options supplémentaires, consultez les autres méthodes d’intégration.

• Intégration basée sur le code : Intégrez le SDK Web Braze directement dans votre base de code à l’aide de votre gestionnaire de paquets préféré ou du réseau de diffusion de contenu Braze. Cela vous permet de contrôler entièrement le chargement et la configuration du SDK.
• Google Tag Manager : Une solution sans code qui vous permet d’intégrer le SDK Web Braze sans modifier le code de votre site. Pour plus d’informations, consultez Google Tag Manager avec le SDK Braze.

Important

Nous recommandons d’utiliser la méthode d’intégration NPM. Les avantages comprennent le stockage local des bibliothèques SDK sur votre site web, l’immunité contre les extensions de blocage des publicités et la contribution à des temps de chargement plus rapides dans le cadre de la prise en charge des bundlers.

• code-based integration
• google tag manager

Étape 1 : Installer la bibliothèque Braze

Vous pouvez installer la bibliothèque Braze en utilisant l’une des méthodes suivantes. Toutefois, si votre site web utilise un Content-Security-Policy, consultez la politique de sécurité du contenu avant de poursuivre.

Important

Bien que la plupart des bloqueurs de publicités ne bloquent pas le SDK Web Braze, certains bloqueurs plus restrictifs sont connus pour causer des problèmes.

• package manager
• braze cdn

Si votre site utilise les gestionnaires de paquets NPM ou Yarn, vous pouvez ajouter le paquet NPM de Braze comme dépendance.

Les définitions TypeScript sont désormais incluses à partir de la version v3.0.0. Pour les notes sur la mise à jour de 2.x vers 3.x, consultez notre journal des modifications.

1
2
3
npm install --save @braze/web-sdk
# or, using yarn:
# yarn add @braze/web-sdk

Une fois installé, vous pouvez import ou require la bibliothèque de la manière habituelle :

1
2
3
import * as braze from "@braze/web-sdk";
// or, using `require`
const braze = require("@braze/web-sdk");

Ajoutez le SDK Web Braze directement à votre code HTML en faisant référence à notre script hébergé par le réseau de diffusion de contenu, qui charge la bibliothèque de manière asynchrone.

Important

Le paramètre par défaut Empêcher le suivi intersites dans Safari peut empêcher l’affichage de certains types de messages in-app, tels que les bannières et les Content Cards, lorsque vous utilisez la méthode d’intégration par réseau de diffusion de contenu. Pour éviter ce problème, utilisez la méthode d’intégration NPM afin que Safari ne classe pas ces messages comme du trafic intersite et que vos utilisateurs web puissent les voir dans tous les navigateurs pris en charge.

Étape 2 : Initialiser le SDK

Une fois le SDK Web Braze ajouté à votre site web, initialisez la bibliothèque à l’aide de la clé API et de l’URL de l’endpoint SDK disponibles dans Paramètres > Paramètres des applications dans votre tableau de bord de Braze. Pour obtenir la liste complète des options de braze.initialize(), ainsi que nos autres méthodes JavaScript, consultez la documentation JavaScript de Braze.

Remarque

Les domaines personnalisés pour les requêtes du SDK Web ne sont pas pris en charge : Le baseUrl du SDK Web doit être un endpoint du SDK Braze (par exemple, sdk.iad-05.braze.com). Braze ne prend pas en charge le routage du trafic du SDK Web via un domaine appartenant au client à l’aide d’enregistrements CNAME. Si vous avez besoin que les requêtes du SDK Web proviennent de votre propre domaine, contactez l’assistance Braze.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// initialize the SDK
braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE",
    enableLogging: false, // set to `true` for debugging
    allowUserSuppliedJavascript: false, // set to `true` to support custom HTML messages
});

// Enable automatic display of in-app messages
// Required if you want in-app messages to display automatically when triggered
braze.automaticallyShowInAppMessages();

// if you use Content Cards
braze.subscribeToContentCardsUpdates(function(cards){
    // cards have been updated
});

// optionally set the current user's external ID before starting a new session
// you can also call `changeUser` later in the session after the user logs in
if (isLoggedIn){
    braze.changeUser(userIdentifier);
}

// `openSession` should be called last - after `changeUser` and `automaticallyShowInAppMessages`
braze.openSession();

Important

Affichage des messages in-app : Pour afficher automatiquement les messages in-app lorsqu’ils sont déclenchés, vous devez appeler braze.automaticallyShowInAppMessages(). Sans cet appel, les messages in-app ne s’affichent pas automatiquement. Si vous souhaitez gérer manuellement l’affichage des messages, supprimez cet appel et utilisez braze.subscribeToInAppMessage() à la place. Pour plus d’informations, consultez la section Réception/distribution de messages in-app.

Résolution des problèmes de sessions manquantes pour les utilisateurs anonymes

Si vous constatez un comportement de « session manquante » ou si vous n’êtes pas en mesure de suivre la session des utilisateurs anonymes sur le web, assurez-vous que votre intégration appelle braze.openSession() lors de l’initialisation.

• Scénario : Les utilisateurs anonymes peuvent renvoyer un ID Braze, mais les données de session sont vides ou manquantes.
• Cause : L’implémentation n’appelle pas braze.openSession().
• Résolution : Appelez toujours braze.openSession() après l’initialisation (et après braze.changeUser() si vous définissez un ID externe).

Pour plus d’informations, consultez l’étape 2 : Initialiser le SDK.

Important

Les utilisateurs anonymes sur des appareils mobiles ou web peuvent être comptabilisés dans votre MAU. Par conséquent, vous pouvez charger ou initialiser conditionnellement le SDK pour exclure ces utilisateurs de votre décompte de MAU.

Conditions préalables

Avant de pouvoir utiliser cette méthode d’intégration, vous devez créer un compte et un conteneur pour Google Tag Manager.

Étape 1 : Ouvrir la galerie de modèles de balises

Dans Google Tag Manager, sélectionnez votre espace de travail, puis choisissez Templates. Dans le volet Tag Template, sélectionnez Search Gallery.

Étape 2 : Ajouter le modèle de balise d’initialisation

Dans la galerie de modèles, recherchez braze-inc, puis sélectionnez Braze Initialization Tag.

Sélectionnez Add to workspace > Add.

Étape 3 : Configurer la balise

Dans la section Templates, sélectionnez le modèle que vous venez d’ajouter.

Sélectionnez l’icône en forme de crayon pour ouvrir le menu déroulant Tag Configuration.

Saisissez les informations minimales requises :

Champ	Description
API Key	Votre clé API Braze, disponible dans le tableau de bord de Braze sous Settings > App Settings.
API Endpoint	L’URL de votre endpoint REST. Votre endpoint dépend de l’URL de Braze pour votre instance.
SDK Version	La version MAJOR.MINOR la plus récente du SDK Web Braze indiquée dans le journal des modifications. Par exemple, si la dernière version est 4.1.2, saisissez 4.1. Pour en savoir plus, consultez À propos de la gestion des versions du SDK.

Pour accéder à des paramètres d’initialisation supplémentaires, sélectionnez Braze Initialization Options et choisissez les options dont vous avez besoin.

Étape 4 : Choisir les options d’initialisation

La balise d’initialisation Braze propose les options suivantes. La plupart correspondent directement aux InitializationOptions du SDK Web, et certaines correspondent à des méthodes du SDK Web que la balise appellera lors de l’initialisation. Sélectionnez les options qui correspondent à vos besoins d’intégration :

Option GTM	Configuration ou méthode du SDK Web	Description
Allow HTML In-App Messages	allowUserSuppliedJavascript	Active les messages in-app HTML, les bannières et les actions de clic JavaScript fournies par l’utilisateur. Nécessaire pour les messages in-app HTML et les bannières utilisant du HTML personnalisé. Activez cette option uniquement si vous faites confiance au contenu HTML et JavaScript, car elle autorise l’exécution de JavaScript fourni par l’utilisateur.
App Version Number	appVersion, appVersionNumber	Version de l’application pour la segmentation (par exemple, 1.2.3.4).
Automatically Open New Session	braze.openSession()	Ouvre une nouvelle session après l’initialisation du SDK en appelant cette méthode automatiquement.
Automatically show new in app messages	braze.automaticallyShowInAppMessages()	Affiche automatiquement les nouveaux messages in-app lorsqu’ils arrivent du serveur, en appelant cette méthode après l’initialisation.
Disable Automatic Push Token Maintenance	disablePushTokenMaintenance	Empêche le SDK de synchroniser les jetons de notification push avec le backend de Braze lors des nouvelles sessions.
Disable Automatic Service Worker Registration	manageServiceWorkerExternally	À utiliser si vous enregistrez et gérez vous-même le service de traitement.
Disable Cookies	noCookies	Utilise localStorage à la place des cookies pour les données utilisateur/session. Empêche la reconnaissance entre sous-domaines.
Disable Font Awesome	doNotLoadFontAwesome	Empêche le SDK de charger Font Awesome depuis le réseau de diffusion de contenu. À utiliser si votre site dispose déjà de Font Awesome.
Enable SDK Authentication	enableSdkAuthentication	Active l’authentification SDK.
Enable Web SDK Logging	enableLogging	Active la journalisation dans la console à des fins de débogage. À retirer avant la mise en production.
Minimum Interval Between Triggered Messages	minimumIntervalBetweenTriggerActionsInSeconds	Nombre minimum de secondes entre les actions de déclenchement (valeur par défaut : 30).
Open Cards in New Tab	openCardsInNewTab	Ouvre les liens des cartes de contenu dans un nouvel onglet lorsque l’interface par défaut du flux est utilisée.
Service Worker Location	serviceWorkerLocation	Chemin personnalisé pour le fichier du service de traitement (par défaut : /service-worker.js).
Session Timeout (seconds)	sessionTimeoutInSeconds	Délai d’expiration de la session en secondes (valeur par défaut : 1 800).

Remarque

Pour activer les messages in-app HTML personnalisés lorsque vous utilisez la balise d’initialisation Braze de Google Tag Manager, sélectionnez Allow HTML In-App Messages dans Braze Initialization Options. Cette case correspond à l’option d’initialisation allowUserSuppliedJavascript dans braze.initialize() et la définit sur true. La balise d’initialisation Braze de Google Tag Manager utilise ce libellé à la place du nom de l’option.

Pour les options non exposées dans le modèle GTM (telles que contentSecurityNonce, localization ou devicePropertyAllowlist), utilisez plutôt l’initialisation à l’exécution.

Étape 5 : Configurer le déclenchement sur toutes les pages

La balise d’initialisation doit être exécutée sur toutes les pages de votre site. Cela vous permet d’utiliser les méthodes du SDK Braze et d’enregistrer les analyses des notifications push Web.

Étape 6 : Vérifier votre intégration

Vous pouvez vérifier votre intégration en utilisant l’une des options suivantes :

• Option 1 : À l’aide de l’outil de débogage de Google Tag Manager, vérifiez que la balise d’initialisation Braze se déclenche correctement sur les pages ou événements configurés.
• Option 2 : Vérifiez les requêtes réseau envoyées à Braze depuis votre page Web. De plus, la bibliothèque globale window.braze devrait maintenant être définie.

Filtrage du trafic des robots

Le nombre de MAU peut inclure un pourcentage d’utilisateurs robots, ce qui gonfle votre nombre d’utilisateurs actifs par mois. Bien que le SDK Web Braze intègre une détection de certains robots d’indexation courants (tels que les robots des moteurs de recherche et les robots de prévisualisation des réseaux sociaux), il est particulièrement important de rester proactif en mettant en place des solutions robustes pour détecter les robots, car les mises à jour du SDK ne permettent pas à elles seules de détecter systématiquement tous les nouveaux robots.

Limites de la détection des robots côté SDK

Le SDK Web comprend une détection de base des robots fondée sur l’agent utilisateur, qui filtre les robots d’indexation connus. Cependant, cette approche présente certaines limites :

• De nouveaux robots apparaissent constamment : Les entreprises spécialisées dans l’intelligence artificielle et d’autres acteurs développent régulièrement de nouveaux robots qui peuvent se dissimuler afin d’échapper à la détection.
• Usurpation de l’agent utilisateur : Les robots sophistiqués peuvent imiter les agents utilisateurs légitimes des navigateurs.
• Robots personnalisés : Les utilisateurs non techniciens peuvent désormais créer facilement des robots à l’aide de grands modèles de langage (LLM), rendant le comportement des robots imprévisible.

Mise en œuvre du filtrage des robots

Important

Les solutions présentées ci-dessous sont des suggestions générales. Adaptez la logique de filtrage des robots à votre environnement unique et à vos modèles de trafic spécifiques.

La solution la plus robuste consiste à mettre en œuvre votre propre logique de filtrage des robots avant d’initialiser le SDK Braze. Les approches courantes comprennent :

Exiger une interaction de l’utilisateur

Envisagez de retarder l’initialisation du SDK jusqu’à ce qu’un utilisateur effectue une interaction significative, telle que l’acceptation d’une bannière de consentement aux cookies, le défilement ou un clic. Cette approche est souvent plus facile à mettre en œuvre et peut s’avérer très efficace pour filtrer le trafic des robots.

Important

Retarder l’initialisation du SDK jusqu’à l’interaction de l’utilisateur peut également entraîner le non-affichage des bannières et des Content Cards jusqu’à ce que cette interaction ait lieu.

Détection personnalisée des robots

Mettez en place une détection personnalisée en fonction des modèles de trafic spécifiques de vos robots, par exemple :

• Analyse des chaînes de caractères des agents utilisateurs pour identifier les modèles que vous avez détectés dans votre trafic
• Vérification des indicateurs de navigateur sans interface graphique
• Utilisation de services tiers de détection des robots
• Surveillance des signaux comportementaux spécifiques à votre site

Exemple d’initialisation conditionnelle :

1
2
3
4
5
6
7
8
// Only initialize Braze if your custom bot detection determines this is not a bot
if (!isLikelyBot()) {
  braze.initialize('YOUR-API-KEY-HERE', {
    baseUrl: "YOUR-SDK-ENDPOINT-HERE"
  });
  braze.automaticallyShowInAppMessages();
  braze.openSession();
}

Bonnes pratiques

• Analysez régulièrement vos données MAU et les tendances de trafic web afin d’identifier tout nouveau comportement de robot.
• Effectuez des tests approfondis pour vous assurer que votre filtrage des robots n’empêche pas le suivi des utilisateurs légitimes.
• Mettez à jour votre logique de filtrage en fonction des modèles de trafic des robots que vous observez dans votre environnement.

Configurations optionnelles

Journalisation

Pour activer rapidement la journalisation, vous pouvez ajouter ?brazeLogging=true comme paramètre à l’URL de votre site web. Vous pouvez également activer la journalisation de base ou personnalisée. Pour un aperçu centralisé sur toutes les plateformes, consultez la section Journalisation détaillée.

Journalisation de base

• before initialization
• after initialization

1
enableLogging: true

1
2
3
4
5
braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
    enableLogging: true
});
braze.openSession();

1
2
3
4
5
6
braze.initialize('API-KEY', {
    baseUrl: 'API-ENDPOINT',
});
braze.openSession();
...
braze.toggleLogging();

Important

Les journaux de base sont visibles par tous les utilisateurs. Envisagez de les désactiver ou de passer à setLogger avant de mettre votre code en production.

Journalisation personnalisée

Utilisez setLogger pour enregistrer des messages de débogage personnalisés dans la console JavaScript. Contrairement aux journaux de base, ces journaux ne sont pas visibles par les utilisateurs.

1
setLogger(loggerFunction: (message: STRING) => void): void

Remplacez STRING par votre message sous la forme d’un paramètre de chaîne de caractères unique. Votre méthode doit être similaire à la suivante :

1
2
3
4
5
braze.initialize('API-KEY');
braze.setLogger(function(message) {
    console.log("Braze Custom Logger: " + message);
});
braze.openSession();

Mise à niveau du SDK

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.

Lorsque vous faites référence au SDK Web Braze à partir de notre réseau de diffusion de contenu, par exemple https://js.appboycdn.com/web-sdk/a.a/braze.min.js (comme recommandé par nos instructions d’intégration par défaut), vos utilisateurs reçoivent automatiquement les mises à jour mineures (corrections de bogues et fonctionnalités rétrocompatibles, versions a.a.a à a.a.z dans les exemples ci-dessus) lorsqu’ils actualisent votre site.

Cependant, lorsque nous publions des modifications majeures, nous vous demandons de mettre à jour manuellement le SDK Web Braze afin de garantir que les changements majeurs n’affectent pas votre intégration. De plus, si vous téléchargez notre SDK et l’hébergez vous-même, vous ne recevrez aucune mise à jour automatique et devrez effectuer la mise à niveau manuellement pour bénéficier des dernières fonctionnalités et corrections de bogues.

Vous pouvez vous tenir au courant de notre dernière version en suivant notre flux de publication avec le lecteur RSS ou le service de votre choix, et consulter notre journal des modifications pour un compte-rendu complet de l’historique des versions de notre SDK Web. Pour mettre à niveau le SDK Web Braze :

• Mettez à jour la version de la bibliothèque Braze en modifiant le numéro de version de https://js.appboycdn.com/web-sdk/[OLD VERSION NUMBER]/braze.min.js ou dans les dépendances de votre gestionnaire de paquets.
• Si vous avez intégré les notifications push web, mettez à jour le fichier du service de traitement sur votre site. Par défaut, celui-ci se trouve à /service-worker.js dans le répertoire racine de votre site, mais l’emplacement peut être personnalisé dans certaines intégrations. Vous devez accéder au répertoire racine pour héberger un fichier de service de traitement.

Vous devez mettre à jour ces deux fichiers de manière coordonnée afin d’assurer un fonctionnement correct.

Autres méthodes d’intégration

Pages mobiles accélérées (AMP)

1
<script async custom-element="amp-web-push" src="https://cdn.ampproject.org/v0/amp-web-push-0.1.js"></script>

1
2
3
4
5
6
7
8
9
<!-- A subscription widget -->
<amp-web-push-widget visibility="unsubscribed" layout="fixed" width="250" height="80">
  <button on="tap:amp-web-push.subscribe">Subscribe to Notifications</button>
</amp-web-push-widget>

<!-- An unsubscription widget -->
<amp-web-push-widget visibility="subscribed" layout="fixed" width="250" height="80">
  <button on="tap:amp-web-push.unsubscribe">Unsubscribe from Notifications</button>
</amp-web-push-widget>

1
2
3
4
5
6
7
<amp-web-push
layout="nodisplay"
id="amp-web-push"
helper-iframe-url="FILE_PATH_TO_YOUR_HELPER_IFRAME"
permission-dialog-url="FILE_PATH_TO_YOUR_PERMISSION_DIALOG"
service-worker-url="FILE_PATH_TO_YOUR_SERVICE_WORKER?apiKey={YOUR_API_KEY}&baseUrl={YOUR_BASE_URL}"
>

Définition de module asynchrone (AMD)

Désactiver la prise en charge

Si votre site utilise RequireJS ou un autre chargeur de modules AMD, mais que vous préférez charger le SDK Web Braze via l’une des autres options de cette liste, vous pouvez charger une version de la bibliothèque qui n’inclut pas la prise en charge AMD. Cette version de la bibliothèque peut être chargée depuis l’emplacement suivant du réseau de diffusion de contenu :

Chargeur de modules

Si vous utilisez RequireJS ou d’autres chargeurs de modules AMD, nous vous recommandons d’auto-héberger une copie de notre bibliothèque et de la référencer comme vous le feriez avec d’autres ressources :

1
2
3
4
5
6
require(['path/to/braze.min.js'], function(braze) {
  braze.initialize('YOUR-API-KEY-HERE', { baseUrl: 'YOUR-SDK-ENDPOINT' });
  // Required if you want in-app messages to display automatically
  braze.automaticallyShowInAppMessages();
  braze.openSession();
});

Electron

Electron ne prend pas officiellement en charge les notifications push web (voir ce problème GitHub). Il existe d’autres solutions de contournement open source que vous pouvez essayer, mais qui n’ont pas été testées par Braze.

Framework Jest

Lorsque vous utilisez Jest, vous pouvez rencontrer une erreur similaire à SyntaxError: Unexpected token 'export'. Pour la corriger, ajustez votre configuration dans package.json pour ignorer le SDK Braze :

1
2
3
4
5
"jest": {
  "transformIgnorePatterns": [
    "/node_modules/(?!@braze)"
  ]
}

Frameworks SSR

Le SDK Web s’exécute dans un environnement de navigateur. Dans les frameworks SSR, initialisez Braze dans un composant côté client uniquement afin que votre serveur n’exécute jamais le code du SDK.

Import dynamique indépendant du framework

Si votre framework n’est pas répertorié dans cette section, vous pouvez importer dynamiquement Braze depuis un hook de cycle de vie côté client uniquement.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// MyComponent/braze-exports.js
// Export the parts of the SDK that you need.
export { initialize, openSession } from "@braze/web-sdk";

// MyComponent/MyComponent.js
useEffect(() => {
    import("./braze-exports.js").then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

Si vous utilisez webpack, vous pouvez importer dynamiquement uniquement les exports spécifiques du SDK.

1
2
3
4
5
6
7
8
9
10
11
12
13
// MyComponent.js
useEffect(() => {
    import(
        /* webpackExports: ["initialize", "openSession"] */
        "@braze/web-sdk"
    ).then(({ initialize, openSession }) => {
        initialize("YOUR-API-KEY-HERE", {
            baseUrl: "YOUR-SDK-ENDPOINT",
            enableLogging: true,
        });
        openSession();
    });
}, []);

Hook partagé pour Next.js et Remix

Créez un hook réutilisable useBraze et appelez-le à la racine de votre application.

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
// hooks/useBraze.ts
import { useEffect, useRef } from "react";

export function useBraze() {
  const didInit = useRef(false);

  useEffect(() => {
    if (didInit.current) {
      return;
    }
    didInit.current = true;

    import("@braze/web-sdk")
      .then((braze) => {
        const initialized = braze.initialize("YOUR-API-KEY-HERE", {
          // Use your Braze Web SDK endpoint, such as sdk.iad-01.braze.com.
          baseUrl: "YOUR-SDK-ENDPOINT",
          enableLogging: false,
        });
        if (!initialized) {
          return;
        }

        // Optional: Identify signed-in users before opening a session.
        // braze.changeUser("external-id");

        // Optional: Automatically display in-app messages.
        // braze.automaticallyShowInAppMessages();
        braze.openSession();
      })
      .catch((error) => {
        console.error("Unable to load Braze SDK:", error);
      });
  }, []);
}

Next.js (App Router)

Appelez useBraze dans un composant client qui encapsule votre application.

1
2
3
4
5
6
7
8
9
10
// app/components/AppRoot.tsx
"use client";

import type { ReactNode } from "react";
import { useBraze } from "../hooks/useBraze";

export function AppRoot({ children }: { children: ReactNode }) {
  useBraze();
  return <>{children}</>;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// app/layout.tsx
import type { ReactNode } from "react";
import { AppRoot } from "./components/AppRoot";

export default function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <AppRoot>{children}</AppRoot>
      </body>
    </html>
  );
}

Next.js (Pages Router)

Appelez useBraze en haut de votre composant d’application personnalisé.

1
2
3
4
5
6
7
8
9
10
11
// pages/_app.tsx
import type { AppProps } from "next/app";
import { useBraze } from "../hooks/useBraze";

export default function App({ Component, pageProps }: AppProps) {
  useBraze();

  return (
    <Component {...pageProps} />
  );
}

Remix

Appelez useBraze en haut de votre composant de route racine.

Pour les exemples de validation Remix en local, exécutez PORT=4013 npm run dev.

1
2
3
4
5
6
7
8
9
// app/root.tsx
import { Outlet } from "@remix-run/react";
import { useBraze } from "./hooks/useBraze";

export default function App() {
  useBraze();

  return <Outlet />;
}

Journalisation des événements et mise à jour des utilisateurs

Une fois que useBraze a initialisé le SDK à la racine de votre application, d’autres composants côté client peuvent appeler les méthodes Braze. Un modèle courant consiste à les appeler dans des actions utilisateur, telles que onClick ou onSubmit. Dans l’exemple, les méthodes du SDK sont chargées dans le gestionnaire de clic plutôt qu’en haut du fichier. Cela permet de garder le SDK Web hors du code serveur et de ne charger que ce dont l’action a besoin. Le commentaire webpackExports indique à webpack quelles méthodes inclure, ce qui réduit la taille de votre bundle.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// app/components/BuyButton.tsx
"use client";

export function BuyButton() {
  const handleClick = async () => {
    const { logCustomEvent, logPurchase, getUser } = await import(
      /* webpackExports: ["logCustomEvent", "logPurchase", "getUser"] */
      "@braze/web-sdk"
    );

    getUser()?.setCustomUserAttribute("last_purchase_date", "2026-05-04");
    logCustomEvent("clicked_buy", { source: "product_page" });
    logPurchase("sku_123", 19.99, "USD");
  };

  return <button onClick={handleClick}>Buy</button>;
}

Cet exemple montre un composant BuyButton qui enregistre l’activité lorsqu’un utilisateur clique sur Acheter. Il commence par importer uniquement logCustomEvent, logPurchase et getUser au moment du clic. Ensuite, il met à jour un attribut utilisateur, enregistre un événement personnalisé et enregistre un achat. Ce modèle vous permet de centraliser l’initialisation dans useBraze, tout en suivant les actions significatives depuis n’importe quel composant côté client.

Si vous utilisez Remix avec Vite et que les imports depuis la racine du paquet échouent à l’exécution, utilisez la solution de contournement Vite existante. Pour plus d’informations, consultez Vite.

Pour une liste complète des méthodes disponibles, consultez la documentation de référence JavaScript de Braze.

Tealium iQ

Tealium iQ propose une intégration de base clé en main de Braze. Pour configurer l’intégration, recherchez Braze dans l’interface Tealium Tag Management et fournissez la clé API du SDK Web à partir de votre tableau de bord.

Pour plus de détails ou pour obtenir une assistance approfondie concernant la configuration de Tealium, consultez notre documentation sur l’intégration ou contactez votre gestionnaire de compte Tealium.

Vite

Si vous utilisez Vite et voyez un avertissement concernant des dépendances circulaires ou Uncaught TypeError: Class extends value undefined is not a constructor or null, vous devrez peut-être exclure le SDK Braze de sa découverte de dépendances :

1
2
3
optimizeDeps: {
    exclude: ['@braze/web-sdk']
},

Autres gestionnaires de balises

Braze peut également être compatible avec d’autres solutions de gestion des balises en suivant nos instructions d’intégration au sein d’une balise HTML personnalisée. Contactez un conseiller Braze si vous avez besoin d’aide pour évaluer ces solutions.