Browser SDK 2 참조

이 참조는 버전 2.48.1에 대해 확인된 @amplitude/analytics-browser의 모든 공개 내보내기와 init()로 전달할 수 있는 모든 옵션을 설명합니다. 스크립트 로더를 사용하면 전역 amplitude 객체에서 동일한 멤버를 사용할 수 있습니다. 옵션을 보려면 구성 옵션으로 이동합니다. 기능이 추가되거나 변경된 릴리즈를 찾으려면 Browser SDK 2 릴리즈 노트를 참조하십시오.

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

최상위 함수는 기본 인스턴스에서 작동합니다. createInstance()의 각 인스턴스는 동일한 메서드를 갖습니다.

반환 값

비동기식 작업을 수행하는 메서드는 하나의 속성을 가진 객체인 AmplitudeReturn<T>를 반환합니다.promise 반환 값 자체가 아닌 promise를 기다립니다.

ts
const result = await amplitude.track("Song Played").promise; // correct
const wrapper = await amplitude.track("Song Played"); // returns { promise }, not a Result

업로드 시도가 완료되면 추적 메서드가 Result로 확인됩니다.

모든 코드 및 메시지에 대해서는 '업로드 결과 읽기'로 이동하십시오.

init()가 완료되기 전에 수행된 호출은 대기열에서 대기하다가 완료된 후 순서대로 실행됩니다. 해당 프로미스는 init()가 완료되고 업로드가 완료된 후 해결됩니다.

설정

초기화

인스턴스를 초기화합니다. 인스턴스당 한 번씩 호출합니다. 완료된 후 다시 호출하면 추가한 플러그인을 포함한 모든 플러그인이 해제되며 다시 시작됩니다.

ts
init(apiKey: string, options?: BrowserOptions): AmplitudeReturn<void>
init(apiKey: string, userId?: string, options?: BrowserOptions): AmplitudeReturn<void>

promise는 SDK가 원격 구성을 가져오고, 플러그인을 설치하고, 대기열에 있는 호출을 실행한 후 해결됩니다.

ts
await amplitude.init("YOUR_API_KEY", "user-12345", {
  serverZone: "EU",
}).promise;

createInstance

자체 구성, ID, 큐 및 플러그인을 사용하여 독립적 인스턴스를 생성합니다. 이를 사용하여 둘 이상의 프로젝트로 데이터를 전송합니다.

ts
createInstance(): BrowserClient
ts
const secondary = amplitude.createInstance();
secondary.init("OTHER_API_KEY", { instanceName: "secondary" });

스크립트 로더를 사용하면 amplitude.createInstance(name)도 인스턴스를 아래에 등록하여 nameSDK가 로드되기 전에 수행된 호출이 해당 인스턴스에 도달하도록 합니다.

추가

플러그인을 추가합니다. setup()인스턴스에서 이미 실행된 경우init() 즉시 실행되고, init()그렇지 않은 경우 실행됩니다. SDK는 이미 추가된 플러그인과 name일치하는 플러그인이 있으면 건너뛰고 경고를 기록합니다.

ts
add(plugin: Plugin): AmplitudeReturn<void>
ts
await amplitude.add({
  name: "add-app-section",
  execute: async (event) => {
    event.event_properties = { ...event.event_properties, section: "checkout" };
    return event;
  },
}).promise;

플러그인 컨트랙트를 보려면 Plugin으로 이동하십시오.

제거

이름으로 플러그인을 제거하고 해당 플러그인의 함수를 teardown()호출합니다.

ts
remove(pluginName: string): AmplitudeReturn<void>
ts
amplitude.remove("add-app-section");

setTransport

향후 업로드를 위해 HTTP API를 변경합니다.

ts
setTransport(transport: "fetch" | "xhr" | "beacon" | TransportOptions): void
ts
window.addEventListener("pagehide", () => {
  amplitude.setTransport("beacon");
  amplitude.flush();
});

플러시

이제 대기열에 있는 모든 이벤트를 업로드합니다. 수동 플러시는 실패한 업로드를 재시도하지 않습니다.

ts
flush(): AmplitudeReturn<void>
ts
await amplitude.flush().promise;

추적

추적

사용자 지정 이벤트를 전송합니다. logEvent() 는 동일한 서명을 가진 별칭입니다.

ts
track(eventInput: string | BaseEvent, eventProperties?: Record<string, any>, eventOptions?: EventOptions): AmplitudeReturn<Result>
logEvent(eventInput: string | BaseEvent, eventProperties?: Record<string, any>, eventOptions?: EventOptions): AmplitudeReturn<Result>
ts
amplitude.track(
  "Song Played",
  { title: "Here Comes the Sun" },
  { time: Date.now() },
);

식별

사용자 속성을 업데이트하는 $identify이벤트를 보냅니다.user_id 에 device_id 또는 eventOptions 가 포함된 경우, SDK는 이를 사용하여 setUserId() 또는 setDeviceId() 를 호출합니다.

ts
identify(identify: Identify, eventOptions?: EventOptions): AmplitudeReturn<Result>
ts
amplitude.identify(new amplitude.Identify().set("plan", "pro"));

setGroup

groups 가 설정된 $identify이벤트를 전송하여 현재 사용자를 그룹에 할당합니다.

ts
setGroup(groupType: string, groupName: string | string[], eventOptions?: EventOptions): AmplitudeReturn<Result>
ts
amplitude.setGroup("company", "Acme Inc");

groupIdentify

한 그룹의 속성을 업데이트하는 $groupidentify이벤트를 보냅니다. 업데이트는 해당 시점 이후의 이벤트에만 적용됩니다.

ts
groupIdentify(groupType: string, groupName: string | string[], identify: Identify, eventOptions?: EventOptions): AmplitudeReturn<Result>
ts
amplitude.groupIdentify(
  "company",
  "Acme Inc",
  new amplitude.Identify().set("seats", 250),
);

매출

객체Revenue에서 생성된 revenue_amount이벤트를 보냅니다.

ts
revenue(revenue: Revenue, eventOptions?: EventOptions): AmplitudeReturn<Result>
ts
amplitude.revenue(
  new amplitude.Revenue().setProductId("pro-annual").setPrice(99.99),
);

trackVideo

실험적. <video> 요소 또는 player.js 내장 플레이어의 트랙 Video Content Started및 Video Content Stopped이벤트를 추적합니다. Browser SDK 2.39.0 이상이 필요합니다.

ts
trackVideo(amplitude: BrowserClient, video: HTMLVideoElement | EmbeddedVideoPlayer, options?: VideoCaptureOptions): (() => void) | Error

추적을 중단하는 함수를 반환하거나, SDK가 연결할 수 없는 경우 Error를 반환합니다.

ts
const stop = amplitude.trackVideo(amplitude, document.querySelector("video")!);

아이덴티티

getUserId 및 setUserId

향후 이벤트를 위해 사용자 ID를 읽거나 설정합니다. setUserId(undefined)이를 지우려면 사용하세요.

ts
getUserId(): string | undefined
setUserId(userId: string | undefined): void
ts
amplitude.setUserId("user-12345");

getDeviceId 및 setDeviceId

향후 이벤트를 위해 장치 ID를 읽거나 설정합니다.

ts
getDeviceId(): string | undefined
setDeviceId(deviceId: string): void
ts
amplitude.setDeviceId("2f9d6a1e-4b7c-4f0e-9a51-0c3e8b7d5a12");

재설정

사용자 ID를 지우고 새 장치 ID를 생성합니다. 사용자가 로그아웃할 때 사용하십시오. 새 세션을 시작하지는 않습니다.

ts
reset(): void
ts
amplitude.reset();

getIdentity 및 setIdentity

장치 ID, 사용자 ID 및 사용자 속성을 함께 읽거나 업데이트합니다. setIdentity()이(가) userProperties을(를) 수신하면 각 키를 $set(으)로 설정하는 $identify 이벤트를 전송합니다. userProperties은(는) 이 페이지 로드에서 설정된 속성만 보관합니다. getIdentity()은(는) 브라우저 SDK 2.18.0 이상이 필요하며, setIdentity()은(는) 2.35.0 이상이 필요합니다.

ts
getIdentity(): { deviceId?: string; userId?: string; userProperties?: Record<string, any> }
setIdentity(identity: { deviceId?: string; userId?: string; userProperties?: Record<string, any> }): void
ts
amplitude.setIdentity({
  userId: "user-12345",
  userProperties: { plan: "pro" },
});

세션

getSessionId 및 setSessionId

현재 세션 ID를 읽거나, 현재 세션을 종료하고 지정된 ID로 세션을 시작합니다. Unix 타임스탬프를 밀리초 단위로 전달합니다. 옵트아웃된 인스턴스는 ID를 저장하고 옵트아웃이 꺼지면 세션을 시작합니다.

ts
getSessionId(): number | undefined
setSessionId(sessionId: number): void
ts
amplitude.setSessionId(Date.now());

extendSession

이벤트를 전송하지 않고 세션을 현재 활성화로 표시합니다.

ts
extendSession(): void
ts
amplitude.extendSession();

개인정보 보호

getOptOut 및 setOptOut

읽거나 옵트아웃을 설정합니다. 옵트아웃 상태인 동안 trueSDK는 모든 이벤트를 삭제합니다. 값은 ID 저장소에 유지됩니다. getOptOut()브라우저 SDK 2.18.0 이상이 필요합니다.

ts
getOptOut(): boolean | undefined
setOptOut(optOut: boolean): void
ts
amplitude.setOptOut(true);

Identify

Identify identify()는 groupIdentify(), 및 identifyinit 옵션에 대한 사용자 속성 또는 그룹 속성 작업을 구축합니다. 각 메서드는 동일한 객체를 반환하므로 호출을 체이닝할 수 있습니다. 각 속성은 객체당 하나의 작업만 수행할 수 있습니다. SDK는 동일한 속성에 대한 이후 작업 및 그 clearAll()이후의 모든 작업을 무시합니다.

ts
const identify = new amplitude.Identify();

값은 문자열, 숫자, 부울, 배열 또는 해당 유형의 객체를 허용합니다.

매출

Revenue revenue_amount는 이벤트의 속성을 구축합니다. 각 setter는 동일한 객체를 반환합니다.

ts
const revenue = new amplitude.Revenue();

플러그인

플러그인은 SDK가 모든 이벤트에 대해 실행하는 객체입니다. add()에 전달합니다.

각 이벤트에 대해 SDK는 모든 이전 플러그인, 그 다음 모든 강화 플러그인, 마지막으로 모든 목적지 플러그인을 순서대로 실행합니다. 동일한 유형의 플러그인은 추가한 순서대로 실행됩니다. Plugins는 내장된 자동 캡처 플러그인보다 먼저 설치되므로, init()먼저 실행됩니다.

ts
const lowercaseUserId: amplitude.Types.BeforePlugin = {
  name: "lowercase-user-id",
  type: "before",
  execute: async (event) => {
    if (event.user_id) event.user_id = event.user_id.toLowerCase();
    return event;
  },
};
amplitude.add(lowercaseUserId);

이벤트를 자체 엔드포인트로 전달하는 목적지 플러그인:

ts
const forwardToWarehouse = (
  url: string,
): amplitude.Types.DestinationPlugin => ({
  name: "forward-to-warehouse",
  type: "destination",
  execute: async (event) => {
    const response = await fetch(url, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(event),
    });
    return { event, code: response.status, message: response.statusText };
  },
});
amplitude.add(forwardToWarehouse("https://collect.example.com/events"));

Amplitude는 페이지 URL 강화 및 사용자 정의 강화와 같은 기성 플러그인을 게시합니다. 자세한 내용은 SDK 플러그인을 참조하십시오.

유형

amplitude.Types 다음을 포함하여 TypeScript 유형 및 상수를 내보냅니다.

연동 내보내기

이러한 내보내기는 다른 Amplitude 패키지에 대해 존재합니다. 대부분의 앱에서는 이러한 기능이 필요하지 않습니다.

구성 옵션

이 섹션에서는 브라우저 SDK 2.48.1 기준으로, BrowserOptions에 전달하는 구성 객체의 모든 옵션을 init()나열합니다. 모든 옵션은 선택 사항입니다. 지원 중단된 옵션은 여전히 작동합니다.

ts
amplitude.init(apiKey: string, options?: BrowserOptions);
amplitude.init(apiKey: string, userId?: string, options?: BrowserOptions);

Identity 및 session

쿠키 옵션

SDK는 다음과 같은 쿠키를 작성합니다.

데이터 수집

전송

전송 옵션

원격 구성 및 진단

사용자 지정 loggerProvider은 모든 ILogger 메서드를 구현해야 합니다. 이 예제는 SDK 오류를 자체 오류 보고에 전달하고 기본 콘솔 출력을 유지합니다.

ts
class ErrorReportingLogger implements amplitude.Types.ILogger {
  private level = amplitude.Types.LogLevel.Warn;
  enable(logLevel: amplitude.Types.LogLevel) {
    this.level = logLevel;
  }
  disable() {
    this.level = amplitude.Types.LogLevel.None;
  }
  log(...args: any[]) {
    if (this.level >= amplitude.Types.LogLevel.Verbose) console.log(...args);
  }
  warn(...args: any[]) {
    if (this.level >= amplitude.Types.LogLevel.Warn) console.warn(...args);
  }
  error(...args: any[]) {
    reportError(args.join(" ")); // Your error reporting, at every log level.
    if (this.level >= amplitude.Types.LogLevel.Error) console.error(...args);
  }
  debug(...args: any[]) {
    if (this.level >= amplitude.Types.LogLevel.Debug) console.log(...args);
  }
}
amplitude.init("YOUR_API_KEY", { loggerProvider: new ErrorReportingLogger() });

자동 캡처 옵션

autocapture 는 true, false또는 이러한 키를 가진 객체를 허용합니다. 동작 및 예제를 보려면 자동 캡처로 이동하십시오.

autocapture: true를 제외한 모든 키를 설정합니다performanceTracking. Chrome 확장 프로그램에서 default-on 키는 설정하지 않으면 꺼져 있습니다. 기본값은 2.42.1에서 변경되었습니다.

AttributionOptions

PageTrackingOptions

FormInteractionsOptions

ElementInteractionsOptions

FrustrationInteractionsOptions

네트워크추적 옵션

각 항목은 NetworkCaptureRule다음을 허용합니다.

Amplitude는 BrowserOptions의 최상위 수준에서 networkTrackingOptions을(를) 더 이상 사용하지 않습니다. autocapture.networkTracking를 사용하십시오.

WebVitalsOptions

PerformanceTrackingOptions

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

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.

이 페이지에서