브라우저 통합 SDK 시작하기

npmv1.2.3121.0 kB gzip
For web developers10 분Beginner

이 가이드는 브라우저 통합 SDK(@amplitude/unified)를 설치하고, 한 번의 호출로 포함된 모든 제품을 초기화하며, 하나의 사용자 지정 이벤트를 Amplitude로 전송하는 데 도움을 줍니다. 전체 옵션 목록을 보려면 UnifiedOptions로 이동하십시오. 버전 간 변경 사항은 @amplitude/unified변경 로그로 이동하십시오.

통합 SDK는 브라우저 SDK 2(@amplitude/analytics-browser)를 세션 리플레이, 기능 실험, 가이드 및 설문조사와 함께 번들로 제공합니다. 모든 분석 메서드와 옵션은 브라우저 SDK 2에서와 동일하게 작동합니다. 분석만 필요한 경우 브라우저 SDK 2를 대신 설치하십시오. 동일한 페이지에 두 패키지를 모두 설치하지 마십시오. npm, Unified Script 및 Google Tag Manager를 비교하려면 브라우저 설치 선택으로 이동하십시오.

사전 조건

  • Amplitude 프로젝트 및 해당 API 키입니다. 키를 찾으려면 _설정 > 프로젝트_로 이동하여 프로젝트를 선택한 다음 _일반_을 엽니다.
  • 조직에서 사용하는 데이터 센터입니다: US(기본값) 또는 EU.
  • webpack, Vite 또는 esbuild 등의 JavaScript 번들러입니다. Unified SDK는 npm에서만 설치됩니다. 스크립트 태그의 경우 Unified Script를 사용하십시오.
  • 페이지가 http://또는 https://로 제공됩니다. file://에서 열린 페이지는 쿠키를 설정할 수 없으므로 SDK는 로드 시 ID를 유지할 수 없습니다.

SDK 설치

bash
npm install @amplitude/unified

그런 다음 패키지를 가져옵니다:

ts
import * as amplitude from "@amplitude/unified";

설치 문제 해결

SDK 초기화

가능한 initAll()한 빨리 한 번만 호출하십시오. 먼저 분석을 초기화한 다음 세션 리플레이, 기능 실험, 가이드 및 설문조사를 플러그인으로 추가합니다. SDK는 완료되기 전에 사용자가 수행한 모든 호출을 대기열에 넣고 initAll()이후에 실행합니다.

ts
amplitude.initAll("YOUR_API_KEY", {
  serverZone: "EU", // Omit for US projects.
  analytics: { autocapture: true },
  sessionReplay: { sampleRate: 1 }, // Records every session. Lower this before production.
});

내부가 serverZone아닌 최상위 수준에 설정하십시오.analytics 최상위 값을 설정하지 않은 경우initAll()에도 최상위 값이 모든 제품에 전달되어 제품별 값을 덮어씁니다.

세션 리플레이는 0위에서 설정하기 전까지 아무것도 기록하지 않습니다sessionReplay.sampleRate.

initAll() 는 사용자 ID 인수를 허용하지 않습니다. amplitude.setUserId()이후 호출하십시오.

초기화 문제 해결

쿠키나 자동 캡처 경고와 같은 분석 초기화 문제가 발생하는 경우 브라우저 SDK 2에서 초기화 문제 해결으로 이동하십시오.

첫 번째 이벤트 전송

하나의 사용자 지정 이벤트를 추적하고 업로드 결과를 기다립니다. promise은(는) 업로드 시도 후 해결되는 객체를 track()반환합니다.

ts
const result = await amplitude.track("Sign Up Clicked", {
  plan: "starter",
}).promise;
console.log(result.code, result.message);
// 200 "Event tracked successfully"

업로드 문제 해결

Unified SDK는 번들로 제공되는 Browser SDK 2를 통해 이벤트를 업로드하므로 결과 코드는 Browser SDK 2와 일치합니다. 모든 result.code 및 result.message에 대해 Browser SDK 2에서 업로드 문제 해결으로 이동하십시오.

Amplitude에서 이벤트 확인

  1. Amplitude에서 사용자 조회를 열고 amplitude.getDeviceId()에서 장치 ID를 검색합니다.
  2. 활동 탭을 열고 라이브 이벤트 업데이트를 켭니다.
  3. Sign Up Clicked이(가) plan속성과 함께 표시되는지 확인합니다.

1분 내에 이벤트가 나타나지 않으면 이벤트 확인을 따르십시오.

다음 단계

이 내용이 도움이 되었나요?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

이 페이지에서