브라우저 SDK 1

브라우저 SDK를 사용하면 Amplitude로 이벤트를 전송할 수 있습니다.

SDK 초기화

어떤 이벤트든 계측하기 전에 SDK를 초기화하십시오. Amplitude 프로젝트의 API 키가 필요합니다. 이 호출에서 선택적 사용자 ID 및 구성 객체를 전달할 수 있습니다. 초기화 후에는 애플리케이션의 어디에서나 SDK를 사용할 수 있습니다.

// Option 1, initialize with API_KEY only
amplitude.init(API_KEY);
// Option 2, initialize with user ID if it's already known
amplitude.init(API_KEY, "user@amplitude.com");
// Option 3, initialize with configuration
amplitude.init(API_KEY, "user@amplitude.com", options);

SDK 구성

기본 구성 옵션과 함께 기여 분석을 구성할 수 있습니다.

일괄 처리 동작 구성

고성능 환경을 지원하기 위해 SDK는 이벤트를 일괄 처리로 전송합니다. 이 track 메소드는 기록된 모든 이벤트를 메모리 대기열에 넣습니다. SDK는 백그라운드에서 이벤트를 일괄적으로 플러시합니다.flushQueueSize 및 flushIntervalMillis을 사용하여 일괄 처리 동작을 사용자 지정할 수 있습니다. 기본적으로 serverUrl은 https://api2.amplitude.com/2/httpapi입니다. 한 번에 대량의 데이터를 전송하려면 useBatch를 true로 설정하여 setServerUrl을 배치 이벤트 업로드 API인 https://api2.amplitude.com/batch로 설정하십시오. 일반 모드와 배치 모드 모두 동일한 이벤트 업로드 임계값과 플러시 시간 간격을 사용합니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  // Events queued in memory will flush when number of events exceed upload threshold
  // Default value is 30
  flushQueueSize: 50,
  // Events queue will flush every certain milliseconds based on setting
  // Default value is 10000 milliseconds
  flushIntervalMillis: 20000,
  // Using batch mode with batch API endpoint, `https://api2.amplitude.com/batch`
  useBatch: true,
});

EU 데이터 상주

Amplitude의 EU 서버로 데이터를 전송하기 위해 클라이언트를 초기화할 때 서버 영역을 구성하십시오. SDK는 서버 영역이 설정되어 있는 경우 이를 기반으로 데이터를 전송합니다.

에서 프로젝트를 생성하고 Amplitude EU의 API 키를 사용하십시오.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  serverZone: "EU",
});

디버깅

다음 logLevel 설정을 사용하여 SDK가 콘솔에 출력하는 로그 수준을 제어하십시오.

logLevel 매개변수를 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  logLevel: amplitude.Types.LogLevel.Warn,
});

기본 로거는 개발자 콘솔에 로그를 출력합니다. 사용자 정의를 위해 Logger인터페이스를 기반으로 자체 로거 구현을 제공할 수 있습니다. 예를 들어 프로덕션 환경에서 SDK로부터 전체 오류 메시지를 수집하는 작업입니다.

loggerProvider를 자체 구현으로 구성하여 로거를 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  loggerProvider: new MyLogger(),
});

디버그 모드

logLevel를 "디버그"로 설정하여 디버그 모드를 활성화하십시오. 예를 들면 다음과 같습니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  logLevel: amplitude.Types.LogLevel.Debug,
});

기본 로거를 사용하면 SDK는 사용자가 전체 SDK 공용 메서드를 호출할 때 다음과 같은 추가 함수 컨텍스트 정보를 개발자 콘솔에 출력합니다.

• type: 이 컨텍스트의 범주입니다. 예를 들어 "공용 메소드 호출".
• name: 호출된 함수의 이름입니다(예: "track").
• args: 호출된 함수의 인수입니다.
• stacktrace: 호출된 함수의 스택트레이스입니다.
• time: 함수 호출의 시작 및 종료 타임스탬프입니다.
• states: 함수 호출 전후의 유용한 내부 상태 스냅샷입니다.

이벤트 추적

이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어 ‘버튼 클릭’은 추적하려는 동작일 수 있습니다.

// Track a basic event
amplitude.track("Button Clicked");
// Track events with optional properties
const eventProperties = {
  buttonColor: "primary",
};
amplitude.track("Button Clicked", eventProperties);

BaseEvent 객체를 track에 전달할 수도 있습니다. 사용 가능한 모든 필드에 대한 자세한 내용은 BaseEvent 인터페이스를 참조하십시오.

const event_properties = {
  buttonColor: "primary",
};
const event = {
  event_type: "Button Clicked",
  event_properties,
  groups: { role: "engineering" },
  group_properties: { groupPropertyKey: "groupPropertyValue" },
};
amplitude.track(event);

여러 프로젝트에 대한 이벤트 추적

기본적으로 Amplitude SDK는 데이터를 하나의 Amplitude 프로젝트로 전송합니다. 데이터를 둘 이상의 프로젝트에 전송하려면 데이터를 수신해야 하는 각 프로젝트에 대해 Amplitude SDK의 인스턴스를 추가하십시오. 그런 다음 Amplitude를 호출하는 모든 위치에 인스턴스 변수를 전달합니다. 각 인스턴스는 독립적인 apiKey, userId, deviceId, 및 settings값을 지원합니다.

const defaultInstance = amplitude.createInstance();
defaultInstance.init(API_KEY_DEFAULT);
const envInstance = amplitude.createInstance();
envInstance.init(API_KEY_ENV, {
  instanceName: "env",
});

기본 이벤트 추적

SDK 버전 1.9.1부터 브라우저 SDK는 기본 이벤트를 추적하고 기본 이벤트 수집을 제어하기 위한 구성을 추가합니다. 브라우저 SDK는 다음과 같은 기본 이벤트를 추적합니다.

• 페이지 뷰 수.

• 세션.

• 양식 상호작용.

• 파일 다운로드.

• config.defaultTracking.pageViews

  • 값: 선택 사항입니다. boolean.
  • 설명:
    • 기본 페이지 보기 추적을 활성화합니다. 값이 true인 경우 Amplitude는 초기화 시 페이지 보기 이벤트를 추적합니다. 기본값은 false입니다.
    • 추적되는 이벤트 속성에는 [Amplitude] Page Domain, [Amplitude] Page Location, [Amplitude] Page Path, [Amplitude] Page Title, [Amplitude] Page URL이 포함됩니다.
    • 자세한 내용은 페이지 뷰 추적을 참조하십시오.

• config.defaultTracking.sessions

  • 값: 선택 사항입니다. boolean.
  • 설명:
    • 세션 추적을 활성화합니다. 값이 true인 경우 Amplitude는 세션 시작 및 세션 종료 이벤트를 추적합니다. 기본값은 false입니다.
    • 자세한 내용은 세션 추적을 참조하십시오.

• config.defaultTracking.formInteractions

  • 값: 선택 사항입니다. boolean.
  • 설명:
    • 양식 상호 작용 추적을 활성화합니다. 값이 true인 경우 Amplitude는 양식 시작 및 양식 제출 이벤트를 추적합니다. 기본값은 false입니다.
    • 추적된 이벤트 속성에는 [Amplitude] Form ID, [Amplitude] Form Name, [Amplitude] Form Destination이 포함됩니다.
    • 자세한 내용은 양식 상호 작용 추적을 참조하십시오.

• config.defaultTracking.fileDownloads

  • 값: 선택 사항입니다. boolean.
  • 설명:
    • 파일 다운로드 추적을 활성화합니다. 값이 true인 경우 Amplitude는 파일 다운로드 이벤트를 추적합니다. 기본값은 false입니다.
    • 추적되는 이벤트 속성에는 [Amplitude] File Extension, [Amplitude] File Name, [Amplitude] Link ID, [Amplitude] Link Text, [Amplitude] Link URL이 포함됩니다.
    • 자세한 내용은 파일 다운로드 추적을 참조하십시오.

다음 코드 샘플을 사용하여 모든 기본 이벤트를 추적하십시오. 또는 기본 이벤트를 비활성화한 상태로 유지하려면 구성을 생략하십시오.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    pageViews: true,
    sessions: true,
    formInteractions: true,
    fileDownloads: true,
  },
});

모든 기본 이벤트를 추적하려면 true로 설정할 수도 있습니다. config.defaultTracking이 설정을 통해 SDK는 Amplitude가 추가할 수 있는 전체 새로운 기본 이벤트를 추적할 수 있습니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: true,
});

페이지 뷰 추적

true로 설정하면 Amplitude는 기본 페이지 뷰 추적 동작을 사용합니다. config.defaultTracking.pageViews이 설정은 초기화 시 페이지 보기 이벤트를 전송하며, 이 이벤트는 Amplitude에 [Amplitude] Page Viewed로 표시됩니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    pageViews: true,
  },
});

페이지 뷰 추적을 위한 고급옵션 구성

고급옵션 구성을 사용하면 SDK가 페이지 보기 이벤트를 전송할 시기를 보다 효과적으로 제어할 수 있습니다.

• config.defaultTracking.pageViews.trackOn
  • 값: 선택 사항입니다. "attribution" 또는 () => boolean.
  • 설명:
    • SDK가 페이지 보기 이벤트를 추적할 때를 제어하는 고급옵션 기능을 제공합니다.
    • 초기화 시 페이지 보기 이벤트를 추적하려면 값을 생략하거나 undefined으로 설정하십시오.
    • Amplitude가 웹 속성을 추적할 때만 페이지 뷰 이벤트를 추적하려면 값을 "attribution"로 설정하십시오.
    • 이 값을 불리언(true 또는 false)을 반환하는 함수로 설정하여 기준에 따라 페이지 보기 이벤트를 추적합니다.
• config.defaultTracking.pageViews.trackHistoryChanges
  • 값: 선택 사항입니다. "pathOnly" 또는 "all".
  • 설명:
    • SDK가 페이지 뷰를 추적할 때 단일 페이지 애플리케이션에 대한 고급옵션 제어 기능을 제공합니다.
    • 단일 페이지 응용 프로그램 첫 사용 후 URL 전체 탐색 변경에 대한 페이지 보기 이벤트를 추적하려면 값을 생략하거나 "all"으로 설정하십시오. 예를 들어 https://amplitude.com/#company에서 https://amplitude.com/#blog 로 이동하는 경우를 예로 들 수 있습니다.
    • 단일 페이지 응용 프로그램 첫 사용 후에서만 URL 경로 탐색 변경에 대한 페이지 보기 이벤트를 추적하려면 값을 "pathOnly"으로 설정하십시오. 예를 들어 https://amplitude.com/company에서 https://amplitude.com/blog 로 이동하는 경우를 예로 들 수 있습니다.
• config.defaultTracking.pageViews.eventType
  • 값: 선택 사항입니다. string.
  • 설명: 페이지 보기 이벤트에 대해 event_type을 사용자 정의합니다.

예를 들어 URL 경로에 특정 하위 문자열(예: home)이 포함된 경우에만 페이지 뷰를 추적하도록 Amplitude를 구성할 수 있습니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    pageViews: {
      trackOn: () => {
        return window.location.pathname.includes("home");
      },
    },
  },
});

Amplitude는 페이지 보기 이벤트를 통해 다음과 같은 정보를 추적합니다.

페이지 보기 추적과 함께 더 많은 속성을 추가하는 것과 같은 기본 페이지 보기 이벤트를 강화하는 방법에 대한 예제는 이 예제를 참조하십시오.

세션 추적

Amplitude가 세션을 추적할 수 있도록 true를 config.defaultTracking.sessions로 설정합니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    sessions: true,
  },
});

세션은 사용자가 귀하의 웹사이트를 열어 놓은 상태의 기간입니다. 자세한 내용은 Amplitude가 세션을 정의하는 방법을 참조하십시오. 새 세션이 시작될 때, Amplitude는 세션 시작 이벤트를 세션의 첫 번째 이벤트로 추적합니다. 세션 시작에 대한 이벤트 유형은 [Amplitude] Start Session입니다. 기존 세션이 종료되면 Amplitude는 세션의 마지막 이벤트인 [Amplitude] End Sessions을 추적합니다.

양식 상호 작용 추적

Amplitude가 양식 상호 작용을 추적하도록true config.defaultTracking.formInteractions설정합니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    formInteractions: true,
  },
});

Amplitude는 사용자가 처음에 양식과 상호 작용할 때 [Amplitude] Form Started를 추적합니다. 초기 상호 작용은 텍스트 입력, 라디오 버튼 또는 드롭다운에 대한 첫 번째 변경일 수 있습니다.

Amplitude는 사용자가 양식을 제출할 때 [Amplitude] Form Submitted이를 추적합니다. 사용자가 양식 필드에 대해 초기 변경 사항이 없는 상태에서 양식을 제출하면 Amplitude는 [Amplitude] Form Started및 [Amplitude] Form Submitted 이벤트를 모두 전송합니다.

Amplitude는 태그와 중첩된 <input>태그로 작성된 <form>양식을 추적할 수 있습니다. 예를 들면 다음과 같습니다.

<form id="subscriber-form" name="subscriber-form" action="/subscribe">
  <input type="text" />
  <input type="submit" />
</form>

파일 다운로드 추적

Amplitude가 파일 다운로드를 추적하도록true config.defaultTracking.fileDownloads설정합니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    fileDownloads: true,
  },
});

Amplitude는 사용자가 파일에 링크된 앵커나 <a>태그를 클릭할 때 발생하는 파일 다운로드 이벤트를 추적합니다. 파일 다운로드에 대한 이벤트 유형은 [Amplitude] File Downloaded입니다. 파일 확장자가 다음 정규 표현식과 일치하는 경우 Amplitude는 앵커 또는 <a>태그가 파일에 링크되는지 확인합니다.

pdf|xlsx?|docx?|txt|rtf|csv|exe|key|pp(s|t|tx)|7z|pkg|rar|gz|zip|avi|mov|mp4|mpe?g|wmv|midi?|mp3|wav|wma

사용자 속성

사용자 속성은 기기 세부 정보, 사용자 환경설정, 언어와 같은 세부 정보로, 사용자가 앱에서 작업을 수행했을 때 이를 이해하는 데 도움을 줍니다.

Identify를 사용하여 이벤트를 전송하지 않고 특정 사용자의 사용자 속성을 설정합니다. SDK는 개별 사용자 속성에 대해 set, setOnce, unset, add, append, prepend, preInsert, postInsert 및 remove 작업을 지원합니다. 제공된 Identify 인터페이스를 통해 작업을 선언합니다. 단일 Identify 객체에서 여러 작업을 체인화할 수 있습니다. Identify 객체를 Amplitude 클라이언트에 전달하여 서버로 전송합니다.

사용자 속성 설정

Identify 객체는 사용자 속성 설정을 제어할 수 있는 기능을 제공합니다. 먼저 Identify 객체를 인스턴스화한 다음 이에 대해 Identify 메서드를 호출합니다. 마지막으로, 클라이언트는 Identify 객체를 사용하여 호출을 할 수 있습니다.

const identifyEvent = new amplitude.Identify();
amplitude.identify(identifyEvent);

Identify.set

이 메서드는 사용자 속성의 값을 설정합니다. 예를 들어 사용자의 역할 속성을 설정할 수 있습니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.set("location", "LAX");
amplitude.identify(identifyEvent);

Identify.setOnce

이 메서드는 사용자 속성의 값을 한 번만 설정합니다. SDK는 setOnce()를 사용한 후속 호출을 무시합니다. 예를 들어 사용자의 초기 로그인 방법을 설정할 수 있습니다. 초기 값만 추적되므로 에서는 이후 setOnce()호출을 무시합니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.setOnce("initial-location", "SFO");
identify(identifyEvent);

Identify.add

이 메서드는 사용자 속성을 일부 숫자 값만큼 증가시킵니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 속성을 0으로 초기화한 후 증가시킵니다. 예를 들어 사용자의 여행 수행 횟수를 추적할 수 있습니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.add("travel-count", 1);
amplitude.identify(identifyEvent);

사용자 속성의 배열

배열을 사용자 속성으로 사용할 수 있습니다. 배열을 직접 설정하거나 prepend, append, preInsert 및 postInsert를 사용하여 배열을 생성하십시오.

Identify.prepend

이 메서드는 사용자 속성 배열 앞에 값을 추가합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 앞에 추가하기 전에 속성을 빈 목록으로 초기화합니다.

const identifyEvent = new Identify();
identifyEvent.prepend("visited-locations", "LAX");
identify(identifyEvent);

Identify.append

이 메서드는 사용자 속성 배열에 하나 이상의 값을 추가합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 추가하기 전에 속성을 빈 목록으로 초기화합니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.append("visited-locations", "SFO");
amplitude.identify(identifyEvent);

Identify.preInsert

이 메서드는 사용자 속성에 값이 아직 존재하지 않는 경우 해당 값을 사용자 속성에 미리 삽입합니다. 사전 삽입은 지정된 목록의 시작 부분에 값을 삽입하는 것을 의미합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 미리 삽입하기 전에 속성을 빈 목록으로 초기화합니다. 사용자 속성에 기존 값이 있는 경우 이 메서드는 no-op입니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.preInsert("unique-locations", "LAX");
identify(identifyEvent);

Identify.postInsert

이 메서드는 사용자 속성에 값이 아직 존재하지 않는 경우 해당 값을 사용자 속성에 사후 삽입합니다. 사후 삽입은 주어진 목록의 끝에 값을 삽입하는 것을 의미합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 사후 삽입하기 전에 속성을 빈 목록으로 초기화합니다. 사용자 속성에 기존 값이 있는 경우 이 메서드는 no-op입니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.postInsert("unique-locations", "SFO");
amplitude.identify(identifyEvent);

Identify.remove

이 메서드는 사용자 속성에 값이 있는 경우 사용자 속성에서 해당 값을 제거합니다. 제거는 주어진 목록에서 기존 값을 제거한다는 것을 의미합니다. 사용자 속성에 기존 값이 없는 경우, 이 메소드는 아무 작업도 수행하지 않습니다.

const identifyEvent = new amplitude.Identify();
identifyEvent.remove("unique-locations", "JFK");
amplitude.identify(identifyEvent);

사용자 그룹

Amplitude는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 사용자별 수행 회수가와 같은 쿼리를 수행하는 것을 지원합니다. 그룹 구성원 중 적어도 한 명이 특정 이벤트를 수행한 경우 해당 그룹도 수행 회수가에 포함됩니다.

예를 들어 'orgId'를 사용하여 사용자가 속한 조직을 기준으로 사용자를 그룹화하려는 경우가 있습니다. Joe는 'orgId' '10'에 있고 Sue는 'orgId' '15'에 있습니다. Sue와 Joe는 둘 다 특정 이벤트를 수행합니다. 이벤트 세분화 차트에서 해당 조직을 쿼리할 수 있습니다.

그룹을 설정할 때 groupType 및 groupName를 정의하십시오. 이전 예제에서 'orgId'는 groupType이고 '10'과 '15'는 groupName에 대한 값입니다. a의 또 다른 예는 '테니스'나 '야구'와 같은 groupName값을 가진 '스포츠'일 수 있습니다groupType.

또한 그룹을 groupType:groupName설정하면 를 사용자 속성으로 설정하고 해당 groupType사용자와 해당 사용자 속성 값에 대해 설정된 groupName기존 값을 덮어씁니다. groupType은 groupName문자열이며 사용자가 여러 그룹에 속해 있음을 나타내는 문자열 또는 문자열 배열일 수 있습니다.

// set group with a single group name
amplitude.setGroup("orgId", "15");

// set group with multiple group names
amplitude.setGroup("sport", ["soccer", "tennis"]);

groups을 포함한 Event 객체를 track에 전달하여 이벤트 수준 그룹을 설정할 수도 있습니다. 이벤트 수준 그룹의 경우 그룹 지정은 기록된 특정 이벤트에만 적용되며 setGroup를 사용하여 명시적으로 이를 설정하지 않는 한 사용자에게 지속되지 않습니다.

amplitude.track({
  event_type: "event type",
  event_properties: { eventPropertyKey: "event property value" },
  groups: { orgId: "15" },
});

매출 추적

사용자의 수익을 추적하는 선호되는 방법은 제공된 revenue()수익 인터페이스와 함께 사용하는 것입니다. 수익 인스턴스는 각 수익 거래를 저장하며, Amplitude의 이벤트 세분화 및 LTV (Lifetime Value) 차트에서 사용하는 몇 가지 특별한 수익 속성(예: 'revenueType' 및 'productIdentifier')을 정의할 수 있도록 해줍니다. 이러한 Revenue 인스턴스 객체를 revenue()에 전달하여 Amplitude에 수익 이벤트로 전송하십시오. 이 방법은 플랫폼에 수익 관련 데이터를 자동으로 표시합니다. 이 방법을 사용하여 앱 내 구매와 앱 내 이외의 구매를 모두 추적하세요.

사용자의 수익을 추적하려면 사용자가 수익을 창출할 때마다 수익을 호출하십시오. 이 예제에서 사용자는 3.99달러에 제품 3개를 구입했습니다.

const event = new amplitude.Revenue()
  .setProductId("com.company.productId")
  .setPrice(3.99)
  .setQuantity(3);
amplitude.revenue(event);

수익 인터페이스

이벤트 버퍼 플러시

이 flush 메서드는 클라이언트가 버퍼링된 이벤트를 즉시 전송하도록 트리거합니다.

amplitude.flush();

기본적으로 SDK는 일정한 간격으로 자동으로 flush호출됩니다. 이벤트를 모두 플러시하려면 선택적 Promise 인터페이스를 사용하여 비동기 흐름을 제어합니다. 예를 들어:

amplitude.init(API_KEY).promise.then(function () {
  amplitude.track("Button Clicked");
  amplitude.flush();
});

사용자 지정 사용자 ID

앱에 사용자를 추적하려는 자체 로그인 시스템이 있는 경우 언제든지 setUserId를 호출할 수 있습니다.

amplitude.setUserId("user@amplitude.com");

또한 사용자 ID를 init 호출의 인수로 할당할 수도 있습니다.

amplitude.init(API_KEY, "user@amplitude.com");

사용자 지정 세션 ID

setSessionId를 사용하여 새 세션 ID를 할당할 수 있습니다. 사용자 지정 세션 ID를 설정할 때는 값이 에포크 이후 밀리초 단위인지 확인하십시오(Unix 타임스탬프).

amplitude.setSessionId(Date.now());

사용자 지정 장치 ID

deviceId를 사용하여 새 장치 ID를 할당할 수 있습니다. 사용자 지정 장치 ID를 설정할 때는 값이 충분히 고유한지 확인하십시오. Amplitude는 UUID 사용을 권장합니다.

amplitude.setDeviceId(uuid());

사용자가 로그아웃할 때 재설정

reset는 사용자가 로그아웃한 후 익명화하는 바로 가기입니다. 방법은 다음과 같습니다.

• userId을 undefined로 설정합니다.
• 새 UUID 값으로 deviceId설정합니다.

정의되지 않은 userId상태이고 완전히 새로운 deviceId상태인 경우 현재 사용자는 대시보드에 완전히 새로운 사용자로 표시됩니다.

amplitude.reset();

사용자를 추적에서 해제합니다

true을 setOptOut로 설정하여 지정된 사용자에 대한 로깅을 해제할 수 있습니다.

amplitude.setOptOut(true);

Amplitude는 setOptOut가 활성화되어 있는 동안 이벤트를 저장하거나 서버에 전송하지 않으며, 이 설정은 페이지가 로드될 때에도 지속됩니다.

false로 설정하여 setOptOut로깅을 다시 활성화합니다.

amplitude.setOptOut(false);

추적 옵션

기본적으로 SDK는 이러한 속성을 자동으로 추적합니다. SDK를 초기화할 때 trackingOptions라는 구성을 전달하고 해당 옵션을 false로 설정하여 이 동작을 재정의할 수 있습니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  trackingOptions: {
    deviceManufacturer: false,
    deviceModel: false,
    ipAddress: false,
    language: false,
    osName: false,
    osVersion: false,
    platform: false,
  },
});

콜백

선택적으로 Promise 인터페이스를 통해 모든 비동기 API를 기다릴 수 있습니다. Promise 인터페이스는 콜백 인터페이스로도 사용됩니다.

amplitude.init("apikey", "12321.com").promise.then(function () {
  // init callback
});
amplitude.track("Button Clicked").promise.then(function (result) {
  result.event; // {...} (The final event object sent to Amplitude)
  result.code; // 200 (The HTTP response status code of the request.
  result.message; // "Event tracked successfully" (The response message)
});

플러그인

플러그인을 사용하면 이벤트 속성을 수정하거나(보강 유형), 타사 API로 전송(목적지 유형)하는 등의 방법으로 Amplitude SDK의 동작을 확장할 수 있습니다. 플러그인은 setup() 및 execute() 메서드를 가진 객체입니다.

add

add 메소드는 Amplitude에 플러그인을 추가합니다. 플러그인은 이벤트를 처리하고 전송하는 데 도움이 될 수 있습니다.

amplitude.add(new Plugin());

remove

remove 메서드는 클라이언트 인스턴스에 지정된 플러그인 이름이 있는 경우 해당 이름을 제거합니다.

amplitude.remove(plugin.name);

사용자 지정 플러그인 만들기

Plugin.setup

이 메서드는 플러그인을 사용할 준비를 위한 논리를 포함하고 있으며 config를 매개변수로 사용합니다. 예상 반환 값은 undefined입니다. 이 메서드의 일반적인 용도는 config에서 구성을 복사하거나 플러그인 의존성을 인스턴스화하는 것입니다. SDK는 amplitude.add()를 통해 클라이언트에 플러그인을 등록할 때 이 메서드를 호출합니다.

Plugin.execute

이 메서드는 이벤트를 처리하기 위한 논리를 포함하고 있으며 이벤트를 매개변수로 취합니다. 보강 유형 플러그인으로 사용될 경우 예상 반환 값은 수정되거나 보강된 이벤트입니다. 대상 유형 플러그인으로 사용될 경우 예상되는 반환 값은 event(BaseEvent), code (number), message(string) 키가 있는 맵입니다. SDK는 Identify, GroupIdentify 및 Revenue 이벤트를 비롯하여 클라이언트 인터페이스를 통해 계측되는 각 이벤트에 대해 이 메서드를 호출합니다.

플러그인 예제

목적지 유형 플러그인

다음은 사용자가 선호하는 HTTP 클라이언트를 사용하여 각 계측된 이벤트를 대상 서버 URL로 전송하는 플러그인의 예입니다.

function myDestinationPlugin (serverUrl) {
  const name = 'my-destination-plugin';
  const type = amplitude.Types.PluginType.DESTINATION;
  let amplitudeConfig;
  /**
   * setup() is called on plugin installation
   * example: amplitude.add(new myDestinationPlugin());
   */
  const setup = function (config) {
    amplitudeConfig = config;
  }
  /**
   * execute() is called on each event instrumented
   * example: amplitude.track('New Event');
   */
  const execute = function (event) {
    const payload = {
      key: 'secret',
      data: event,
    };
    return fetch(this.serverUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Accept: '*/*',
      },
      body: JSON.stringify(payload),
    }).then(function(response) {
      return {
        code: response.status,
        event: event,
        message: response.statusText,
      };
    });
  }
  return {
    name,
    type,
    setup,
    execute,
  },
}
amplitude.init(API_KEY);
amplitude.add(myDestinationPlugin('https://custom.domain.com'));

보강 유형 플러그인

다음은 이벤트의 event_id속성에 증분 정수를 추가하여 계측된 각 이벤트를 수정하는 플러그인의 예입니다(100부터 시작).

const addEventIdPlugin = () => {
  const name = "add-event-id";
  const type = amplitude.Types.PluginType.ENRICHMENT;
  let currentId = 100;
  let amplitudeConfig;
  /**
   * setup() is called on plugin installation
   * example: amplitude.add(new AddEventIdPlugin());
   */
  const setup = function (config) {
    amplitudeConfig = config;
  };
  /**
   * execute() is called on each event instrumented
   * example: client.track('New Event');
   */
  const execute = function (event: Event) {
    event.event_id = currentId++;
    return event;
  };
  return {
    name,
    type,
    setup,
    execute,
  };
};
amplitude.init(API_KEY);
amplitude.add(addEventIdPlugin());

웹 어트리뷰션 강화 플러그인

plugin-web-attribution-browser메서드를 호출하기 전에 init패키지를 다운로드하고 webAttributionPlugin를 추가하십시오.

npm install @amplitude/plugin-web-attribution-browser

플러그인을 Amplitude 인스턴스에 추가합니다.

amplitude.add(webAttributionPlugin());
amplitude.init(API_KEY);

구성에 대한 자세한 내용은 구성 옵션을 참조하십시오.

Web Attribution 플러그인이 지원하는 기능에 대한 자세한 내용은 플러그인 문서를 참조하십시오.

기본 SDK와의 차이점

Attribution 플러그인을 활성화하면 SDK의 기본 속성 추적 동작이 무시됩니다.

SDK에 내장된 속성 추적은 세션 시작 시의 속성만 추적합니다. 즉, 사용자가 세션 도중에 새로운 캠페인 채널(예: 직접 또는 광고)을 통해 사이트에 다시 들어오더라도 SDK는 이 새로운 채널을 기록하지 않습니다.

trackNewCampaigns옵션이 true로 설정되어 있으면 SDK가 캠페인을 추적하고 새 캠페인을 감지할 때 사용자의 세션을 재설정합니다.

어트리뷰션 플러그인은 사용자가 세션을 시작했는지 여부에 관계없이 모든 캠페인을 추적합니다.

Amplitude가 새 캠페인을 감지할 때 사용자의 세션을 재설정하려면 resetSessionOnNewCampaign옵션을 true으로 설정하십시오. 추천자가 사이트의 다른 하위 도메인일 경우 세션은 재설정되지 않습니다.

페이지 보기 강화 플러그인

init 메소드를 호출하기 전에 plugin-page-view-tracking-browser를 다운로드하고 pageViewTrackingPlugin를 추가하십시오.

npm install @amplitude/plugin-page-view-tracking-browser

플러그인을 Amplitude 인스턴스에 추가합니다.

amplitude.add(pageViewTrackingPlugin());
amplitude.init(API_KEY);

구성에 대한 자세한 내용은 구성 옵션을 참조하십시오. 페이지 보기 플러그인이 지원하는 기능에 대한 자세한 내용은 플러그인 문서를 참조하십시오.

기본 SDK와의 차이점

이 attribution.trackPageViews 옵션이 true로 설정된 경우 기본 SDK는 Amplitude가 사용자의 캠페인을 추적할 때 페이지 뷰 이벤트를 전송합니다.

페이지 보기 플러그인은 기본적으로 사용자가 방문하는 각 페이지에 페이지 보기 이벤트를 전송합니다. 플러그인은 이 동작을 사용자 정의할 수 있는 옵션도 제공합니다.

문제 해결 및 디버깅

브라우저에서 디버깅하면 코드 구현과 관련된 문제뿐만 아니라 사용하는 SDK 첫 사용 후 잠재적 문제를 식별하는 데 도움이 될 수 있습니다. 다음은 디버깅을 위해 브라우저에 내장된 개발자 도구(DevTools)를 사용하는 방법에 대한 기본 가이드입니다.

콘솔

검사 > 콘솔에서 JavaScript 오류를 찾을 수 있습니다. 여기에는 문제를 일으킨 코드 줄과 파일에 대한 세부 정보가 있을 수 있습니다. 또한 콘솔을 사용하면 JavaScript 코드를 실시간으로 실행할 수 있습니다.

• 디버그 모드 지침에 따라 디버그 모드를 활성화하십시오. 그런 다음 기본 로거를 사용하면 SDK가 전체 SDK 공용 메서드를 호출할 때 추가 함수 컨텍스트 정보를 개발자 콘솔에 출력하므로 디버깅에 유용할 수 있습니다.

• Amplitude는 SDK 지연 초기화를 지원합니다. Amplitude는 초기화 호출 후 초기화 전에 추적된 이벤트를 디스패치합니다. 이벤트를 전송할 수는 없지만 브라우저 콘솔에 입력한 후 amplitude.init(API_KEY, 'USER_ID')성공적으로 이벤트를 전송할 수 있다면, 해당 호출이 코드베이스에서 트리거되지 않았거나 amplitude.init초기화 다음 기간동안 올바른 Amplitude 인스턴스를 사용하고 있지 않을 수 있습니다.

네트워크 요청

검사 > 네트워크 탭을 사용하여 해당 페이지에서 수행한 모든 네트워크 요청을 확인할 수 있습니다. Amplitude 요청을 검색합니다.

응답 코드를 확인하고 응답 페이로드가 예상대로인지 확인하십시오.

Instrumentation 익스플로러/Chrome 확장 프로그램

Amplitude Instrumentation 익스플로러는 Google Chrome 웹 스토어에서 사용할 수 있는 확장 프로그램입니다. 이 확장 기능은 사용자가 트리거하는 각 Amplitude 이벤트를 캡처하여 확장 기능 팝업에 표시합니다. Amplitude가 이벤트를 성공적으로 전송했는지 확인하고 이벤트 페이로드의 컨텍스트를 확인합니다.

자세한 내용은 이벤트 스트림 분석 가이드를 참조하십시오.

일반적인 문제

다음은 브라우저 SDK와 관련된 일반적인 문제입니다. 보다 일반적인 문제에 대해서는 SDK 문제 해결 및 디버깅을 참조하십시오.

광고 차단 프로그램

Ad Blocker 이벤트가 삭제될 수 있습니다. 이러한 오류는 Ad Blocker가 추적에 영향을 미쳤음을 나타냅니다. 스크립트 태그를 통해 로드할 때 SDK 스크립트를 로드하는 동안 콘솔이나 네트워크 탭에 오류가 나타날 수 있습니다. npm 패키지와 함께 로드될 경우 SDK가 서버로 이벤트를 전송하려고 할 때 네트워크 탭에 오류가 나타날 수 있습니다. 오류는 브라우저에 따라 다를 수 있습니다.

• 크롬(우분투, 맥OS) 콘솔: error net::ERR_BLOCKED_BY_CLIENT 네트워크: 상태(차단됨:기타)
• Firefox (Ubuntu) 콘솔: 오류 텍스트에 전체 차단 관련 정보가 포함되어 있지 않습니다 네트워크: 전송된 열에는 uBlock Origin에 의해 차단된 플러그인 이름이 포함됩니다
• 사파리 (맥 OS) 콘솔: 오류에 텍스트가 포함되어 있습니다. 콘텐츠 차단기로 인해 프레임 ... 이 ...에서 리소스를 로드할 수 없습니다. 네트워크: 차단된 요청은 나열되지 않습니다. 브라우저가 이를 표시할 수 있는지 여부는 확실하지 않습니다.

Amplitude는 이러한 상황을 피하기 위해 프록시 서버를 사용할 것을 권장합니다.

쿠키 관련

SDK가 쿠키에 저장하는 정보에 대한 자세한 내용은 쿠키 관리 섹션을 참조하십시오. 쿠키를 비활성화하거나 개인 브라우저, 창 또는 탭을 사용하는 것과 같은 클라이언트의 행동은 쿠키에 불러오기된 이러한 값의 지속성에 영향을 미칩니다. 이러한 값이 지속되지 않거나 1씩 증가하지 않는 경우 이것이 원인일 수 있습니다.

CORS

CORS(Cross-Origin Resource Sharing)는 웹 페이지의 리소스를 다른 도메인에서 요청할 수 있는 방법을 제한하기 위해 브라우저가 구현하는 보안 조치입니다. CORS를 사용하는 경우 setServerURL이 문제가 발생할 수 있습니다.

Access to fetch at 'xxx' from origin 'xxx' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

Cross-origin resource sharing (CORS)는 악의적인 사이트가 다른 사이트의 데이터를 권한 없이 읽는 것을 방지합니다. 이 오류 메시지는 액세스하려는 서버가 사용자의 출처에서 요청된 리소스에 액세스하는 것을 허용하지 않고 있음을 나타냅니다. 이는 서버의 응답에 Access-Control-Allow-Origin헤더가 없기 때문입니다.

• 서버에 대한 제어 권한이 있는 경우 서버의 CORS 정책을 업데이트할 수 있습니다. 서버의 응답에 Access-Control-Allow-Origin 헤더를 추가하십시오. 이렇게 하면 여러분의 오리진이 요청을 할 수 있습니다. Access-Control-Allow-Origin의 값은 모든 출처를 허용하기 위해 *일 수도 있고 웹 페이지의 특정 URL일 수도 있습니다.

• 서버에 대한 제어 권한이 없는 경우 필요한 CORS 헤더를 추가하는 프록시 서버를 설정할 수 있습니다. 웹 페이지는 프록시에 요청을 전송하며, 프록시는 실제 서버에 요청을 전송합니다. 프록시는 응답을 웹 페이지로 다시 전송하기 전에 응답에 Access-Control-Allow-Origin헤더를 추가합니다.

API 프록시를 설정했는데 선택한 플랫폼에서 그와 관련된 구성 문제가 발생했다면, 이는 더 이상 SDK 문제가 아니라 애플리케이션과 서비스 공급자 대상 구간의 연동 문제입니다.

이벤트가 발생했지만 네트워크 요청이 없음

로거를 '디버그' 수준으로 설정하고 개발자 콘솔에서 호출 추적을 확인할 경우 SDK가 해당 track() 메서드를 호출한 것입니다. Amplitude, Amplitude Instrumentation 익스플로러 Chrome 확장 프로그램 또는 브라우저의 네트워크 요청 탭에서 해당 이벤트를 볼 수 없다면 Amplitude가 해당 이벤트를 수신하지 않은 것입니다. SDK는 이벤트를 전송하여 호출이 성공할 경우 이를 SDK의 내부 대기열에 넣지만, track()때로는 이러한 대기열에 저장된 이벤트가 성공적으로 전송되지 않을 수도 있습니다. 이 문제는 진행 중인 HTTP 요청이 취소될 때 발생할 수 있습니다. 예를 들어 브라우저를 닫거나 페이지를 떠나는 경우입니다.

이 문제를 해결하는 방법은 두 가지가 있습니다.

1. 표준 네트워크 요청을 사용하는 경우 초기화 다음 기간동안 전송을 로 설정하거나 페이지 종료 beacon시 beacon전송을 sendBeacon로 설정하십시오. 이는 백그라운드에서 이벤트를 전송하고 4xx또는 과 같은 서버 응답을 반환하지 않으므로 이 경우 작동하지 5xx않습니다. 따라서 실패 시 재시도하지 않습니다. sendBeacon는 백그라운드에서 예약된 요청만 전송합니다. 자세한 내용은 sendBeacon 섹션을 참조하십시오.

2. track()을 동기화하려면 호출 전에 키워드 await를 추가하십시오.

고급옵션 항목

도메인 간 추적

두 개의 다른 도메인에서 익명의 행동을 추적할 수 있습니다. Amplitude는 익명 사용자를 장치 ID로 식별하며, 이 ID는 도메인 간에 전달되어야 합니다. 예를 들면 다음과 같습니다.

• 사이트 1: www.example.com.
• 사이트 2: www.example.org.

사이트 1에서 시작한 후 사이트 2로 이동한 사용자의 경우 사이트 1에서 생성된 디바이스 ID를 매개변수로 사이트 2로 전달해야 합니다. 그런 다음 사이트 2는 디바이스 ID를 사용하여 SDK를 초기화해야 합니다.

deviceId가 URL 쿼리 매개변수에 포함되어 있는 경우 SDK는 URL 매개변수를 자동으로 파싱할 수 있습니다.

1. 사이트 1에서는 getDeviceId()에서 디바이스 ID를 가져옵니다.
2. 사용자가 탐색할 때 URL 매개 변수를 통해 디바이스 ID를 사이트 2에 전달하십시오. 예를 들어: www.example.com?deviceId=device_id_from_site_1.
3. init('API_KEY', null)를 사용하여 사이트 2에서 Amplitude SDK를 초기화합니다.

deviceId와 같이 init를 제공하지 않는 init('API_KEY', null, { deviceId: 'custom-device-id' })경우 SDK는 자동으로 URL 매개 변수를 사용하도록 폴백합니다.

사용자 지정 HTTP 클라이언트

사용자 정의를 위해 transportProvider 인터페이스의 구현을 Transport 구성 옵션에 제공할 수 있습니다. 예를 들어 사용자 정의된 HTTP 요청 헤더를 사용하여 프록시 서버에 요청을 전송하는 경우가 있습니다.

class MyTransport {
  send(serverUrl, payload) {
    // check example: https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/analytics-client-common/src/transports/fetch.ts
  }
}
amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  transportProvider: new MyTransport(),
});

sendBeacon 사용

표준 네트워크 요청과 달리 sendBeacon은 사용자가 브라우저를 닫거나 페이지를 떠나더라도 백그라운드에서 이벤트를 전송합니다.

모든 이벤트에 대해 sendBeacon을 사용하도록 전송 설정

sendBeacon를 사용하여 이벤트를 전송하려면 다음 두 가지 방법 중 하나를 사용하여 전송 SDK 옵션을 '비콘'으로 설정하십시오.

amplitude.init(API_KEY, "user@amplitude.com", {
  transport: TransportType.SendBeacon,
  // To make sure the event will be scheduled right away.
  flushIntervalMillis: 0,
  flushQueueSize: 1,
});

페이지를 종료할 때만 beacon을 사용하도록 전송 방식을 설정하십시오.

Amplitude는 pagehide이벤트에 대한 자체 이벤트 리스너를 추가할 것을 권장합니다.

window.addEventListener("pagehide", () => {
  amplitude.setTransport("beacon");
  // Sets https transport to use `sendBeacon` API
  amplitude.flush();
});

콘텐츠 보안 정책(CSP)

보안상의 이유로 웹 앱에 엄격한 콘텐츠 보안 정책(CSP)이 구성되어 있는 경우, Amplitude 도메인을 허용하도록 정책을 조정하십시오.

• 스크립트 로더를 사용할 때는 https://*.amplitude.com에 script-src추가하십시오.
• https://*.amplitude.com을 connect-src에 추가하십시오.

쿠키 관리

브라우저 SDK는 쿠키 저장소를 사용하여 동일한 도메인의 여러 하위 도메인이 공유하려는 정보를 유지합니다. 이 정보에는 사용자 세션과 마케팅 캠페인이 포함되며, SDK는 이를 별도의 쿠키 항목에 저장합니다.

쿠키 접두사

• AMP: SDK는 접두사와 API 키의 AMP처음 10자리 숫자를 사용하여 사용자 세션 쿠키를 생성합니다: AMP_{first_ten_digits_API_KEY}.
• AMP_MKTG: SDK는 API 키의 처음 10자리 숫자를 사용하여 마케팅 캠페인 AMP_MKTG쿠키를 생성합니다: AMP_MKTG_{first_ten_digits_API_KEY}.
• AMP_TEST: 초기화 시 SDK는 접두사와 함께 쿠키를 생성하여 쿠키 저장이 AMP_TEST제대로 작동하는지 확인합니다. SDK는 값을 현재 시간으로 설정하고 키를 사용하여 쿠키를 검색한 다음 검색된 값이 원래 설정된 시간과 일치하는지 확인합니다. 어떤 이유로든 AMP_TEST 접두사 쿠키가 성공적으로 삭제되지 않은 경우 안전하게 삭제할 수 있습니다.
• AMP_TLDTEST: 초기화 시 SDK는 쿠키 저장을 지원하는 하위 AMP_TLDTEST도메인을 찾기 위해 접두사와 함께 쿠키를 생성합니다. 예를 들어, https://analytics.amplitude.com/amplitude/home에서 쿠키 지원 여부를 확인할 때 SDK는 먼저 루트 도메인(amplitude.com)과 일치하는 하위 도메인을 찾으려고 시도하고, 실패하면 전체 도메인(analytics.amplitude.com)으로 되돌아갑니다. 어떤 이유로든 AMP_TLDTEST 접두사 쿠키가 성공적으로 삭제되지 않은 경우 안전하게 삭제할 수 있습니다.

쿠키 도메인

기본적으로 SDK는 이러한 쿠키를 쿠키 저장을 지원하는 최상위 도메인에 할당합니다. 쿠키는 여러 하위 도메인에서 공유될 수 있으므로 모든 하위 도메인에서 일관된 사용자 경험을 제공합니다.

예를 들어 사용자가 SDK가 초기화된 한 하위 도메인(data.amplitude.com)의 웹사이트에 로그인합니다. 초기화 시 SDK는 쿠키를 .amplitude.com에 할당합니다. 그런 다음 사용자가 다른 하위 도메인(analytics.amplitude.com)으로 이동하면 공유 쿠키가 로그인 정보를 공유합니다.

쿠키 데이터

SDK는 사용자 세션 쿠키와 마케팅 캠페인 쿠키의 두 가지 유형의 쿠키를 생성합니다.

쿠키 비활성화

disableCookies를 true로 설정하면 쿠키 사용을 거부하고 SDK가 대신 LocalStorage를 사용하도록 할 수 있습니다. LocalStorage는 유용한 대안이지만 LocalStorage에 대한 액세스가 하위 도메인별로 제한되므로 제품의 하위 도메인 간에 익명 사용자를 추적할 수 없습니다(예: www.amplitude.com 대 analytics.amplitude.com).

장치 ID 생애주기 분석

SDK는 다음 순서로 장치 ID를 초기화하며, 장치 ID를 발견한 첫 번째 유효한 값으로 설정합니다.

1. 초기화 시 구성에 있는 장치 ID입니다.
2. deviceId URL 매개변수의 값(예: http://example.com/?deviceId=123456789). 자세한 내용은 교차 도메인 추적을 참조하십시오.
3. 쿠키 저장소의 장치 ID입니다. 자세한 내용은 쿠키 관리를 참조하십시오.
4. 브라우저 SDK의 쿠키 저장소에 있는 장치 ID입니다. 자세한 내용은 쿠키 관리를 참조하십시오.
5. 무작위로 생성된 36자리 UUID입니다.

장치 ID가 변경되는 시기

장치 ID는 다음과 같은 여러 가지 시나리오에서 변경됩니다.

• 명시적으로 setDeviceId()를 호출합니다.
• 기본적으로 SDK는 기기 ID를 쿠키에 저장하므로 사용자가 쿠키를 지우거나, 다른 기기를 사용하거나, 개인정보 보호 모드를 사용하면 기기 ID가 변경됩니다.
• 초기화 시 URL 매개 변수가 장치 IDdeviceId를 전달합니다.
• reset()을(를) 호출하십시오.

사용자 지정 장치 ID

setDeviceId()를 사용하여 새 장치 ID를 할당할 수 있습니다. 사용자 지정 장치 ID를 설정할 때는 값이 충분히 고유한지 확인하십시오. Amplitude는 UUID 사용을 권장합니다.

amplitude.setDeviceId(uuid());

장치 ID 가져오기

헬퍼 메서드를 사용하여 현재 deviceId의 값을 얻을 수 있습니다getDeviceId().

const deviceId = amplitude.getDeviceId();