이 페이지는 AI로 자동 번역되었으며 부정확한 내용이 포함될 수 있습니다. 번역 오류를 신고하려면 페이지 오른쪽 목차 아래에 있는 피드백 기능을 사용하세요.

기기 ID를 통한 크로스 도메인 웹 SDK 사용자 연결

두 도메인이 쿠키를 공유할 수 없는 경우, 목적지 URL을 통해 Braze 웹 SDK 기기 ID를 전달하면 두 사이트의 익명 세션이 동일한 Braze 고객 프로필에 매핑됩니다.

이 예시에 대하여

가상의 주방용품 소매업체인 Kitchenerie는 마케팅 사이트(kitchenerie.com)와 쇼핑몰(kitchenerie.shop)을 운영합니다. 각 도메인에는 별도의 Braze Web SDK 통합이 있습니다. 브라우저 쿠키는 도메인 간에 공유되지 않으므로, 같은 사용자가 마케팅 사이트에서 쇼핑몰로 이동하면 Braze는 별도의 기기 ID와 별도의 익명 프로필을 할당합니다.

이 시나리오는 다음과 같이 진행됩니다.

SDK 초기화 후 getDeviceId로 소스 도메인의 기기 ID를 읽습니다.
읽은 기기 ID를 아웃바운드 링크에 쿼리 매개변수(예: brazeDeviceId)로 추가합니다.
대상 도메인에서 해당 매개변수를 읽고 deviceId 옵션을 통해 braze.initialize에 전달합니다.

이 핸드오프는 익명 사용자에게 가장 중요합니다. 사용자가 쇼핑몰에 로그인한 후에는 external_id를 사용한 changeUser가 여러 기기에 걸쳐 지속되는 식별자가 됩니다. 사용자 ID 설정을 참조하세요.

이벤트가 하나의 프로필에 기록되도록 두 도메인 모두 동일한 Braze 워크스페이스 API 키와 SDK 엔드포인트를 사용해야 합니다.

고려 사항

기기 ID는 브라우저별로 지정됩니다. 이 시나리오에서는 서로 다른 브라우저, 기기 또는 프로필 간의 활동을 연결하지 않습니다. 인증된 크로스 기기 ID가 필요하면 changeUser를 통해 external_id를 사용하세요.
기기 ID는 소스 도메인에서 Web SDK가 초기화된 후에만 가져오세요. initialize 전에 getDeviceId를 호출하면 값이 반환되지 않습니다.
Web SDK는 initialize 시점에 deviceId를 한 번만 읽습니다. 초기화 후에 활성 기기 ID를 변경하는 setDeviceId는 없습니다. 대상 도메인에서는 initialize를 호출하기 전에 URL 파라미터를 읽으세요.
brazeDeviceId 없이 쇼핑몰에 직접 방문하거나, 북마크 또는 서드파티 추천을 통해 방문하는 경우에는 기본 기기 ID 할당 방식으로 대체되어야 합니다. 상속할 소스 도메인 ID가 없으므로 이는 예상된 동작입니다.
쿼리 파라미터는 브라우저 기록과 서버 로그에 표시됩니다.
쿼리 파라미터는 리퍼러 헤더를 통해 노출될 수 있습니다. 기기 ID 자체는 PII가 아니지만, 개인정보 보호팀에서 요구하는 경우 사용 후 파라미터를 제거하세요(2단계 참조).
포괄적으로 테스트하세요. 네트워크 검사를 통해 도메인 2의 이벤트가 예상한 기기 ID를 사용하는지 확인하세요.
호스트 이름, 링크 SELECTOR, 오류 처리를 사이트에 맞게 조정하세요. 프로덕션에 적용하기 전에 개발 환경에서 테스트하세요.

설정

1단계: 소스 도메인의 크로스 도메인 링크에 기기 ID 추가하기

kitchenerie.com(도메인 1)에서 평소와 같이 Web SDK를 초기화한 다음, kitchenerie.shop(도메인 2)을 가리키는 링크에 현재 기기 ID를 추가합니다.

사이트에서 사용하는 다른 이름과 충돌하지 않는 쿼리 매개변수 이름을 선택합니다(이 예제에서는 brazeDeviceId 사용). 서버에서 렌더링하는 링크, 클라이언트 측 탐색, 직접 관리하는 iframe src 값에도 같은 아이디어를 적용할 수 있습니다.

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

사용 중인 SDK 버전이 getDeviceId를 동기 방식(콜백 없음)으로 제공한다면, 대신 초기화 후에 다음과 같이 호출합니다.

const deviceId = braze.getDeviceId();

Web SDK 리포지토리 가이드 — 기기 ID 가져오기 및 초기화 옵션 — deviceId를 참조하세요.

2단계: 대상 도메인에서 기기 ID를 읽고 Web SDK 초기화하기

kitchenerie.shop(도메인 2)에서 initialize 전에 쿼리 문자열에서 brazeDeviceId를 읽고, 값이 있으면 초기화 옵션에 전달합니다.

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

사용자가 로그인하면 해당 사용자의 external_id로 changeUser를 호출하여 이후 활동이 식별된 프로필에 연결되도록 합니다.

3단계: 핸드오프 확인하기

로그인하지 않은 상태의 브라우저에서 도메인 1을 엽니다.
크로스 도메인 링크를 따라 도메인 2로 이동합니다.
브라우저 네트워크 탭에서 도메인 2가 도메인 1에서 사용한 것과 동일한 기기 ID로 이벤트를 전송하는지 확인합니다.
도메인 2에 직접 방문(쿼리 매개변수 없음)하여 같은 과정을 반복하고, 새 기기 ID가 할당되는지 확인합니다.

New Stuff!