브라우저 통합 SDK

Amplitude는 브라우저 SDK를 설치하는 여러 방법을 제공하며, 각 방법은 서로 다른 제품 지원 및 버전 제어 옵션을 제공합니다. 이 가이드에서는 세 가지 주요 설치 방법을 비교합니다.

수동 설정을 건너뛰려면 진폭 마법사 CLI를 사용하십시오. 이 도구는 코드베이스를 읽고, 추적 이벤트를 제안하며, 사용자의 승인을 받으면 SDK를 자동으로 계측합니다.

설치 방법을 선택하십시오.

Amplitude는 브라우저 SDK를 설치하는 세 가지 방법을 제공합니다.

메서드	설명	버전 관리	최적의 용도
통합 SDK(npm)	모든 Amplitude 기능을 갖춘 단일 npm 패키지	고객 관리	재현 가능한 빌드와 엄격한 변경 관리를 필요로 하는 팀
통합 스크립트(CDN)	Amplitude 기능을 로드하는 단일 스크립트 태그	Amplitude 관리	자동 업데이트 및 합리적인 기본값을 통한 빠른 설치
GTM 템플릿	구글 태그 관리자 템플릿	템플릿 버전 관리	태그 관리를 위해 GTM을 사용하는 팀

설치 방법별 제품 지원

각 설치 방법은 서로 다른 Amplitude 제품 세트를 지원합니다.

제품	통합 스크립트(CDN)	통합 SDK(npm)	GTM 템플릿
분석(`@amplitude/analytics-browser`)	✅ 포함됨	✅ 포함됨	✅ 포함됨
세션 리플레이	✅ 포함됨	✅ 포함됨	✅ 선택 사항(확인란)
가이드 및 설문조사	⚠ 별도의 스크립트	✅ 포함됨	✅ 선택 사항(확인란)
웹 실험(`@amplitude/experiment-tag`)	✅ 포함됨	❌ 포함되지 않음	❌ 지원되지 않음
기능 실험(`@amplitude/experiment-js-client`)	❌ 포함되지 않음	✅ 포함됨	❌ 지원되지 않음

웹 실험과 기능 실험 비교

웹 실험: 웹 페이지에서 코드 없는 A/B 테스트를 위해 시각적 편집을 사용합니다. 통합 스크립트에 자동으로 포함됩니다.
기능 실험: Experiment JavaScript SDK와 함께 코드 기반 기능 플래그를 사용합니다. 통합 npm 패키지에 포함되어 있습니다.

통합 SDK(npm)

통합 SDK는 단일 API를 통해 분석, 세션 리플레이, 기능 실험, 가이드 및 설문조사에 액세스할 수 있는 단일 npm 패키지(@amplitude/unified)를 제공합니다. npm 또는 yarn을 사용하여 IT 설치하고 package.json에서 버전을 제어합니다.

주요 특징:

버전을 완벽하게 제어할 수 있는 고객 관리 패키지 설치
기능 실험(코드 기반 기능 플래그)을 포함하며 웹 실험(시각적 편집기)은 포함하지 않습니다.
업그레이드하려면 종속성 파일에서 패키지 버전을 업데이트하십시오.
재현 가능한 빌드와 엄격한 변경 관리가 필요한 팀에게 적합합니다.

개별 제품 설치

번들 크기가 걱정되고 특정 제품만 필요한 경우 개별적으로 설치하십시오.

분석: 사용자 이벤트 및 행동을 추적하기 위한 기능입니다.
실험: A/B 테스트 및 기능 플래그를 실행하기 위한 것입니다.
세션 리플레이: 사용자 세션을 캡처하고 재생합니다.
가이드 및 설문조사: 제품 내 메시징 및 설문조사용입니다.

통합 SDK 설치

npm 또는 yarn을 사용하여 의존성을 설치하십시오.

bash

npm install @amplitude/unified

통합 SDK 초기화

통합 SDK는 모든 Amplitude 기능을 초기화하는 단일 초기화 방법을 제공합니다.

typescript

import { initAll } from "@amplitude/unified";
initAll("AMPLITUDE_API_KEY");

SDK 기능 액세스

통합 SDK는 단일 인터페이스를 통해 모든 Amplitude 기능에 액세스할 수 있도록 해줍니다.

기능 문서

각 제품의 기능 및 API에 대한 자세한 내용은 해당 문서를 참조하십시오.

typescript

import { track, identify, experiment, sessionReplay } from "@amplitude/unified";
// Track events
track("Button Clicked", { buttonName: "Sign Up" });
// Identify users
identify(new Identify().set("userType", "premium"));
// Access Experiment features
const variant = await experiment.fetch("experiment-key");
// Access Session Replay features
sessionReplay.flush();

구성

통합 SDK는 모든 Amplitude 기능에 대한 구성 옵션을 지원합니다. 각 제품을 개별적으로 구성하고 몇 가지 공통 옵션을 공유하십시오.

typescript

import { initAll } from "@amplitude/unified";
initAll("AMPLITUDE_API_KEY", {
  // Shared options for all SDKs (optional)
  serverZone: "US", // or 'EU'
  instanceName: "my-instance",
  // Analytics options
  analytics: {
    // Analytics configuration options
  },
  // Session Replay options
  sessionReplay: {
    // Session Replay configuration options
    sampleRate: 1, // To enable session replay
  },
  // Experiment options
  experiment: {
    // Experiment configuration options
  },
  // Guides and Surveys options
  engagement: {
    // Guides and Surveys configuration options
  },
});

공유 옵션

이름	유형	기본값	설명
`serverZone`	`'US'` 또는 `'EU'`	`'US'`	모든 SDK에 사용할 서버 영역입니다.
`instanceName`	`string`	`$default_instance`	이 SDK 인스턴스에 대한 고유 이름입니다.

분석 옵션

통합 브라우저 SDK는 @amplitude/analytics-browser의 모든 옵션을 지원합니다. 자세한 내용은 분석 Browser SDK 문서를 참조하십시오.

세션 리플레이 옵션

통합 브라우저 SDK는 @amplitude/plugin-session-replay-browser의 모든 옵션을 지원합니다. 자세한 내용은 세션 리플레이 플러그인 문서를 참조하십시오. 세션 리플레이를 활성화하려면 config.sessionReplay.sampleRate이 값을 0이 아닌 값으로 설정하십시오.

샘플 속도는 Amplitude가 세션 리플레이를 캡처하는 속도를 제어합니다. 예를 들어, config.sessionReplay.sampleRate을 0.5로 설정하면 세션 리플레이는 전체 세션의 약 절반을 캡처합니다.

실험 옵션

통합 브라우저 SDK는 @amplitude/plugin-experiment-browser의 모든 옵션을 지원합니다. 자세한 내용은 실험 문서를 참조하십시오.

가이드 및 설문조사 옵션

통합 브라우저 SDK는 모든 가이드 및 설문조사 옵션을 지원합니다. 참여 플러그인은 기본적으로 초기화됩니다.

가이드 및 설문조사 초기화 거부

가이드 및 설문조사는 기본적으로 @amplitude/unified에서 초기화됩니다. 가이드 및 설문조사를 사용하지 않고 참여 SDK가 로드되지 않도록 하려면 engagement 블록에 skip: true를 전달하십시오. 이렇게 하면 가이드 및 설문조사를 사용하지 않는 속성에 amplitude.engagement.*localStorage 항목이 입력되지 않습니다.

요구 사항: @amplitude/engagement-browser1.0.10 이상이 필요합니다.

typescript

initAll("AMPLITUDE_API_KEY", {
  // ... other options
  engagement: {
    skip: true,
  },
});

skip: true일 때, 참여 플러그인은 스토리지, 네트워크 또는 전체 가이드 및 설문조사 관련 사이드 이펙트를 설정하지 않고 즉시 반환합니다.

나중에 가이드를 활성화하려면 skip: true옵션을 제거하거나 false으로 설정한 다음 다시 초기화하십시오.

통합 스크립트(CDN)

통합 스크립트는 Amplitude의 CDN에서 Amplitude 브라우저 기능을 로드하는 단일 스크립트 태그입니다. Amplitude는 기본 SDK의 버전을 원격으로 제어하며, 합리적인 기본값과 선택 사항인 원격 또는 수동 구성을 통해 ‘단일 코드’ 환경을 제공합니다.

주요 특징:

Amplitude는 SDK 버전을 관리하며, 고객 릴리스를 요구하지 않고도 중앙에서 버그를 패치하거나 성능을 개선할 수 있습니다.
기본적으로 웹 실험(시각적 편집기)을 포함합니다.
세션 리플레이 및 웹 실험은 기본 설정으로 자동으로 활성화됩니다.
가이드 및 설문조사는 크기 문제로 인해 별도의 스크립트가 필요합니다.

통합 스크립트 설치

다음 스크립트 태그를 사이트의 <head>에 추가하십시오.

html

<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.js"></script>

AMPLITUDE_API_KEY을 프로젝트의 API 키로 대체하십시오.

통합 스크립트 초기화

통합 스크립트는 기본적으로 세션 리플레이 및 웹 실험을 활성화합니다. 수동 구성의 경우:

html

<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.js"></script>
<script>
  window.amplitude.init("AMPLITUDE_API_KEY", {
    defaultTracking: true,
    autocapture: true,
    fetchRemoteConfig: true,
  });
  // Enable Session Replay with custom sample rate
  window.amplitude.add(window.sessionReplay.plugin({ sampleRate: 1 }));
</script>

통합 스크립트에 가이드 및 설문조사 추가

크기 문제로 인해 가이드 및 설문조사는 별도의 스크립트가 필요합니다. 통합 스크립트 뒤에 추가하십시오.

html

<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.js"></script>
<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.engagement.js"></script>
<script>
  window.amplitude.add(window.engagement.plugin());
  window.amplitude.init("AMPLITUDE_API_KEY", {
    fetchRemoteConfig: true,
    autocapture: true,
  });
</script>

자세한 구성 옵션은 가이드 및 설문조사 SDK 문서를 참조하십시오.

구글 태그 관리자

Amplitude GTM 템플릿은 분석 브라우저 2.0 SDK(@amplitude/analytics-browser)를 직접 래핑합니다. 통합 SDK 또는 통합 스크립트를 사용하지 않습니다.

주요 특징:

템플릿 버전은 GTM을 통해 관리됩니다.
분석, 세션 리플레이, 가이드 및 설문조사를 지원합니다.
웹 실험 또는 기능 실험을 지원하지 않습니다.
세션 리플레이 및 가이드 및 설문조사는 기본적으로 비활성화되어 있으며 확인란을 수동으로 선택해야 합니다.

GTM에서 세션 리플레이와 가이드 및 설문조사 활성화

이러한 기능을 활성화하려면 다음을 수행하십시오.

GTM에서 Amplitude 태그로 이동하세요.
태그 구성에서 세션 리플레이 확인란을 선택하여 세션 리플레이를 활성화합니다.
제품 내 메시징을 활성화하려면 가이드 및 설문조사 확인란을 선택합니다.
변경 사항을 저장하고 게시합니다.

자세한 구성 옵션은 Google 태그 관리자 문서를 참조하십시오.

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