Passer au contenu

Cette page a été traduite automatiquement et peut contenir des inexactitudes. Pour signaler une erreur de traduction, utilisez le module de commentaires en bas de la table des matières, à droite de la page.

Lier les utilisateurs Web SDK entre domaines via l’ID d’appareil

Transmettez l’ID d’appareil du SDK Web Braze dans l’URL de destination lorsque deux domaines ne peuvent pas partager de cookies, afin que les sessions anonymes sur les deux sites soient associées au même profil utilisateur Braze.

À propos de cet exemple

Kitchenerie, un détaillant fictif d’ustensiles de cuisine, héberge un site marketing (kitchenerie.com) et une boutique (kitchenerie.shop). Chaque domaine dispose de sa propre intégration du SDK Web de Braze. Les cookies du navigateur ne sont pas partagés entre domaines : Braze attribue donc des ID d’appareil distincts, et des profils anonymes distincts, lorsqu’un même utilisateur passe du site marketing à la boutique.

Ce scénario :

Lit l’ID d’appareil sur le domaine source avec getDeviceId après l’initialisation du SDK
L’ajoute aux liens sortants sous forme de paramètre de requête (par exemple, brazeDeviceId)
Sur le domaine de destination, lit ce paramètre et le transmet à braze.initialize via l’option deviceId

Ce transfert est surtout utile pour les utilisateurs anonymes. Une fois que l’utilisateur se connecte sur la boutique, changeUser avec un external_id devient l’identifiant durable sur tous les appareils. Consultez Définir les ID utilisateur.

Les deux domaines doivent utiliser la même clé API d’espace de travail Braze et le même endpoint SDK afin que les événements soient enregistrés sur un seul profil.

Considérations

L’ID de l’appareil est propre à chaque navigateur. Ce scénario ne relie pas l’activité entre différents navigateurs, appareils ou profils. Utilisez external_id via changeUser pour une identité authentifiée et multi-appareils.
Récupérez l’ID de l’appareil uniquement après l’initialisation du SDK Web sur le domaine source. Appeler getDeviceId avant initialize ne renvoie aucune valeur.
Le SDK Web lit deviceId une seule fois, lors de initialize. Il n’existe pas de méthode setDeviceId post-initialisation permettant de modifier l’ID de l’appareil actif. Lisez le paramètre d’URL sur le domaine de destination avant d’appeler initialize.
Les visites directes, les favoris ou les recommandations tierces vers la boutique sans brazeDeviceId doivent revenir à l’attribution par défaut de l’ID de l’appareil. C’est le comportement attendu lorsqu’aucun ID du domaine source n’est disponible.
Les paramètres de requête apparaissent dans l’historique du navigateur et dans les journaux du serveur.
Les paramètres de requête peuvent fuiter via les en-têtes referrer. L’ID de l’appareil ne constitue pas à lui seul une donnée d’identification, mais supprimez le paramètre après son utilisation si votre équipe chargée de la confidentialité l’exige (voir l’étape 2).
Testez de bout en bout. Vérifiez par une inspection du réseau que les événements du domaine 2 utilisent l’ID de l’appareil attendu.
Adaptez les noms d’hôte, les sélecteurs de liens et la gestion des erreurs à votre site. Testez dans votre environnement de développement avant la mise en production.

Configuration

Étape 1 : Ajouter l’ID de l’appareil aux liens interdomaines sur le domaine source

Sur kitchenerie.com (Domaine 1), initialisez le SDK Web comme d’habitude, puis ajoutez l’ID actuel de l’appareil aux liens qui pointent vers kitchenerie.shop (Domaine 2).

Choisissez un nom de paramètre de requête qui n’entre pas en conflit avec votre site (cet exemple utilise brazeDeviceId). Le même principe s’applique aux liens générés côté serveur, à la navigation côté client ou aux valeurs src des iframes que vous contrôlez.

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

braze.initialize("YOUR-API-KEY-HERE", {
  baseUrl: "YOUR-SDK-ENDPOINT-HERE",
});
braze.openSession();

const destinationHost = "kitchenerie.shop";

braze.getDeviceId(function (deviceId) {
  if (!deviceId) {
    return;
  }

  const links = document.querySelectorAll('a[href*="' + destinationHost + '"]');

  links.forEach(function (link) {
    try {
      const url = new URL(link.href);
      url.searchParams.set("brazeDeviceId", deviceId);
      link.href = url.toString();
    } catch (e) {
      // Skip malformed hrefs (for example, javascript:, mailto:, or unparsable relative paths).
    }
  });
});

Si votre version du SDK expose getDeviceId de manière synchrone (sans rappel), appelez-la plutôt après l’initialisation :

const deviceId = braze.getDeviceId();

Consultez le guide du dépôt du SDK Web : obtenir l’ID de l’appareil et les options d’initialisation : deviceId.

Étape 2 : Lire l’ID de l’appareil et initialiser le SDK Web sur le domaine de destination

Sur kitchenerie.shop (Domaine 2), lisez brazeDeviceId dans la chaîne de requête avant initialize, puis transmettez-le dans les options d’initialisation s’il est présent.

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

const urlParams = new URLSearchParams(window.location.search);
const passedDeviceId = urlParams.get("brazeDeviceId");

const initOptions = {
  baseUrl: "YOUR-SDK-ENDPOINT-HERE",
};

if (passedDeviceId) {
  initOptions.deviceId = passedDeviceId;
}

braze.initialize("YOUR-API-KEY-HERE", initOptions);
braze.openSession();

// Optional: remove the parameter from the visible URL after consumption.
if (passedDeviceId) {
  const cleanUrl = new URL(window.location.href);
  cleanUrl.searchParams.delete("brazeDeviceId");
  window.history.replaceState({}, document.title, cleanUrl.toString());
}

Lorsque l’utilisateur se connecte, appelez changeUser avec son external_id afin que son activité future soit associée au profil identifié.

Étape 3 : Vérifier la transmission

Ouvrez le Domaine 1 dans un navigateur où vous n’êtes pas connecté.
Suivez un lien interdomaine vers le Domaine 2.
Dans l’onglet réseau du navigateur, vérifiez que le Domaine 2 envoie des événements avec le même ID d’appareil que celui utilisé par le Domaine 1.
Recommencez en accédant directement au Domaine 2 (sans paramètre de requête) et vérifiez qu’un nouvel ID d’appareil est attribué.

New Stuff!