À propos du SDK Web de Braze

Le SDK Web de 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 en savoir plus, 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 de Braze à l’aide des méthodes suivantes. Pour des options supplémentaires, consultez autres méthodes d’intégration.

• Intégration basée sur le code : Intégrez le SDK Web de Braze directement dans votre base de code à l’aide de votre gestionnaire de paquets préféré ou du CDN de Braze. Cela vous donne un contrôle total sur la manière dont le SDK est chargé et configuré.
• Google Tag gestionnaire : Une solution sans code qui vous permet d’intégrer le SDK Web de Braze sans modifier le code de votre site. Pour en savoir plus, consultez Google Tag gestionnaire avec le SDK de Braze.

Important

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

• intégration basée sur le code
• google tag gestionnaire

Étape 1 : Installer la bibliothèque Braze

Vous pouvez installer la bibliothèque Braze à l’aide de l’une des méthodes suivantes. Toutefois, si votre site web utilise une Content-Security-Policy, consultez la section Content Security Policy avant de continuer.

Important

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

• package gestionnaire
• 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 incluses depuis la version 3.0.0. Pour les notes de mise à niveau de la version 2.x vers la version 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ée, vous pouvez utiliser import ou require 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 de Braze directement à votre HTML en référençant notre script hébergé sur le CDN, qui charge la bibliothèque de manière asynchrone.

Important

Le paramètre par défaut Empêcher le suivi intersite 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 CDN. 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 de Braze ajouté à votre site web, initialisez la bibliothèque avec la clé API et l’URL de l’endpoint du SDK disponibles dans Paramètres > Paramètres de l’application dans votre tableau de bord de Braze. Pour une liste complète des options pour 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 de 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 par le biais d’enregistrements CNAME. Si vous avez besoin que les requêtes du SDK Web proviennent de votre propre domaine, contactez le support 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 l’affichage des messages manuellement, supprimez cet appel et utilisez braze.subscribeToInAppMessage() à la place. Pour en savoir plus, consultez Désactiver les déclencheurs automatiques.

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

Si vous constatez un comportement de type « session manquante » ou si vous n’êtes pas en mesure de suivre la session des utilisateurs qui restent 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 en savoir plus, consultez Étape 2 : Initialiser le SDK.

Important

Les utilisateurs anonymes sur appareils mobiles ou web peuvent être comptabilisés dans vos MAU. Par conséquent, vous pouvez souhaiter charger ou initialiser le SDK de manière conditionnelle afin d’exclure ces utilisateurs de votre comptage 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 gestionnaire.

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

Dans Google Tag gestionnaire, 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 CDN. À 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 Content Cards 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 gestionnaire, 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 gestionnaire 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.

Important

Séquencement des balises : la balise d’initialisation Braze doit se déclencher avant toute autre balise qui appelle des méthodes du SDK Braze (telles que braze.getUser() ou braze.logCustomEvent()). Si des événements personnalisés, des attributs utilisateur ou d’autres appels de méthodes Braze se déclenchent avant l’initialisation du SDK, vous risquez de rencontrer des erreurs telles que Uncaught TypeError: Cannot read properties of undefined (reading 'getUser'). Pour garantir un séquencement correct, configurez votre balise d’initialisation Braze comme balise de configuration ou utilisez la fonctionnalité de séquencement des balises de GTM pour vous assurer qu’elle se déclenche en premier. Pour en savoir plus, consultez Séquencement des balises pour les balises d’action Braze.

É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 gestionnaire, 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 basique ou personnalisée. Pour un aperçu centralisé sur toutes les plateformes, consultez Journalisation détaillée.

Journalisation basique

• avant l'initialisation
• après l'initialisation

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 basiques sont visibles par tous les utilisateurs. Pensez à les désactiver ou à passer à setLogger avant de déployer votre code en production.

Journalisation personnalisée

Utilisez setLogger pour journaliser des messages de débogage personnalisés dans la console JavaScript. Contrairement aux journaux basiques, 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 devrait ressembler à ce qui suit :

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

Mise à jour 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 référencez le SDK Web de Braze depuis 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 bugs et fonctionnalités rétrocompatibles, versions a.a.a à a.a.z dans cet exemple) lorsqu’ils actualisent votre site.

Cependant, lorsque nous publions des changements majeurs, nous vous demandons de mettre à jour manuellement le SDK Web de Braze afin de vous assurer que les changements non rétrocompatibles n’impactent pas votre intégration. De plus, si vous téléchargez notre SDK et l’hébergez vous-même, vous ne recevez aucune mise à jour de version automatiquement et devez effectuer la mise à jour manuellement pour bénéficier des dernières fonctionnalités et corrections de bugs.

Vous pouvez rester informé de nos dernières versions en suivant notre flux de versions avec le lecteur RSS ou le service de votre choix, et consulter notre journal des modifications pour un historique complet des versions de notre SDK Web. Pour mettre à jour le SDK Web de 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 à l’emplacement /service-worker.js dans le répertoire racine de votre site, mais cet 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 pour garantir 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}"
>

Asynchronous Module Definition (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 de 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 d’AMD. Cette version de la bibliothèque peut être chargée depuis l’emplacement CDN suivant :

Chargeur de modules

Si vous utilisez RequireJS ou d’autres chargeurs de modules AMD, nous vous recommandons d’héberger vous-même 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 ticket GitHub). Il existe d’autres solutions open source que vous pouvez essayer, mais qui n’ont pas été testées par Braze.

Framework Jest

Lorsque vous utilisez Jest, vous pouvez voir une erreur similaire à SyntaxError: Unexpected token 'export'. Pour résoudre ce problème, 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 à proximité de 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 du composant de votre 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 />;
}

Journaliser des événements et mettre à jour les utilisateurs

Après que useBraze a initialisé le SDK à la racine de votre application, d’autres composants client peuvent appeler les méthodes Braze. Un schéma courant consiste à les appeler dans des actions utilisateur, telles que onClick ou onSubmit. Dans cet 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 cette action a besoin. Le commentaire webpackExports indique à webpack quelles méthodes inclure, ce qui maintient un bundle plus léger.

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 journalise l’activité lorsqu’un utilisateur clique sur Buy. Premièrement, il importe uniquement logCustomEvent, logPurchase et getUser au moment du clic. Ensuite, il met à jour un attribut utilisateur, journalise un événement personnalisé et journalise un achat. Ce schéma vous permet de centraliser l’initialisation dans useBraze, tout en suivant les actions significatives depuis n’importe quel composant client.

Si vous utilisez Remix avec Vite et que les imports depuis la racine du paquet échouent au moment de 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 offre une intégration Braze clé en main. Pour configurer l’intégration, recherchez Braze dans l’interface de gestion des balises Tealium, puis fournissez la clé API du SDK Web depuis votre tableau de bord.

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

Vite

Si vous utilisez Vite et que vous 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 de 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.