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’articles de cuisine, héberge un site marketing (kitchenerie.com) et une boutique (kitchenerie.shop). Chaque domaine possède sa propre intégration du SDK Web de Braze. Les cookies du navigateur ne traversent pas les domaines, de sorte que Braze attribue des ID d’appareil distincts — et des profils anonymes distincts — lorsqu’un même utilisateur passe du site marketing à la boutique.

Ce modèle :

Lit l’ID d’appareil sur le domaine source avec getDeviceId après l’initialisation du SDK
L’ajoute aux liens sortants en tant que 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

Le transfert est surtout important 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 d’appareil est propre à chaque navigateur. Ce modèle ne relie pas l’activité entre différents navigateurs, appareils ou profils. Utilisez external_id via changeUser pour une identité authentifiée et multi-appareil.
Récupérez l’ID d’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 l’appel à initialize. Il n’existe pas de méthode setDeviceId post-initialisation permettant de modifier l’ID d’appareil actif. Lisez le paramètre d’URL sur le domaine de destination avant d’appeler initialize.
Les visites directes, les favoris ou les accès au site marchand via des liens tiers sans brazeDeviceId doivent se rabattre sur l’attribution par défaut de l’ID d’appareil — ce qui est attendu lorsqu’il n’y a pas d’ID du domaine source à hériter.
Les paramètres de requête apparaissent dans l’historique du navigateur et les journaux du serveur.
Les paramètres de requête peuvent fuiter via les en-têtes de référent. L’ID d’appareil n’est pas une donnée d’identification en soi, mais supprimez le paramètre après consommation si votre équipe de protection de la vie privée l’exige (voir l’étape 2).
Testez de bout en bout. Confirmez que les événements du domaine 2 utilisent l’ID d’appareil attendu à l’aide de l’inspection réseau.
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’identifiant de l’appareil aux liens inter-domaines sur le domaine source

Sur kitchenerie.com (Domaine 1), initialisez le SDK Web comme d’habitude, puis ajoutez l’identifiant de l’appareil actuel aux liens pointant 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 d’iframe 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 après l’initialisation :

const deviceId = braze.getDeviceId();

Consultez le guide du dépôt du SDK Web — Get Device ID et les options d’initialisation — deviceId.

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

Sur kitchenerie.shop (Domaine 2), lisez brazeDeviceId depuis la chaîne de requête avant initialize, et 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 l’activité future soit associée au profil identifié.

Étape 3 : Vérifier le transfert

Ouvrez le Domaine 1 dans un navigateur où vous n’êtes pas connecté.
Suivez un lien inter-domaines 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 identifiant d’appareil que celui utilisé par le Domaine 1.
Répétez l’opération en accédant directement au Domaine 2 (sans paramètre de requête) et vérifiez qu’un nouvel identifiant d’appareil est attribué.

New Stuff!