À 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 de carte de contenu à vos utilisateurs Web. Pour plus d’informations, veuillez consulter la documentation de référence JavaScript de Braze.

Intégrer le SDK Web

Vous pouvez intégrer le SDK Web Braze en utilisant les méthodes suivantes. Pour des options supplémentaires, veuillez consulter 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, veuillez consulter Google Tag Manager avec le SDK Braze.

• code-based integration
• google tag manager

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

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

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

Filtrage du trafic des robots

Le nombre d’utilisateurs actifs par mois 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 fonctionnalité de 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 bots côté SDK

Le SDK Web comprend une fonctionnalité de détection des robots basé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 d’identité de l’agent utilisateur : Les robots sophistiqués peuvent imiter les agents utilisateurs légitimes des navigateurs.
• Bots personnalisés : Les utilisateurs non techniciens peuvent désormais créer facilement des bots à l’aide de grands modèles linguistiques (LLM), rendant le comportement des bots imprévisible.

Mise en œuvre du filtrage des bots

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

Nécessite 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.

Détection personnalisée des bots

Mettez en place une détection personnalisée en fonction des modèles de trafic spécifiques de vos bots, tels que :

• 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 bots
• 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

• Veuillez analyser régulièrement vos données MAU et les tendances de trafic Web afin d’identifier tout nouveau comportement de bot.
• Veuillez effectuer des tests approfondis pour vous assurer que votre filtrage des bots n’empêche pas le suivi des utilisateurs légitimes.
• Veuillez mettre à 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 obtenir un aperçu centralisé sur toutes les plateformes, veuillez consulter 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();

Journalisation personnalisée

Veuillez utiliser cette fonctionsetLogger 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’une 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

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.jscomme recommandé par nos instructions d’intégration par défaut), vos utilisateurs reçoivent automatiquement des mises à jour mineures (corrections de bogues et fonctionnalités rétrocompatibles, versionsa.a.adansa.a.zles exemples ci-dessus) lorsqu’ils actualisent votre site.

Cependant, lorsque nous publions des modifications importantes, nous vous demandons de mettre à jour manuellement le SDK Web Braze afin de garantir que les modifications majeures 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 Braze pour le Web :

• 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 responsable de packages.
• Si vous avez intégré des notifications push pour le Web, mettez à jour le fichier du service de traitement sur votre site. Par défaut, ce paramètre est situé à /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.

Il est nécessaire de mettre à jour ces deux fichiers de manière coordonnée afin d’assurer un fonctionnement optimal.

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)

Veuillez désactiver le support.

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. Il est possible de charger cette version de la bibliothèque depuis l’endroit suivant du CDN :

Chargeur de modules

Si vous utilisez RequireJS ou d’autres chargeurs de module 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();
});

Électron

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.

Cadre Jest

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

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

Cadres SSR

Si vous utilisez un framework de rendu côté serveur (SSR) tel que Next.js, vous pourriez rencontrer des erreurs car le SDK est conçu pour fonctionner dans un environnement de navigateur. Vous pouvez résoudre ces problèmes en important le SDK de façon dynamique.

Vous pouvez conserver les bénéfices du nettoyage lorsque vous y procédez en exportant les parties du SDK dont vous avez besoin dans un fichier séparé et en important ensuite de façon dynamique ce fichier dans votre composant.

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

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

Alternativement, si vous utilisez un pack Web pour regrouper votre application, vous pouvez tirer parti de ses commentaires magiques pour importer de façon dynamique uniquement les parties du SDK dont vous avez besoin.

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();
    });
}, []);

Tealium iQ

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

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

Vite

Si vous utilisez Vite et voyez un avertissement autour des dépendances circulaires ou Uncaught TypeError: Class extends value undefined is not a constructor or null, vous pourriez devoir exclure le SDK de Braze de sa découverte de dépendance :

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. Veuillez contacter un conseiller Braze si vous avez besoin d’aide pour évaluer ces solutions.