가이드 및 설문조사 웹 SDK.

Amplitude의 가이드 및 설문조사 SDK를 사용하면 웹사이트 또는 애플리케이션에 가이드 및 설문조사를 배포할 수 있습니다.

SDK 설치

가이드 및 설문조사는 기존 Amplitude 구현(있는 경우)과 가장 잘 작동하도록 다양한 설치 옵션을 지원합니다.

Amplitude 브라우저 SDK 2

Amplitude Browser SDK v2를 사용하는 경우, 가이드 및 설문조사 SDK를 스크립트와 함께 설치하거나 npm 또는 Yarn과 함께 패키지로 설치하십시오.

이 접근 방식은 Amplitude Browser SDK의 플러그인 시스템을 사용하며, 이를 통해 핵심 분석 SDK를 추가 기능으로 확장할 수 있습니다. 호출은 가이드 및 설문조사를 플러그인으로 amplitude.add(engagementPlugin())등록합니다. 가이드 및 설문조사는 분석과 함께 초기화되고, 동일한 API 키와 사용자 ID를 공유하며, 분석과 직접 통신합니다. 별도로 호출하거나 따로 init수행할 필요가 없습니다boot.

amplitude.init() 전에 amplitude.add(engagementPlugin())을 호출하세요. 이를 통해 분석 SDK가 플러그인의 초기화를 제어할 수 있으므로 가이드 및 설문조사가 부팅될 때 사용자 ID와 세션이 준비되어 있습니다.

<script src="https://cdn.amplitude.com/script/API_KEY.engagement.js"></script>
<script>
  amplitude.add(window.engagement.plugin());
</script>

await amplitude.init("API_KEY").promise;
amplitude.add(engagementPlugin());

추가 구성을 위해서는 plugin함수에 공급하십시오InitOptions. 사용 가능한 옵션을 확인하려면 SDK 초기화로 이동하십시오.

예를 들어, 플러그인이 자동으로 autoRefreshIntervalSeconds다음을 호출하므로 날짜 이후 플러그인 시간에 자동 새로 고침을 구성하는 데 boot()사용하십시오.

import { plugin as engagementPlugin } from "@amplitude/engagement-browser";
amplitude.add(
  engagementPlugin({
    autoRefreshIntervalSeconds: 3600,
  }),
);

Amplitude Browser 통합 SDK

Amplitude Browser 통합 SDK에는 기본적으로 가이드 및 설문조사가 포함되어 있습니다. 초기화 다음 기간동안 인게이지먼트 옵션을 제공합니다.

import { initAll } from "@amplitude/unified";
initAll("YOUR_API_KEY", {
  // Other Amplitude SDK options...
  engagement: {
    // Guides and Surveys options go here...
  },
});

가이드 및 설문조사를 표시하기 전에 Amplitude 프로젝트 설정에서 가이드 및 설문조사를 활성화하십시오. 자세한 내용은 Unified SDK 설명서를 참조하십시오.

독립형 설치: 기타 Amplitude SDK, 타사 분석 공급자 및 프록시 설정

다음과 같은 경우 이 독립형 설치 경로를 사용하십시오.

• 브라우저 SDK 2 또는 브라우저 통합 SDK 이외의 Amplitude SDK를 사용하십시오.
• 타사 분석 공급자를 사용하십시오(예: 세그먼트, 힙 또는 믹스패널).
• 브라우저 SDK 2를 프록시 서버와 함께 사용하십시오.

이 설치에는 다음 단계가 필요합니다.

1. 스크립트 태그를 사용하거나 npm또는 yarn을 통해 가이드 및 설문조사 SDK를 추가하십시오.
2. 가이드 및 설문조사를 초기화하고 이를 분석 공급업체에 연결하려면 init및 boot를 직접 호출하십시오.

SDK 초기화

번들을 완전히 초기화하고 전역 window 객체에 engagement를 등록하려면 init를 호출하십시오.

engagement.init(apiKey: string, options: { serverZone: "US" | "EU", serverUrl: string, cdnUrl: string, mediaUrl: string, logger: Logger, logLevel: LogLevel, locale: string, nonce: string, autoRefreshIntervalSeconds: number, skip: boolean, transport: { headers: Record<string, string> | (() => Record<string, string>), handleHttpRequest: (request: TransportHttpRequest) => Promise<Response> } }): void

예: 기본 초기화

engagement.init("YOUR_API_KEY", {
  serverZone: "US",
  logLevel: LogLevel.Warn,
});

예: 프록시를 사용한 초기화

프록시 설정의 경우 serverUrl, cdnUrl 및 mediaUrl을 지정합니다. AI를 사용하는 경우 채팅 요청을 다른 호스트로 전송하므로 chatUrl추가하십시오:

engagement.init("YOUR_API_KEY", {
  serverUrl: "https://your-proxy-domain.cloudfront.net",
  cdnUrl: "https://your-proxy-domain.cloudfront.net",
  mediaUrl: "https://your-proxy-domain.cloudfront.net",
  chatUrl: "https://your-proxy-domain.cloudfront.net",
});

예: CSP nonce를 사용한 초기화

콘텐츠 보안 정책(CSP) 컴플라이언스를 위해 nonce 값을 포함하십시오.

engagement.init("YOUR_API_KEY", {
  nonce: "YOUR_NONCE",
});

예: 자동 새로 고침을 사용한 초기화

자동 새로고침을 활성화하여 타겟팅 데이터를 주기적으로 다시 가져오고 구성을 다시 로드하십시오.

engagement.init("YOUR_API_KEY", {
  autoRefreshIntervalSeconds: 3600,
});

예: 건너뛰기를 사용한 지연된 초기화

SDK를 초기화하거나 프록시를 설정하지 않고 창 객체에 등록하는 데 skip사용합니다engagement. 초기화를 완료하기 위해 나중에 skip없이 init다시 호출한 다음, 시작하려면 boot()를 호출하십시오.

// Register the engagement object without initializing
engagement.init("YOUR_API_KEY", { skip: true });
// Later, when ready to initialize
engagement.init("YOUR_API_KEY", { serverZone: "US" });
engagement.boot({ user_id: "USER_ID" });

이 함수를 호출한 후에는 SDK 함수에 window.engagement 액세스하고 호출할 수 있습니다. 가이드 및 설문조사는 boot를 호출하기 전까지는 완전히 작동하지 않습니다.

부트 사용자

사용자에게 가이드 및 설문조사를 제공하려면 init다음에 boot를 호출하십시오. 독립형 설치의 경우 SDK 스크립트가 페이지에 로드되더라도 boot를 호출할 때까지 가이드 및 설문조사는 작동하지 않습니다.

매개변수 옵션, 유형 정의 및 사용 예제를 포함한 boot 방법에 대한 자세한 문서는 Boot를 참조하십시오.

다음 예제에서는 사용자 ID, 장치 ID 및 사용자 속성을 사용하여 boot호출합니다. 또한 가이드 및 설문조사 이벤트를 분석 공급자에게 integrations전달하도록 지정합니다.

await window.engagement.boot({
  user: {
    user_id: "user123",
    device_id: "device456",
    user_properties: {
      plan: "premium",
    },
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

이벤트 전달

On event tracked 트리거를 사용하려면 분석 공급업체의 이벤트를 가이드 및 설문조사로 전달하십시오. 가이드 및 설문조사 SDK는 이러한 이벤트를 Amplitude로 전송하지 않습니다. SDK는 이를 로컬 트리거 평가에만 사용합니다.

analytics.on("track", (event, properties, options) => {
  // Example for Segment Analytics
  window.engagement.forwardEvent({
    event_type: event,
    event_properties: properties,
  });
});

Segment를 사용하는 경우 이벤트 부팅 및 전달 예

구글 태그 관리자

아직 업데이트하지 않은 경우 최신 버전의 Amplitude 템플릿으로 업데이트하십시오. GTM의 템플릿 페이지에서 업데이트 아이콘을 찾으십시오.

그런 다음 태그 페이지에서 가이드 및 설문조사를 활성화합니다.

설치 및 초기화 확인

가이드 및 설문조사 SDK가 귀하의 사이트 또는 개발 환경에서 실행되고 있는지 확인하려면 브라우저의 개발자 도구를 열고 콘솔에 다음을 입력하십시오.

window.engagement;

응답이 undefined인 경우 가이드 및 설문조사가 제대로 설치되지 않았습니다.

콘텐츠 보안 정책(CSP)

조직에 엄격한 콘텐츠 보안 정책(CSP)이 있는 경우 가이드 및 설문조사가 원활하게 작동하도록 몇 가지 추가 기능이 필요합니다. 다음 CSP 지시어를 정책에 추가하십시오.

script-src: https://*.amplitude.com;
connect-src: https://*.amplitude.com;
img-src: https://*.amplitude.com;
media-src: https://*.amplitude.com;
style-src: https://*.amplitude.com;

인라인 스타일을 차단하는 더 엄격한 CSP 요구 사항을 가진 환경의 경우 초기화 중에 nonce매개변수를 사용하십시오. 이 매개변수를 사용하면 가이드 및 설문조사에서 CSP 논스 값을 포함하여 필요한 인라인 스타일을 실행할 수 있습니다.

engagement.init("YOUR_API_KEY", {
  nonce: "YOUR_NONCE",
});

iframe 지원 및 제한 사항

가이드 및 설문조사는 iframe을 사용하는 애플리케이션에 대한 지원을 제한적으로 제공합니다. iframe 기반 애플리케이션에서 가이드 및 설문조사를 구현할 때는 이러한 제한 사항을 고려하십시오.

iframe 내부의 요소를 타겟팅하기:

• 핀과 툴팁은 부모 애플리케이션의 iframe 내부의 요소를 대상으로 삼을 수 없습니다.
• 각 iframe에는 해당 iframe 내에 가이드나 설문조사를 표시하기 위한 자체 SDK 인스턴스가 필요합니다.
• CSS 선택기는 iframe 경계를 넘을 수 없으므로 SDK가 iframe 내에서 요소를 찾을 수 없습니다.

SDK 인스턴스 및 다단계 경험:

• 각 iframe에는 부모 애플리케이션과 동일한 API 키로 초기화된 별도의 SDK 인스턴스가 필요합니다.
• 상위 응용 프로그램과 iframe에 걸쳐 진행되는 다단계 탐색은 지원되지 않습니다.
• 각 SDK 인스턴스는 독립적으로 작동하며 서로 다른 컨텍스트에서 단계를 조정할 수 없습니다.

이벤트 트래킹 및 사용자 식별:

• iframe에서 추적되는 이벤트는 상위 애플리케이션의 이벤트와 독립적입니다.
• 모든 SDK 인스턴스에서 일관된 사용자 식별(사용자 ID 및 장치 ID)을 보장합니다.
• 각 SDK 인스턴스는 자체 상태를 유지하며 다른 인스턴스와 데이터를 공유하지 않습니다.

도구 모음 및 미리 보기:

• 각 SDK 인스턴스는 자체 디버그 및 미리보기 도구 모음을 렌더링하므로 iframe이 있는 페이지는 둘 이상의 도구 모음을 표시합니다.
• 각 도구 모음에는 인스턴스 이름(default 또는 iframe: {id})이 있는 색상 배지가 표시되며 다른 도구 모음과 수직으로 겹쳐지므로 겹쳐진 도구 모음은 계속 접근 가능합니다.
• 각 도구 모음은 자체 인스턴스만 제어합니다. 요소 선택 및 미리 보기는 인스턴스가 실행된 프레임에 수행되므로, 대상 요소가 포함된 프레임에 해당하는 도구 모음을 선택하세요.

권장되는 접근법:

• 상위 애플리케이션과 가이드 또는 설문조사를 표시해야 하는 각 iframe 모두에 SDK를 설치하십시오.
• 일관된 사용자 식별을 보장하려면 모든 SDK 인스턴스에 동일한 API 키를 사용하십시오.
• 단일 컨텍스트(상위 또는 특정 iframe)에서 작동하도록 가이드 및 설문조사를 디자인합니다.

설치 문제 해결

가이드 및 설문조사 구현이 작동하지 않는 경우 다음 항목을 확인하십시오.

가이드 및 설문조사 설치 확인

1. 브라우저의 개발자 콘솔을 열고 window.engagement를 입력합니다. 반환 값이 undefined인 경우 가이드 및 설문조사 설치 작업이 성공적으로 수행되지 않았습니다.
2. 유효한 응답이 반환되면 window.engagement를 입력합니다. window.engagement._.user``undefined가 반환되면 Amplitude Browser SDK 플러그인 구성에 문제가 있음을 나타냅니다.
3. 추가 디버깅을 하려면 window.engagement._debugStatus()를 입력하십시오. 출력은 다음과 같아야 합니다.

{
  "user": {
    "user_id": "test-base-user-1vxxkg",
    "device_id": "62c5e45a-94ab-4090-b053-3f28e848763f",
    "user_properties": {
      "foo": "bar"
    }
  },
  "apiKey": "6ae8d3d7d48eadfb0b2489db692e14c9",
  "stateInitialized": true,
  "decideSuccessful": true,
  "num_guides_surveys": 2,
  "analyticsIntegrations": 1
}

다음을 확인하십시오.

• user객체가 존재합니다.
• apiKey 설정되었습니다.
• stateInitialized true입니다.
• decideSuccessful true입니다.
• num_guides_surveys 는 페이지에 안내서나 설문조사를 표시해야 하는 경우 0이 아닌 정수입니다.

Amplitude Browser SDK 플러그인 구성 확인

Amplitude Browser SDK 2.0을 사용하는 경우 브라우저 콘솔에서 오류가 있는지 확인하십시오. 해당 항목이 없는 경우 코드가 설치 지침과 일치하는지 확인하십시오. 특히 amplitude.add(window.engagement.plugin())이 코드에 존재하는지 확인하십시오.

amplitude is not defined및 cannot read properties of undefined .add()과 같은 오류가 표시되면 가이드 및 설문조사가 Amplitude SDK가 로드되기 전에 로드될 수 있습니다. 코드를 확인하여 Amplitude Browser SDK가 가이드 및 설문조사 SDK보다 먼저 로드되는지 확인하십시오.

가이드 및 설문조사는 브라우저 SDK 2가 필요하며 기존 Amplitude JavaScript SDK를 지원하지 않습니다.

Google 태그 관리자 구성

Google 태그 관리자를 사용하는 경우, 최신 Amplitude 템플릿으로 업데이트해야 합니다.

일반적인 근본 원인

다음과 같은 일반적인 오류는 가이드 및 설문조사를 실행하지 못하게 할 수 있습니다.

boot 두 번 이상 실행

두 번 이상 호출하면 예기치 않은 동작이 발생할 수 있으며, 특히 즉시 표시되어야 하는 가이드 및 설문조사의 경우에는 boot더욱 그렇습니다.

잘못된 프로젝트를 사용했습니다.

제공한 API 키를 확인하십시오.

• 브라우저 SDK를 초기화하는 데 사용하는 것과 동일한 키입니다.
• 가이드 및 설문조사 구성을 포함하는 프로젝트에 속합니다.

가이드 및 설문조사와 분석에 서로 다른 API 키를 사용하면 SDK가 잘못된 프로젝트에서 가이드 및 설문조사를 가져오게 되며 분석 데이터가 불완전하거나 일치하지 않습니다. 두 SDK가 동일한 Amplitude 프로젝트에 연결되도록 항상 동일한 API 키를 사용하세요.

현지화

초기화 다음 기간동안 locale옵션을 설정하여 가이드 또는 설문조사를 현지화합니다.

• Amplitude Browser SDK 2 플러그인 설치를 사용하고 있는 경우(amplitude.add()를 사용하여) InitOptions로케일을 설정합니다.
• 타사 분석 공급자를 사용하는 경우 engagement.init()메서드 첫 사용 후 options로케일을 설정하십시오.

SDK가 초기화된 후 언어를 동적으로 업데이트하려면 다음 updateLanguage 방법을 사용하십시오. updateLanguage를 호출하면 새 로케일로 구성을 다시 가져옵니다.

engagement.updateLanguage(locale: string): Promise<void>

// Example: Update language to French
await window.engagement.updateLanguage("fr");
// Example: Update language to English
await window.engagement.updateLanguage("en");

사용자 지정 HTTP 요청 헤더

초기화 시 transport 옵션을 전달하여 가이드 및 설문조사 SDK의 모든 발신 요청에 사용자 지정 HTTP 헤더를 첨부합니다. 이 정보를 사용하여 보안 프록시 또는 송신 게이트웨이를 통해 요청을 인증하거나, 인프라에 필요한 테넌트 식별 헤더를 추가할 수 있습니다. 이 기능은 serverUrl을 통해 구성된 프록시 설정과 잘 어울립니다.

headers 헤더 키-값 쌍의 정적 객체를 허용합니다:

engagement.init("YOUR_API_KEY", {
  transport: {
    headers: {
      "X-Corp-Auth": "your-gateway-token",
      "X-Tenant-Id": "your-tenant-id",
    },
  },
});

회사 게이트웨이에 필요한 수명이 짧은 JWT와 같이 자격 증명이 순환되는 경우 함수를 대신 전달하십시오. SDK는 각 요청 전에 동기적으로 함수를 호출하므로 SDK를 다시 초기화하지 않아도 함수가 반환하는 헤더는 항상 최신 상태입니다. 함수는 헤더 객체를 직접 반환해야 합니다. 비동기 함수는 지원되지 않으므로, 함수 내에서 토큰을 가져오기보다는 애플리케이션이 토큰을 저장한 곳에서 읽으십시오:

engagement.init("YOUR_API_KEY", {
  transport: {
    headers: () => ({
      // Synchronous read of a token your application keeps up to date
      "X-Corp-Auth": getCurrentGatewayJwt(),
    }),
  },
});

다음 동작에 유의하십시오.

• 사용자 지정 헤더는 SDK 내부 헤더 뒤에 병합되므로 이름이 같은 사용자 지정 헤더가 SDK 자체 값을 재정의합니다. Authorization 설정을 피하십시오. SDK는 내부적으로 이를 사용하여 프로젝트 API 키로 일부 요청을 인증하며, 이를 재정의하면 해당 요청이 중단됩니다.
• 헤더 함수에서 예외를 던지면 SDK는 경고를 기록하고 요청을 실패시키는 대신 사용자 지정 헤더 없이 요청을 전송합니다.

헤더 이상을 사용자 정의하려면(예: 쿠키 인증 프록시의 credentials정책), 사용자 지정 전송으로 이동하십시오.

맞춤형 운송

예를 들어 보안 프록시가 헤더가 아닌 credentialsfetch 옵션이 필요한 쿠키로 인증하는 등 사용자 지정 헤더만으로 충분하지 않은 경우, 초기화 시 transport.handleHttpRequest콜백을 제공하세요. 설정된 경우 SDK는 모든 발신 요청에 대해 내부 fetch로직 대신 사용자의 콜백을 호출하며, 콜백이 HTTP 호출을 완전히 제어합니다. 이는 세션 리플레이 SDK의 사용자 지정 전송 후크를 미러링합니다.

SDK는 확인된 URL(serverUrl및 관련 옵션 준수), 병합된 헤더(전체 포함) 및 직렬화된 본문을 포함하여 완전히 구성된 요청을 콜백에 전달합니다.transport.headers 콜백의 유일한 작업은 요청을 실행하고 Response를 반환하는 것입니다. 배치 처리, 직렬화, 재시도 및 오류 처리는 SDK 내에 유지되며, 이는 재시도 시도마다 한 번씩 콜백을 호출합니다.

쿠키 인증 프록시의 경우 브라우저가 사이트의 쿠키를 프록시로 전송하도록 요청을 credentials: "include" 와 함께 전달하십시오:

engagement.init("YOUR_API_KEY", {
  serverUrl: "https://your-proxy-domain.example.com/gs",
  transport: {
    handleHttpRequest: ({ url, method, headers, body, signal, keepalive }) =>
      fetch(url, {
        method,
        headers,
        body,
        signal,
        keepalive,
        credentials: "include",
      }),
  },
});

JWT 인증 프록시의 경우 SDK에서 제공한 헤더를 펼치고 고유한 헤더를 추가하세요:

engagement.init("YOUR_API_KEY", {
  transport: {
    handleHttpRequest: ({ url, method, headers, body, signal, keepalive }) =>
      fetch(url, {
        method,
        headers: { ...headers, "X-Corp-Auth": getCurrentGatewayJwt() },
        body,
        signal,
        keepalive,
      }),
  },
});

콜백이 수신하는 요청 객체에는 다음 필드가 있습니다.

다음 동작에 유의하십시오.

• 향후 SDK 버전에서 추가될 필드를 포함하여 수신되는 모든 필드를 전달하여, 취소 및 페이지 종료 전달과 같은 SDK 동작이 콜백을 통해 계속 작동하도록 하십시오.
• fetch호출에서 받은 Response것을 수정하지 않고 반환하십시오. AI 어시스턴트 채팅 요청은 응답 본문에서 점진적으로 소비되므로 응답은 진정한 스트리밍Response이어야 합니다.
• throwing headers 함수와 달리 콜백 오류는 요청을 실패시킵니다. 인증되지 않은 요청은 프록시의 인증을 우회할 수 있으므로, 콜백을 구성할 때 SDK는 결코 기본 제공 기능으로 폴백되지 않습니다fetch.
• 콜백에는 핵심 API 호출, AI Assistant REST 요청, SSE 스트림 및 첨부 파일 업로드가 포함됩니다. 미디어 및 CDN 자산 로드는 다루지 않습니다. 해당 항목에는 cdnUrl 및 mediaUrl 프록시 구성을 사용하십시오.

데스크톱 앱의 미리보기 모드

데스크톱 프레임워크 첫 사용 후 SDK를 사용하는 경우, 가이드 및 설문조사 미리보기를 지원하기 위해 추가 계측을 수행해야 합니다.

Amplitude 대시보드는 딥 링크(예: your-app://?gs-debug-id=123)를 통해 앱에 특수 쿼리 매개변수를 전달합니다. 앱 첫 사용 후 로직을 추가하여 딥 링크에서 이 쿼리 매개변수를 수신하고 이를 사용하여 _startNudgeDebugSDK 메서드를 호출하세요.

다음 프레임워크 예를 사용하십시오.

Electron

Electron 첫 사용 후 가이드 및 설문조사를 구현하려면 다음 최소한의 예제를 사용하십시오.

1. 프리로드 다음 기간동안 프로세스 간 통신 기능을 등록합니다.
2. 기본 프로세스에서: gs-debug-id쿼리 매개변수를 수신하고 구문 분석합니다.
3. 렌더러 프로세스에서: 주 프로세스에서 오는 메시지를 수신하고 디버그 매개변수를 Engagement SDK에 전달합니다.

const { app } = require("electron");
// Handle deep link on macOS
app.on("open-url", (event, url) => {
  const parsedUrl = new URL(url);
  const debugId = parsedUrl.searchParams.get("gs-debug-id");
  if (debugId) {
    mainWindow.webContents.send("start-engagement-debug", {
      debugId: debugId,
    });
  }
});
// Handle deep link on Windows/Linux
app.on("second-instance", (event, commandLine, workingDirectory) => {
  // Find the deep link URL in command line arguments
  const url = commandLine.find((arg) => arg.startsWith(PROTOCOL + "://"));
  if (url) {
    const parsedUrl = new URL(url);
    const debugId = parsedUrl.searchParams.get("gs-debug-id");
    if (debugId) {
      mainWindow.webContents.send("start-engagement-debug", {
        debugId: debugId,
      });
    }
  }
});

생애주기 분석 SDK 방법

부팅

가이드 및 설문조사 SDK를 초기화하고 사용자가 사용할 수 있도록 boot호출하십시오. Amplitude Browser SDK v2 또는 Amplitude Browser Unified SDK를 사용하지 않는 경우, SDK 스크립트가 페이지에 로드되더라도 boot를 호출할 때까지 가이드 및 설문조사가 작동하지 않습니다. 이 방법은 라이브 가이드 및 설문조사에 대한 타겟팅 해결을 트리거하고 가이드 및 설문조사 SDK에서 분석 공급자로의 연결을 설정합니다. 활성 사용자를 변경해야 하는 경우가 아니면 세션당 한 번씩 호출하십시오boot.

engagement.boot(options: BootOptions): Promise<void>

엔드 유저 유형

EndUser이 유형에는 다음 속성이 포함됩니다.

필수 필드: 최소한 user_id 또는 device_id을 제공해야 합니다. 두 필드 모두 제공하지 않으면 메서드에서 오류를 기록하고 일찍 반환합니다.

연동 유형

Integration유형에는 하나의 속성이 포함됩니다.

부팅 예제

예제 1: 사용자 객체의 기본 사용법

await window.engagement.boot({
  user: {
    user_id: "user123",
    user_properties: {
      name: "John Doe",
      plan: "premium",
      signupDate: "2023-01-15",
    },
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

예 2: 분석 연동 사용

await window.engagement.boot({
  user: {
    user_id: "user123",
    device_id: "device456",
    user_properties: {
      plan: "premium",
    },
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

예제 3: 동적 사용자 데이터에 대한 함수 공급자 사용

await window.engagement.boot({
  user: () => {
    return {
      user_id: getCurrentUserId(),
      device_id: getDeviceId(),
      user_properties: getUserProperties(),
    };
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

예 4: 단순 사용자 ID

await window.engagement.boot({
  user: "user123",
  integrations: [],
});

부팅 사용 요구 사항

• 비동기 메서드: boot비동기 메서드입니다. 항상 Promise로 사용하거나 await처리하십시오.
• 필수: 전체 가이드나 설문조사가 표시되기 전에 반드시 호출해야 합니다boot.
• 큐 처리: 부트 호출 프로세스는 SDK의 메서드 큐에서 먼저 수행됩니다.
• 세션당 단일 호출: 일반적으로 사용자 세션당 boot한 번의 호출입니다.

시스템 종료

가이드 및 설문조사 SDK를 종료합니다. 이 메서드는 모든 활성 가이드 및 설문조사를 닫고 가이드 및 설문조사가 트리거되는 것을 중단합니다. 사용자가 로그아웃할 때와 같이 SDK를 완전히 정리해야 할 때 이 방법을 사용하십시오.

engagement.shutdown(): void

shutdown()를 호출한 후에는 SDK가 더 이상 작동하지 않습니다. 가이드 및 설문조사를 다시 사용하려면 다시 호출하십시오boot().

타겟팅 새로고침

decide 엔드포인트에 새 요청을 제출하여 백엔드에서 타겟팅 평가를 다시 가져옵니다. 이 방법을 사용하여 최신 타겟팅 규칙과 사용자 상태를 기반으로 표시할 수 있는 가이드와 설문조사를 새로 고칩니다. SDK는 사용자 또는 사용자 속성이 변경될 때 타겟팅을 자동으로 새로 고칩니다. 수동으로 타겟팅을 새로 고치는 것은 서버측에서 사용자 속성을 업데이트하거나 최신 코호트 멤버십 상태가 필요한 경우에 유용합니다.

engagement.decide(): Promise<void>

자동 새로 고침 간격 설정

타겟팅 데이터의 자동 주기적 새로 고침을 구성합니다. 활성화되면 SDK는 자동으로 결정 데이터를 다시 가져오고, 최종 사용자 저장소를 새로 고치며, 지정된 간격으로 구성을 다시 로드합니다. 자동 새로 고침은 사용자 상태나 타겟팅 규칙이 변경될 수 있는 장기간 실행되는 세션에 유용합니다. 일반적인 사용 사례는 브라우저 환경보다 페이지가 덜 자주 다시 로드되는 데스크톱 애플리케이션입니다.

engagement.setAutoRefreshInterval(intervalSeconds?: number): void

// Set auto-refresh to every hour
window.engagement.setAutoRefreshInterval(3600);
// Set auto-refresh to every 30 minutes
window.engagement.setAutoRefreshInterval(1800);
// Disable auto-refresh
window.engagement.setAutoRefreshInterval(0);

또한 다음 autoRefreshIntervalSeconds옵션을 설정하여 부팅 다음 기간동안 자동 새로 고침을 활성화할 수 있습니다.

await window.engagement.boot({
  user: {
    user_id: "user123",
    device_id: "device456",
  },
  autoRefreshIntervalSeconds: 3600,
});

SDK 메서드 스타일 지정

테마 관리

앱이 밝은 모드와 어두운 모드를 지원하는 경우 시각적 테마 모드를 구성하십시오.

engagement.setThemeMode(mode: ThemeMode): void

// Automatically detect user's system preferences
window.engagement.setThemeMode("auto");
// Set dark mode explicitly
window.engagement.setThemeMode("darkMode");
// Set light mode explicitly
window.engagement.setThemeMode("lightMode");

계측 SDK 방법

전달 이벤트

타사 분석 이벤트를 가이드 및 설문조사 SDK로 전달하여 On 이벤트 추적 트리거를 사용하는 가이드 및 설문조사를 트리거하세요.

engagement.forwardEvent(event: Event): void

콜백 등록

가이드 및 설문조사 SDK를 사용하여 콜백을 등록하십시오. 가이드 또는 설문조사 버튼에 콜백 실행 동작을 설정하여 콜백을 실행합니다.

engagement.addCallback(name: string, callback: () => void): void

window.engagement.addCallback("toggle_dark_mode", () => {
  setTheme("darkMode");
  window.engagement.setThemeMode("darkMode");
});

라우터 구성

가이드 및 설문조사가 단일 페이지 애플리케이션(SPA)에서 URL을 처리하는 방법을 구성합니다. 이렇게 하면 다시 로드하지 않고 URL 업데이트를 수행할 수 있습니다.

engagement.setRouter(routerFn: (url: string) => void): void

// React Router v6 implementation
import { useNavigate } from "react-router-dom";
const MyComponent = () => {
  const navigate = useNavigate();
  React.useEffect(() => {
    window.engagement.setRouter((newUrl) => navigate(newUrl));
  }, []);
};

// Angular implementation
import { Component } from "@angular/core";
import { Router } from "@angular/router";
@Component({
  /* ... */
})
export class AppComponent {
  constructor(private router: Router) {
    window.engagement.setRouter((url: string) => {
      this.router.navigateByUrl(url);
    });
  }
}

Angular 앱의 경우 루트 AppComponent(또는 초기화기)에서 Router 서비스와 navigateByUrl을 함께 사용하십시오. 이 메서드는 setRouter예상되는 서명과 일치하는 (url: string) => void전체 URL 문자열을 허용합니다.

사용자 속성 설정

현재 세션의 사용자 속성을 설정합니다. 이러한 속성을 구문과 함께 가이드 및 설문조사 콘텐츠 내의 변수로 사용하십시오@{{ property.propertyName }}.

amplitude.identify()를 사용하여 사용자 속성을 공유하는 경우에는 _setUserProperties()을 사용할 필요가 없습니다.

engagement._setUserProperties(userProperties: Record<string, any>): void

예제

// Supply user properties manually through engagement SDK
const userProperties = { firstName: "john" };
engagement._setUserProperties(userProperties);
// For testing, view the current user properties
engagement._.user.user_properties;

세션 속성 설정

현재 세션의 세션 속성을 설정합니다. 세션 속성은 가이드 및 설문조사가 트리거되는 시기를 제한하는 또 다른 방법을 제공합니다. 트리거 시점에 가이드 또는 설문조사는 구성된 세션 속성 조건이 일치하는 경우에만 표시됩니다.

세션 속성이 변경되면 SDK는 표시할 수 있는 가이드나 설문조사를 확인합니다. 세션 속성은 "즉시" 트리거와 함께 작동하며 세션 속성 조건이 참이 되는 즉시 콘텐츠를 표시합니다.

engagement.setSessionProperty(key: string, value: any): void

예제

// Various session properties to control guide/survey targeting
window.engagement.setSessionProperty("subscriptionTier", "premium");
window.engagement.setSessionProperty("isFeatureXEnabled", true);
window.engagement.setSessionProperty("userScore", 85);

가이드 및 설문조사 관리 SDK 방법

보기

특정 가이드 또는 설문조사를 표시합니다. SDK는 페이지 타겟팅을 제외한 전체 타겟팅 규칙과 제한을 무시합니다. 버튼의 onclick 핸들러에서 등의 요청 시 안내서나 설문조사를 표시하는 데 show사용합니다.

engagement.gs.show(key: string, stepIndex?: number): void

예: 버튼 클릭 시 표시

빌더에서 가이드 또는 설문조사 트리거를 없음으로 설정한 다음, 사용자가 해당 경험을 선택할 때 버튼의 onclick 핸들러에서 show를 호출하여 경험을 엽니다.

<button onclick="window.engagement.gs.show('my-guide-key')">Open guide</button>

모두 닫기

모든 활성 가이드 및 설문조사를 닫습니다.

engagement.gs.closeAll(): void

재설정

안내서 또는 설문조사를 특정 단계로 재설정합니다.

engagement.gs.reset(key: string, stepIndex?: number)

목록

모든 라이브 가이드 및 설문조사의 목록과 해당 상태를 검색합니다.

engagement.gs.list(): Array<GuideOrSurvey>

interface GuideOrSuvey {
  id: number;
  status: "visible" | "active";
  step: number;
  title: string
}

리소스 센터 SDK 메서드

응용 프로그램 코드에서 리소스 센터 위젯을 제어하십시오. 이러한 메서드는 기본 SDK 인스턴스(window.engagement)에서만 작동합니다.

리소스 센터를 엽니다.

리소스 센터 위젯을 엽니다. 필요한 경우 특정 문서에서 직접 엽니다.

engagement.rc.open(options?: { url?: string }): void

// Open the Resource Center
window.engagement.rc.open();
// Open the Resource Center directly on a specific article
window.engagement.rc.open({
  url: "https://help.example.com/articles/getting-started",
});

리소스 센터 닫기

리소스 센터 위젯을 닫습니다.

engagement.rc.close(): void

리소스 센터 전환

리소스 센터 위젯을 열기와 닫기 대상 구간에서 전환합니다.

engagement.rc.toggle(): void

지속된 상태 지우기

리소스 센터는 열려 있거나 최소화된 상태, 검색 쿼리, 브라우저에서 마지막으로 본 페이지와 같은 상태를 저장합니다. 이 불러오기 상태를 제거하려면 호출하십시오. 그러면 다음 페이지 로드 시 리소스 센터가 새롭게 시작됩니다clearState.

engagement.rc.clearState(): void

태그별로 콘텐츠 필터링

리소스 센터 콘텐츠를 태그별로 제한하도록 필터를 설정합니다. 이 필터는 리소스 센터 검색 결과 및 오토파일럿 개인화 추천에 적용됩니다.

engagement.setResourceCenterFilter(filter: TagFilter | null): void

TagFilter이 유형은 중첩된 AND/OR 논리를 지원합니다.

type TagFilter =
  | { tags: string[] }
  | { and: TagFilter[] }
  | { or: TagFilter[] };

// Filter to content tagged "billing" or "payments"
window.engagement.setResourceCenterFilter({
  tags: ["billing", "payments"],
});
// Complex filter with AND/OR logic
window.engagement.setResourceCenterFilter({
  and: [{ tags: ["billing", "payments"] }, { tags: ["enterprise"] }],
});
// Clear the filter
window.engagement.setResourceCenterFilter(null);

여러 SDK 인스턴스

동일한 페이지에서 여러 개의 격리된 가이드 및 설문조사 SDK 인스턴스를 실행하세요. 단일 페이지가 둘 이상의 Amplitude 프로젝트에서 콘텐츠를 로드해야 할 때 이 옵션을 사용하십시오. 예를 들어 자체 가이드 및 설문조사와 함께 테넌트별 경험을 포함하는 호스트 애플리케이션이 있습니다.

각 명명된 인스턴스는 고유한 API 키, 구성, 타겟팅 데이터, 최종 사용자 상태 및 분석 라우팅을 갖습니다. 기본 인스턴스인 window.engagement는 변경되지 않고 계속 작동하며 이전 버전과도 호환됩니다.

격리 작동 방식

각 명명된 인스턴스는 다음을 자체적으로 유지합니다:

• 인스턴스의 API 키를 사용하여 가져온 구성 및 타겟팅(결정) 데이터입니다.
• Valtio 스토어 및 최종 사용자 스토어.
• 가이드 및 설문조사를 렌더링하기 위한 DOM 컨테이너입니다.
• 분석 연동 라우팅을 통해 이벤트가 인스턴스 간에 유출되지 않습니다.
• 스타일 지정 및 테마 변수.
• localStorage 키는 API 키에 의해 범위가 지정됩니다.

모든 인스턴스는 페이지의 단일 #engagement-wrapper 요소를 공유합니다. 기본 인스턴스는 #engagement-container로 렌더링됩니다. 각 명명된 인스턴스는 #engagement-container-{instanceName}로 렌더링됩니다.

제한 사항

• 독립형 설치 필요: SDK 번들을 로드한 후 createInstance로 명명된 인스턴스를 생성하십시오. Amplitude Browser SDK 2 플러그인 및 Amplitude Browser 통합 SDK 경로는 기본 인스턴스만 관리합니다.
• 먼저 기본 인스턴스가 필요합니다. createInstance를 호출하기 전에 기본 인스턴스(window.engagement)를 생성하고 부트하십시오. 기본 인스턴스는 createInstance를 노출시킵니다.
• 가이드 및 설문조사에만 해당: 명명된 인스턴스는 가이드(체크리스트 포함)와 설문조사를 지원합니다. 리소스 센터 및 도우미는 기본 인스턴스에서만 지원됩니다.
• 고유한 인스턴스 이름: 각 명명된 인스턴스는 고유한 instanceName를 가져야 합니다. 기존 이름으로 인스턴스를 생성하면 이전 이름을 덮어쓰고 경고가 기록됩니다.
• 독립적 타겟팅: 각 인스턴스는 자체 타겟팅 데이터를 가져오고 트리거를 독립적으로 평가합니다. 다단계 투어는 인스턴스 간에 조정할 수 없습니다.
• 독립적인 사용자 ID: 각 인스턴스는 자체적으로 최종 사용자 상태를 관리합니다. 인스턴스가 사용자를 공유하도록 하려면 각 boot 호출에 동일한 user_id 또는 device_id 을 전달하십시오.

인스턴스 생성

기본 SDK에서 createInstance 을 호출하여 명명된 인스턴스를 추가로 생성합니다. 이 메서드는 새 인스턴스로 해석되는 Promise 을 반환합니다. 반환된 인스턴스에서 boot 을 호출하여 사용자를 식별하고 인스턴스를 활성화합니다.

window.engagement.createInstance(instanceName: string, apiKey: string, options?: InitOptions): Promise<EngagementSDK>

예: 두 번째 인스턴스 생성 및 부트

const tenantB = await window.engagement.createInstance(
  "tenant-b",
  "API_KEY_FOR_TENANT_B",
  {
    serverZone: "US",
    locale: "fr",
  },
);
await tenantB.boot({
  user: {
    user_id: "user-456",
  },
  integrations: [
    {
      track: (event) => {
        amplitude.track(event.event_type, event.event_properties);
      },
    },
  ],
});

부팅 후, 기본 인스턴스에서와 마찬가지로 반환된 인스턴스에서 SDK 메서드를 호출하십시오.

tenantB.gs.show("tenant-b-onboarding");
tenantB.gs.closeAll();
tenantB.setThemeMode("darkMode");

기존 인스턴스 가져오기

기본 SDK를 호출하여 이전에 생성된 인스턴스를 이름별로 검색합니다getInstance. 인스턴스가 존재하지 않는 경우 undefined반환됩니다.

window.engagement.getInstance(instanceName?: string): EngagementSDK | undefined

const tenantB = window.engagement.getInstance("tenant-b");
if (tenantB) {
  tenantB.gs.show("tenant-b-welcome");
}

활성 인스턴스 나열

기본 SDK를 호출하여 기본값을 포함한 모든 활성 인스턴스의 이름을 가져옵니다listInstances.

window.engagement.listInstances(): string[]

// Returns something like ['$default', 'tenant-b']
const instanceNames = window.engagement.listInstances();

명명된 인스턴스 종료

명명된 인스턴스에서 shutdown를 호출하여 이를 중지하고 레지스트리에서 제거합니다. 종료 후 getInstance는 더 이상 인스턴스를 반환하지 않습니다. 기본 인스턴스에서 shutdown를 호출해도 레지스트리에서 제거되지는 않습니다.

const tenantB = window.engagement.getInstance("tenant-b");
tenantB?.shutdown();