Browser SDK 2 시작하기

npmv2.49.366.1 kB gzip
For web developers10분Beginner

이 가이드는 Browser SDK 2를 설치하고, 초기화한 다음 하나의 사용자 지정 이벤트를 Amplitude로 전송하는 데 도움을 줍니다.@amplitude/analytics-browser 각 단계에는 해당 단계를 일반적으로 방해하는 브라우저 조건이 나열되므로 문제가 발생하는 곳에서 해결할 수 있습니다. 전체 옵션 목록을 보려면 구성 옵션으로 이동하십시오.

Browser SDK 2는 분석 전용 패키지입니다. 세션 리플레이, 기능 실험 또는 가이드 및 설문조사도 필요한 경우, 대신 브라우저 통합 SDK를 @amplitude/unified설치하십시오. Browser SDK 2가 포함되어 있으므로 동일한 페이지에 두 패키지를 모두 설치하지 마십시오.

사전 조건

  • Amplitude 프로젝트 및 해당 API 키입니다. 설정 > 프로젝트 > 프로젝트 > 일반에서 키를 찾습니다.
  • 조직에서 사용하는 데이터 센터입니다: US(기본값) 또는 EU.
  • 최신 Browser SDK 2 릴리즈 또는 사용 중인 기능에 대해 Browser SDK 2 릴리즈 노트를 확인한 고정 버전입니다.
  • 페이지가 http://또는 https://로 제공됩니다. file://에서 열린 페이지는 쿠키를 설정할 수 없으므로 SDK는 로드 시 ID를 유지할 수 없습니다.

SDK 설치

하나의 설치 방법을 선택합니다. JavaScript를 번들로 구성하는 경우 npm 또는 yarn을 사용하십시오. HTML에 직접 또는 태그 관리자를 통해 태그를 추가하는 경우 스크립트 로더를 사용하십시오.

bash
npm install @amplitude/analytics-browser
ts
import * as amplitude from "@amplitude/analytics-browser";

대신 통합 SDK를 사용하려면 @amplitude/unified을(를) npm install @amplitude/unified 또는 yarn add @amplitude/unified으로 설치하고, 동일한 방식으로 가져옵니다:

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

통합 패키지는 track()및 setUserId()와 같은 동일한 추적 및 ID 메서드를 내보내지만 init()는 내보내지 않습니다. 대신 initAll()함수를 호출하고 이 가이드의 분석 옵션을 아래에 전달합니다analytics.

ts
amplitude.initAll("YOUR_API_KEY", {
  serverZone: "EU", // Omit for US projects.
  analytics: { autocapture: true },
});

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

설치 문제 해결

SDK 초기화

앱에 알려진 사용자 ID 등의 필요한 컨텍스트가 있는 경우 빨리 init()한 번 호출하십시오. 초기화가 완료되기 전에 init()만든 호출은 대기열에서 대기하며 완료된 후 순서대로 실행됩니다.

ts
amplitude.init("YOUR_API_KEY", {
  autocapture: true,
});

이미 알고 있는 경우 사용자 ID를 두 번째 인수로 전달하십시오:

ts
amplitude.init("YOUR_API_KEY", "user-12345", {
  autocapture: true,
});

프로젝트에서 EU 데이터 센터를 사용하는 경우 serverZone를 설정합니다.

ts
amplitude.init("YOUR_API_KEY", {
  serverZone: "EU",
  autocapture: true,
});

autocapture: true요소 클릭, 사용자 불편 신호, 실패한 네트워크 요청 및 웹 바이털을 포함하여 SDK가 불리언으로 활성화하는 모든 자동 캡처 기능을 켭니다. 기본 설정(페이지 보기, 세션, 속성, 양식 및 파일 다운로드)만 사용하여 시작하려면 객체를 생략하거나 autocapture전달하십시오. 선택 사항을 보려면 자동 캡처로 이동합니다.

초기화 문제 해결

첫 번째 이벤트 전송

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

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

SDK는 첫 번째 이벤트가 큐에 들어온 후 약 1초 후에 최대 30개의 이벤트로 구성된 요청으로 대기열의 이벤트를 업로드합니다. 해당 업로드 후에 해결되므로 약 1초의 지연이 발생할 것으로 promise예상됩니다.

업로드 문제 해결

Amplitude에서 이벤트 확인

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

1분 내에 이벤트가 나타나지 않으면 이벤트 확인을 따르십시오. track()Amplitude 서버 간의 각 단계를 거쳐 이동합니다.

다음 단계

  • 로그인한 사용자를 식별하고setUserId(), 로그아웃 시 호출하십시오reset().
  • 보관할 자동 캡처 이벤트를 선택합니다.
  • 트래킹 플랜에 필요한 사용자 지정 이벤트와 속성을 추가합니다. 이벤트 추적으로 이동합니다.

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

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.

이 페이지에서