Zum Inhalt springen

Diese Seite wurde automatisch übersetzt und kann Ungenauigkeiten enthalten. Um einen Übersetzungsfehler zu melden, nutzen Sie das Feedback unten im Inhaltsverzeichnis rechts auf der Seite.

Domainübergreifende Web-SDK-Nutzer:innen über die Geräte-ID verknüpfen

Übergeben Sie die Geräte-ID des Braze Web SDK über die Ziel-URL, wenn zwei Domains keine Cookies teilen können, damit anonyme Sitzungen auf beiden Websites demselben Braze-Kundenprofil zugeordnet werden.

Über dieses Beispiel

Kitchenerie, ein fiktiver Händler für Küchenzubehör, betreibt eine Marketing-Website (kitchenerie.com) und einen Shop (kitchenerie.shop). Jede Domain verfügt über eine eigene Integration des Braze Web SDK. Browser-Cookies gelten nicht domainübergreifend. Deshalb vergibt Braze separate Geräte-IDs und legt separate anonyme Profile an, wenn dieselbe Person von der Marketing-Website in den Shop wechselt.

In diesem Szenario passiert Folgendes:

Die Geräte-ID wird auf der Quell-Domain nach der SDK-Initialisierung mit getDeviceId ausgelesen.
Die ID wird ausgehenden Links als Abfrageparameter angehängt (zum Beispiel brazeDeviceId).
Auf der Ziel-Domain wird dieser Parameter ausgelesen und über die Option deviceId an braze.initialize übergeben.

Diese Übergabe ist vor allem für anonyme Nutzer:innen wichtig. Sobald sich Nutzer:innen im Shop anmelden, wird changeUser mit einer external_id zum dauerhaften Bezeichner über alle Geräte hinweg. Weitere Informationen finden Sie unter Nutzer-IDs festlegen.

Beide Domains sollten denselben API-Schlüssel des Braze-Workspace und denselben SDK-Endpunkt verwenden, damit Events in einem einzigen Profil landen.

Hinweise

Die Geräte-ID gilt pro Browser. Dieses Szenario verknüpft keine Aktivitäten über verschiedene Browser, Geräte oder Profile hinweg. Verwenden Sie external_id über changeUser für eine authentifizierte, geräteübergreifende Identität.
Rufen Sie die Geräte-ID erst ab, nachdem das Web SDK auf der Quell-Domain initialisiert wurde. Ein Aufruf von getDeviceId vor initialize gibt keinen Wert zurück.
Das Web SDK liest deviceId einmalig bei initialize. Es gibt kein setDeviceId nach der Initialisierung, das die aktive Geräte-ID ändert. Lesen Sie den URL-Parameter auf der Ziel-Domain aus, bevor Sie initialize aufrufen.
Direkte Besuche, Lesezeichen oder Empfehlungen von Drittanbietern zum Shop ohne brazeDeviceId sollten auf die standardmäßige Zuweisung der Geräte-ID zurückfallen. Das ist zu erwarten, wenn keine ID der Quell-Domain übernommen werden kann.
Abfrageparameter erscheinen im Browserverlauf und in Server-Logs.
Abfrageparameter können über Referrer-Header nach außen gelangen. Die Geräte-ID allein ist keine PII, entfernen Sie den Parameter jedoch nach der Verarbeitung, wenn Ihr Datenschutzteam dies verlangt (siehe Schritt 2).
Testen Sie End-to-End. Überprüfen Sie mithilfe der Netzwerkanalyse, dass Events auf Domain 2 die erwartete Geräte-ID verwenden.
Passen Sie Hostnamen, Link-Selektoren und Fehlerbehandlung an Ihre Website an. Testen Sie in Ihrer Entwicklungsumgebung, bevor Sie in die Produktion gehen.

Einrichtung

Schritt 1: Geräte-ID an domainübergreifende Links auf der Quelldomain anhängen

Initialisieren Sie auf kitchenerie.com (Domain 1) das Web SDK wie gewohnt und hängen Sie dann die aktuelle Geräte-ID an Links an, die auf kitchenerie.shop (Domain 2) verweisen.

Wählen Sie einen Namen für den Abfrageparameter, der nicht mit Ihrer Website kollidiert (in diesem Beispiel brazeDeviceId). Dasselbe Prinzip gilt für serverseitig gerenderte Links, clientseitige Navigation oder src-Werte von iframes, die Sie kontrollieren.

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).
    }
  });
});

Wenn Ihre SDK-Version getDeviceId synchron bereitstellt (ohne Callback), rufen Sie die Methode stattdessen nach der Initialisierung auf:

const deviceId = braze.getDeviceId();

Siehe Web SDK Repository-Leitfaden – Geräte-ID abrufen und Initialisierungsoptionen – deviceId.

Schritt 2: Geräte-ID auslesen und Web SDK auf der Zieldomain initialisieren

Lesen Sie auf kitchenerie.shop (Domain 2) brazeDeviceId vor initialize aus dem Query-String aus und übergeben Sie den Wert, sofern vorhanden, in den Initialisierungsoptionen.

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

Wenn sich Nutzer:innen anmelden, rufen Sie changeUser mit ihrer external_id auf, damit künftige Aktivitäten mit dem identifizierten Profil verknüpft werden.

Schritt 3: Übergabe überprüfen

Öffnen Sie Domain 1 in einem Browser, in dem Sie nicht angemeldet sind.
Folgen Sie einem domainübergreifenden Link zu Domain 2.
Bestätigen Sie im Netzwerk-Tab des Browsers, dass Domain 2 Events mit derselben Geräte-ID sendet, die Domain 1 verwendet hat.
Wiederholen Sie den Vorgang mit einem direkten Aufruf von Domain 2 (ohne Abfrageparameter) und bestätigen Sie, dass eine neue Geräte-ID zugewiesen wird.

New Stuff!