Browser SDK 2 시작하기
이 가이드는 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에 직접 또는 태그 관리자를 통해 태그를 추가하는 경우 스크립트 로더를 사용하십시오.
npm install @amplitude/analytics-browser
import * as amplitude from "@amplitude/analytics-browser";
대신 통합 SDK를 사용하려면 @amplitude/unified을(를) npm install @amplitude/unified 또는 yarn add @amplitude/unified으로 설치하고, 동일한 방식으로 가져옵니다:
import * as amplitude from "@amplitude/unified";
통합 패키지는 track()및 setUserId()와 같은 동일한 추적 및 ID 메서드를 내보내지만 init()는 내보내지 않습니다. 대신 initAll()함수를 호출하고 이 가이드의 분석 옵션을 아래에 전달합니다analytics.
amplitude.initAll("YOUR_API_KEY", {
serverZone: "EU", // Omit for US projects.
analytics: { autocapture: true },
});
initAll() 는 사용자 ID 인수를 허용하지 않습니다. 그 후setUserId()에 호출하십시오.
설치 문제 해결
| 증상 | 원인 | 수정 |
|---|---|---|
amplitude is not defined 콘솔에서(스크립트 로더) | 스니펫은 코드가 실행된 후 로드되거나 콘텐츠 보안 정책으로 인해 차단됩니다. | amplitude를 호출하는 코드 앞에 스니펫을 배치합니다. https://*.amplitude.com을 script-src에 추가하십시오. |
net::ERR_BLOCKED_BY_CLIENT SDK 스크립트용 | 광고 차단기 또는 개인정보 보호 확장 프로그램은 CDN을 차단합니다. | npm에서 설치하고 SDK를 코드와 함께 번들로 구성하거나, 확장 프로그램 없이 프로필에서 테스트하십시오. |
전역 변수 두 amplitude 개의 또는 이벤트가 두 번 전송됨 | 페이지에서 이 스니펫과 통합 스크립트 또는 @amplitude/unified가 모두 로드됩니다. | 페이지당 하나의 Amplitude 엔트리 포인트를 유지하십시오. |
SDK 초기화
앱에 알려진 사용자 ID 등의 필요한 컨텍스트가 있는 경우 빨리 init()한 번 호출하십시오. 초기화가 완료되기 전에 init()만든 호출은 대기열에서 대기하며 완료된 후 순서대로 실행됩니다.
amplitude.init("YOUR_API_KEY", {
autocapture: true,
});
이미 알고 있는 경우 사용자 ID를 두 번째 인수로 전달하십시오:
amplitude.init("YOUR_API_KEY", "user-12345", {
autocapture: true,
});
프로젝트에서 EU 데이터 센터를 사용하는 경우 serverZone를 설정합니다.
amplitude.init("YOUR_API_KEY", {
serverZone: "EU",
autocapture: true,
});
autocapture: true요소 클릭, 사용자 불편 신호, 실패한 네트워크 요청 및 웹 바이털을 포함하여 SDK가 불리언으로 활성화하는 모든 자동 캡처 기능을 켭니다. 기본 설정(페이지 보기, 세션, 속성, 양식 및 파일 다운로드)만 사용하여 시작하려면 객체를 생략하거나 autocapture전달하십시오. 선택 사항을 보려면 자동 캡처로 이동합니다.
초기화 문제 해결
| 증상 | 원인 | 수정 |
|---|---|---|
콘솔 경고: `options.defaultTracking` is set to undefined | 설정하지 않았거나 defaultTracking사용되지 않는 autocapture설정을 지정하지 않았습니다. | 오류가 아닙니다. 이를 비활성화하려면 autocapture명시적으로 설정하십시오. |
| 서버측 렌더링 중 오류가 발생하거나 서버 렌더링된 페이지에 이벤트가 없습니다. | init() 서버에서 실행됩니다(Next.js, Nuxt, SvelteKit, Remix). | 브라우저 init()코드에서만 호출하며, 예를 들어 클라이언트 구성 요소 또는 useEffect에서만 호출합니다. Next.js 설치 가이드로 이동합니다. |
Angular 앱에서 특정 작업 init()이후 클릭 또는 입력이 작동하지 않습니다. | Zone.js는 자동 캡처가 패치하는 DOM API를 감싸줍니다. | init()을(를) main.ts에서 bootstrapApplication전 또는 NgZone.runOutsideAngular() 내부에서 호출하십시오. |
| Chrome 확장 프로그램에는 페이지 뷰, 세션 또는 어트리뷰션이 없습니다. | Chrome 확장 프로그램에서 각 기능을 활성화하지 않는 한 SDK는 기본 자동 캡처를 끕니다. 이 기본값은 2.42.1에서 변경되었습니다. | 각 기능을 명시적으로 설정합니다(예: autocapture: { pageViews: true, sessions: true }). |
| 모든 페이지 로드 시 Identity 재설정 | 브라우저는 쿠키(비공개 모드, 엄격한 추적 보호 또는 샌드박스 iframe)를 차단하거나 페이지가 file://에서 실행됩니다. | HTTP(S)를 통해 페이지를 제공합니다. 쿠키가 차단된 상태로 유지되는 경우 identityStorage: "localStorage"를 설정하십시오. |
이벤트가 잘못된 지역으로 이동하거나 수집이 반환됩니다. Invalid API key | serverZone 는 프로젝트의 데이터 센터와 일치하지 않습니다. | EU 프로젝트에 대해 serverZone: "EU"설정합니다. 미국 프로젝트의 경우 생략하십시오. |
첫 번째 이벤트 전송
하나의 사용자 지정 이벤트를 추적하고 업로드 결과를 기다립니다. SDK가 업로드 시도를 완료한 후 해결되는 객체를 promise반환합니다.track()
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예상됩니다.
업로드 문제 해결
result.code 그리고 result.message | 원인 | 수정 |
|---|---|---|
0, Event skipped due to optOut config | 이 브라우저에 대해 옵트아웃이 설정되어 있습니다. SDK는 옵트아웃을 쿠키에 저장하므로 로드 전체에 걸쳐 유지됩니다. | amplitude.setOptOut(false)를 호출하거나 도메인의 AMP_쿠키를 지웁니다. |
0, Event skipped due to empty event type | 이벤트 이름이 비어 있거나 문자열이 아닙니다. | 첫 번째 인수로 비어 있지 않은 문자열을 전달하세요. |
400, Event rejected due to missing API key | init() 빈 API 키를 받았습니다. | 키를 보유하는 변수를 확인하십시오. 빌드 도구는 종종 환경 변수가 누락된 경우 빈 값을 인라인합니다. |
400, Invalid API key: ... | 키가 잘못되었거나 다른 데이터 센터의 프로젝트에 속해 있습니다. | 키를 다시 복사하고 serverZone를 확인합니다. |
500, 약 10초 후Event rejected due to exceeded retry count | 요청은 Amplitude에 도달하지 않았으며, SDK는 5번의 시도 후 포기했습니다. 광고 차단기, 콘텐츠 보안 정책, 프록시의 CORS 또는 서버 오류로 인해 발생합니다. | 브라우저의 네트워크 탭을 열고 요청을 확인하십시오api2.amplitude.com(또는 api.eu.amplitude.com). https://*.amplitude.com을 connect-src에 추가하십시오. 광고 차단기가 요청을 차단하는 경우 프록시를 통해 트래픽을 라우팅하십시오. |
| promise는 절대로 해결되지 않습니다. | init()이 인스턴스에서 실행된 적이 없으므로 호출은 여전히 대기열에 있습니다. | 동일한 인스턴스의 호출 전이나 후에 실행되도록 하고, 이를 건너뛰는 브랜치 내부에 있지 않은지 init()확인하십시오. |
이 이벤트는 페이지가 바로 이동한 직후에 사라집니다.track() | 페이지가 언로드될 때 브라우저가 요청을 취소했습니다. | keepalive로 전송하는 기본 fetch 전송을 유지합니다. 대규모 페이로드의 경우 페이지가 언로드될 때 이벤트 보내기로 이동하십시오. |
Amplitude에서 이벤트 확인
- Amplitude에서 사용자 조회를 열고 전달한 사용자 ID 또는
amplitude.getDeviceId()에서 장치 ID를 검색합니다. - 활동 탭을 열고 라이브 이벤트 업데이트를 설정합니다.
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.