브라우저 통합 SDK 시작하기
이 가이드는 브라우저 통합 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 설치
npm install @amplitude/unified
그런 다음 패키지를 가져옵니다:
import * as amplitude from "@amplitude/unified";
설치 문제 해결
| 증상 | 원인 | 수정 |
|---|---|---|
amplitude.init is not a function | 통합 패키지는 init()를 내보내지 않습니다. | 대신 initAll()호출하십시오. |
| Amplitude 인스턴스 2개 또는 이벤트가 두 번 전송됨 | 또한 페이지에서 @amplitude/analytics-browser, 스크립트 로더 또는 Unified Script가 로드됩니다. | 페이지당 하나의 Amplitude 엔트리 포인트를 유지하십시오. |
| 번들 크기가 예상보다 더 증가했습니다. | 이 패키지에는 모든 제품이 포함되어 있으며 런타임에 CDN에서 가이드 및 설문조사 번들을 로드합니다. | 브라우저 SDK 2를 설치하고 필요한 제품만 추가하십시오. 브라우저 설치 선택으로 이동합니다. |
SDK 초기화
가능한 initAll()한 빨리 한 번만 호출하십시오. 먼저 분석을 초기화한 다음 세션 리플레이, 기능 실험, 가이드 및 설문조사를 플러그인으로 추가합니다. SDK는 완료되기 전에 사용자가 수행한 모든 호출을 대기열에 넣고 initAll()이후에 실행합니다.
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()이후 호출하십시오.
초기화 문제 해결
| 증상 | 원인 | 수정 |
|---|---|---|
EU 프로젝트이지만 이벤트가 미국 데이터 센터에 도달하거나 실패합니다. Invalid API key | serverZone: "EU" 는 안에 analytics있습니다. 설정되지 않은 최상위 수준은 serverZone 덮어씁니다. | initAll()옵션의 최상위 수준으로 이동합니다serverZone. |
콘솔 경고: Plugin with name @amplitude/unified-library-plugin already exists, skipping registration | initAll() 동일한 인스턴스에서 두 번째로 실행되었습니다. 두 번째 호출은 분석을 다시 초기화하고 모든 플러그인을 다시 시작합니다. | 페이지 로드당 initAll()한 번씩 호출합니다. |
로그: Session ... not being captured due to capture being disabled for project or because the remote config could not be fetched. | 프로젝트에 대해 세션 리플레이 캡처가 꺼져 있거나 API 키가 잘못되었습니다. | API 키 및 serverZone를 확인하고 프로젝트에 세션 리플레이가 설정되어 있는지 확인합니다. |
| 재생 및 캡처 로그 없음 | sessionReplay.sampleRate 0는 기본값입니다. | 위0에 sampleRate를 설정합니다. |
Angular 앱에서 클릭 또는 입력이 initAll()이후 작동하지 않습니다. | initAll() 브라우저 SDK 2의 init()를 호출하며, Zone.js는 자동 캡처가 패치하는 DOM API를 래핑합니다. | bootstrapApplication전에 main.ts또는 NgZone.runOutsideAngular()내initAll()에 호출하십시오. |
| 서버측 렌더링 중 오류 | initAll() 서버에서 실행됩니다(Next.js, Nuxt, SvelteKit, Remix). | 브라우저 코드에서initAll()만 호출합니다. Next.js 설치 가이드로 이동합니다. |
쿠키나 자동 캡처 경고와 같은 분석 초기화 문제가 발생하는 경우 브라우저 SDK 2에서 초기화 문제 해결으로 이동하십시오.
첫 번째 이벤트 전송
하나의 사용자 지정 이벤트를 추적하고 업로드 결과를 기다립니다. promise은(는) 업로드 시도 후 해결되는 객체를 track()반환합니다.
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에서 이벤트 확인
- Amplitude에서 사용자 조회를 열고
amplitude.getDeviceId()에서 장치 ID를 검색합니다. - 활동 탭을 열고 라이브 이벤트 업데이트를 켭니다.
Sign Up Clicked이(가)plan속성과 함께 표시되는지 확인합니다.
1분 내에 이벤트가 나타나지 않으면 이벤트 확인을 따르십시오.
다음 단계
- 공유 및 제품별 옵션을 설정합니다. 각 제품 구성으로 이동합니다.
- 플래그를 가져오고 변형을 읽습니다. 기능 실험 사용으로 이동합니다.
- 가이드 및 설문조사를 사용하지 않는 경우 끄십시오. 가이드 및 설문조사 끄기로 이동합니다.
- 사용자 지정 이벤트를 추적하고, 사용자를 식별하며, 이벤트 자동 캡처를 선택합니다. 기기로 이동하여 Browser SDK 2를 구성합니다.
이 내용이 도움이 되었나요?
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.