Ir al contenido

Esta página fue traducida automáticamente y puede contener errores. Para informar de un error de traducción, usa el componente de comentarios situado bajo el sumario, a la derecha de la página.

Vincular usuarios del SDK Web entre dominios mediante el ID de dispositivo

Pasa el ID de dispositivo del SDK Web de Braze a través de la URL de destino cuando dos dominios no pueden compartir cookies, de modo que las sesiones anónimas en ambos sitios se asignen al mismo perfil de usuario de Braze.

Acerca de este ejemplo

Kitchenerie, un comercio minorista ficticio de artículos de cocina, tiene un sitio de marketing (kitchenerie.com) y una tienda (kitchenerie.shop). Cada dominio tiene su propia integración del SDK Web de Braze. Las cookies del navegador no se comparten entre dominios, así que Braze asigna ID de dispositivo distintos (y perfiles anónimos distintos) cuando el mismo usuario pasa del sitio de marketing a la tienda.

En este escenario:

Se lee el ID de dispositivo en el dominio de origen con getDeviceId después de inicializar el SDK
Se añade a los enlaces salientes como parámetro de consulta (por ejemplo, brazeDeviceId)
En el dominio de destino, se lee ese parámetro y se pasa a braze.initialize mediante la opción deviceId

Esta transferencia es más importante para los usuarios anónimos. Cuando el usuario inicia sesión en la tienda, changeUser con un external_id se convierte en el identificador duradero entre dispositivos. Consulta Establecer ID de usuario.

Ambos dominios deben usar la misma clave de API del espacio de trabajo de Braze y el mismo endpoint de SDK para que los eventos lleguen a un único perfil.

Consideraciones

El ID de dispositivo es por navegador. Este escenario no vincula la actividad entre distintos navegadores, dispositivos o perfiles. Usa external_id mediante changeUser para una identidad autenticada entre dispositivos.
Recupera el ID de dispositivo solo después de que el SDK web se haya inicializado en el dominio de origen. Llamar a getDeviceId antes de initialize no devuelve ningún valor.
El SDK web lee deviceId una sola vez en initialize. No existe un setDeviceId posterior a la inicialización que cambie el ID de dispositivo activo. Lee el parámetro de URL en el dominio de destino antes de llamar a initialize.
Las visitas directas, los marcadores o los referidos de terceros a la tienda sin brazeDeviceId deben recurrir a la asignación predeterminada del ID de dispositivo, algo esperable cuando no hay un ID del dominio de origen que heredar.
Los parámetros de consulta aparecen en el historial del navegador y en los registros del servidor.
Los parámetros de consulta pueden filtrarse a través de los encabezados Referer. El ID de dispositivo no es PII por sí solo, pero elimina el parámetro después de usarlo si tu equipo de privacidad lo requiere (consulta el paso 2).
Haz pruebas de extremo a extremo. Confirma mediante la inspección de red que los eventos del dominio 2 usan el ID de dispositivo esperado.
Adapta los nombres de host, los selectores de enlaces y la gestión de errores a tu sitio. Haz pruebas en tu entorno de desarrollo antes de pasar a producción.

Configuración

Paso 1: Añade el ID del dispositivo a los enlaces entre dominios en el dominio de origen

En kitchenerie.com (Dominio 1), inicializa el SDK Web como de costumbre y, después, añade el ID del dispositivo actual a los enlaces que apuntan a kitchenerie.shop (Dominio 2).

Elige un nombre de parámetro de consulta que no entre en conflicto con tu sitio (este ejemplo usa brazeDeviceId). La misma idea se aplica a los enlaces renderizados en el servidor, a la navegación del lado del cliente o a los valores src de iframes que controles.

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 tu versión del SDK expone getDeviceId de forma síncrona (sin devolución de llamada), llámalo después de la inicialización:

const deviceId = braze.getDeviceId();

Consulta Guía del repositorio del SDK Web: obtener el ID del dispositivo y Opciones de inicialización: deviceId.

Paso 2: Lee el ID del dispositivo e inicializa el SDK Web en el dominio de destino

En kitchenerie.shop (Dominio 2), lee brazeDeviceId de la cadena de consulta antes de initialize y pásalo en las opciones de inicialización cuando esté presente.

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

Cuando el usuario inicie sesión, llama a changeUser con su external_id para que la actividad futura quede vinculada al perfil identificado.

Paso 3: Verifica la transferencia

Abre el Dominio 1 en un navegador en el que no hayas iniciado sesión.
Sigue un enlace entre dominios hacia el Dominio 2.
En la pestaña de red del navegador, confirma que el Dominio 2 envía eventos con el mismo ID de dispositivo que usó el Dominio 1.
Repite la prueba con una visita directa al Dominio 2 (sin parámetro de consulta) y confirma que se asigna un nuevo ID de dispositivo.

New Stuff!