Ir para o conteúdo

Esta página foi traduzida automaticamente e pode conter imprecisões. Para relatar um erro de tradução, use o componente de feedback na parte inferior do sumário, à direita da página.

Vincular usuários do Web SDK entre domínios por ID de dispositivo

Passe o ID de dispositivo do Braze Web SDK pela URL de destino quando dois domínios não podem compartilhar cookies, para que sessões anônimas em ambos os sites sejam mapeadas para o mesmo perfil de usuário na Braze.

Sobre este exemplo

A Kitchenerie, uma varejista fictícia de utensílios de cozinha, hospeda um site de marketing (kitchenerie.com) e uma loja (kitchenerie.shop). Cada domínio tem sua própria integração com o Braze Web SDK. Os cookies do navegador não são compartilhados entre domínios. Por isso, a Braze atribui IDs de dispositivo diferentes (e perfis anônimos diferentes) quando o mesmo usuário passa do site de marketing para a loja.

Este cenário:

Lê o ID do dispositivo no domínio de origem com getDeviceId após a inicialização do SDK
Anexa esse ID aos links de saída como um parâmetro de consulta (por exemplo, brazeDeviceId)
No domínio de destino, lê esse parâmetro e o envia para braze.initialize por meio da opção deviceId

Essa transferência é mais importante para usuários anônimos. Depois que o usuário faz login na loja, changeUser com um external_id passa a ser o identificador permanente entre dispositivos. Consulte Definir IDs de usuário.

Os dois domínios devem usar a mesma chave de API do espaço de trabalho da Braze e o mesmo endpoint do SDK, para que os eventos sejam registrados em um único perfil.

Considerações

O ID do dispositivo é por navegador. Este cenário não vincula atividades entre navegadores, dispositivos ou perfis diferentes. Use external_id por meio de changeUser para uma identidade autenticada entre dispositivos.
Recupere o ID do dispositivo somente depois que o Web SDK for inicializado no domínio de origem. Chamar getDeviceId antes de initialize não retorna nenhum valor.
O Web SDK lê deviceId uma única vez, em initialize. Não existe um setDeviceId pós-inicialização que altere o ID de dispositivo ativo. Leia o parâmetro de URL no domínio de destino antes de chamar initialize.
Visitas diretas, favoritos ou referências de terceiros à loja sem brazeDeviceId devem recorrer à atribuição padrão do ID do dispositivo. Esse é o comportamento esperado quando não há um ID do domínio de origem para herdar.
Os parâmetros de consulta aparecem no histórico do navegador e nos logs do servidor.
Os parâmetros de consulta podem vazar pelos cabeçalhos de referência. O ID do dispositivo não é IPI por si só, mas remova o parâmetro depois de usá-lo se a sua equipe de privacidade exigir isso (consulte a Etapa 2).
Teste de ponta a ponta. Confirme com a inspeção de rede que os eventos do Domínio 2 usam o ID do dispositivo esperado.
Adapte os nomes de host, os seletores de links e o tratamento de erros ao seu site. Teste no seu ambiente de desenvolvimento antes da produção.

Configuração

Etapa 1: Anexe o ID do dispositivo aos links entre domínios no domínio de origem

Em kitchenerie.com (Domínio 1), inicialize o Web SDK normalmente. Depois, anexe o ID do dispositivo atual aos links que apontam para kitchenerie.shop (Domínio 2).

Escolha um nome de parâmetro de consulta que não entre em conflito com o seu site (este exemplo usa brazeDeviceId). A mesma ideia se aplica a links renderizados no servidor, à navegação do lado do cliente ou a valores src de iframes que você controla.

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

Se a sua versão do SDK expõe getDeviceId de forma síncrona (sem retorno de chamada), chame-o após a inicialização:

const deviceId = braze.getDeviceId();

Consulte o Guia do repositório do Web SDK — Obter ID do dispositivo e as Opções de inicialização — deviceId.

Etapa 2: Leia o ID do dispositivo e inicialize o Web SDK no domínio de destino

Em kitchenerie.shop (Domínio 2), leia brazeDeviceId da string de consulta antes de initialize e passe-o nas opções de inicialização quando estiver 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());
}

Quando o usuário fizer login, chame changeUser com o external_id dele. Assim, a atividade futura fica vinculada ao perfil identificado.

Etapa 3: Verifique a transferência

Abra o Domínio 1 em um navegador no qual você não esteja conectado.
Siga um link entre domínios para o Domínio 2.
Na guia de rede do navegador, confirme que o Domínio 2 envia eventos com o mesmo ID do dispositivo usado pelo Domínio 1.
Repita o teste com uma visita direta ao Domínio 2 (sem parâmetro de consulta) e confirme que um novo ID do dispositivo é atribuído.

New Stuff!