Javascript SDK에서 브라우저 SDK 1.0으로 마이그레이션

Amplitude 브라우저 SDK 1.0(@amplitude/analytics-browser)은 플러그인 아키텍처, 내장 유형 정의, 프런트엔드 프레임워크에 대한 광범위한 지원을 특징으로 합니다. 브라우저 SDK 1.0은 amplitude-js과 역호환되지 않습니다.

@amplitude/analytics-browser로 마이그레이션하려면 종속성 및 계측을 업데이트하십시오.

용어

• amplitude-js: Maintenance 브라우저 SDK.
• @amplitude/analytics-browser: 브라우저 SDK 1.0입니다.

종속성

스니펫 설치를 위해서는 프로젝트의 스니펫 로더를 업데이트하십시오.

Node 프로젝트의 경우 package.json의 종속성 목록을 업데이트하십시오.

{
  "dependencies": {
    "amplitude-js": "^8"
  }
}

계측

브라우저 SDK 1.0은 이벤트를 계측하기 위한 API를 제공합니다. 브라우저 SDK 1.0으로 마이그레이션하려면 몇 가지 호출을 업데이트하십시오. 다음 섹션에서는 변경된 호출에 대해 자세히 설명합니다.

초기화

다른 모든 통화와 마찬가지로 Amplitude도 getInstance()를 삭제했습니다. SDK를 초기화하려면 동일한 매개변수를 사용하여 init()를 호출하십시오. config매개변수의 모양은 다릅니다. 구성을 참조하십시오.

import amplitude from "amplitude-js";
amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, config);

구성

이벤트 추적

유지 관리 브라우저 SDK는 이벤트 페이로드의 특정 속성을 재정의하기 위해 logEventWithTimestamp 및 logEventWithGroups과 같은 여러 logEvent API를 제공했습니다. Amplitude는 이러한 변형을 @amplitude/analytics-browser에서 통합 track API로 단순화했습니다.

logEvent()

logEvent() API는 track()에 매핑됩니다.

const eventType = "Button Clicked";
const eventProperties = {
  type: "primary",
};
amplitude.getInstance().logEvent(eventType, eventProperties);

logEventWithTimestamp()

logEventWithTimestamp() API는 track()에 매핑됩니다.

const eventType = "Button Clicked";
const eventProperties = {
  type: "primary",
};
const timestamp = Date.now();
amplitude
  .getInstance()
  .logEventWithTimestamp(eventType, eventProperties, timestamp);

logEventWithGroups()

logEventWithGroups() API는 track()에 매핑됩니다.

const eventType = "Button Clicked";
const eventProperties = {
  type: "primary",
};
const groups = {
  orgId: "12345",
};
amplitude.getInstance().logEventWithGroups(eventType, eventProperties, groups);

sendEvents()

sendEvents() API는 flush()에 매핑됩니다.

amplitude.getInstance().sendEvents();

사용자 속성 설정

사용자 속성을 설정하기 위한 API는 getInstance()가 더 이상 존재하지 않는다는 점을 제외하고는 동일합니다. 다음 코드 조각은 사용자 속성 API를 마이그레이션하는 방법을 보여줍니다.

setUserId()

getInstance()를 호출하지 않고 amplitude를 호출할 때 userId를 설정합니다.

const userId = "1";
amplitude.getInstance().setUserId(userId);

setDeviceId()

getInstance()를 호출하지 않고 amplitude를 호출할 때 deviceId를 설정합니다.

const deviceId = "1";
amplitude.getInstance().setDeviceId(deviceId);

setSessionId()

getInstance()를 호출하지 않고 amplitude를 호출할 때 sessionId를 설정합니다.

const sessionId = Date.now();
amplitude.getInstance().setSessionId(sessionId);

clearUserProperties()

Amplitude는 clearUserPropertiesAPI를 삭제했습니다. 통합 identify API를 사용하여 사용자 속성을 제거하십시오.

amplitude.getInstance().clearUserProperties();

setUserProperties()

Amplitude는 setUserPropertiesAPI를 삭제했습니다. 통합 identify API를 사용하여 사용자 속성을 추가하십시오.

amplitude.getInstance().setUserProperties({
  membership, "paid",
  payment, "bank",
})

identify()

amplitude에서 getInstance()를 호출하지 않고 identify 호출을 수행하십시오.

const identify = new amplitude.Identify();
identify.set("membership", "paid");
amplitude.getInstance().identify(identify);

그룹 속성 설정

groupIdentify()

amplitude에서 getInstance()를 호출하지 않고 identify 호출을 수행하십시오.

const identify = new amplitude.Identify();
identify.set("membership", "paid");
amplitude.getInstance().groupIdentify(identify);

매출 추적

logRevenueV2()

getInstance()를 호출하지 않고 amplitude API를 사용하여 revenue()수익을 추적하십시오.

const revenue = new amplitude.Revenue();
revenue.setProductId("productId").setPrice(10);
amplitude.getInstance().logRevenueV2(revenue);

패턴

플러그인

config.language, config.library 및 config.platform 구성을 amplitude-js에서 사용하여 이러한 특정 필드에 대한 이벤트 페이로드를 수정할 수 있었습니다. @amplitude/analytics-browser는 이러한 구성을 지원하지 않지만 새 브라우저 SDK에 플러그인을 추가하여 이벤트 페이로드를 풍부하게 할 수 있습니다.

import {
  BrowserConfig,
  EnrichmentPlugin,
  Event,
  PluginType,
} from "@amplitude/analytics-types";
export class LibraryModifierPlugin implements EnrichmentPlugin {
  name = "library-modifier";
  type = PluginType.ENRICHMENT as const;
  /**
   * setup() is called on plugin installation
   * example: client.add(new LibraryModifierPlugin());
   */
  setup(config: BrowserConfig): Promise<undefined> {
    this.config = config;
  }
  /**
   * execute() is called on each event instrumented
   * example: client.track('New Event');
   */
  execute(event: Event): Promise<Event> {
    event.library = "my-library-name/1.0.0";
    return Promise.resolve(event);
  }
}

사용자 지정 플러그인을 설치하려면 사용자 지정 플러그인과 함께 add()를 매개변수로 사용하십시오.

import { add } from "@amplitude/analytics-browser";
add(new LibraryModifierPlugin());

초기화 지연

amplitude-js에서 초기화를 연기하려면 config.deferInitialization를 true로 설정하여 init를 호출한 다음, enableTracking()를 호출하여 초기화를 공식화하고 대기열에 있는 모든 이벤트를 전송하십시오.

amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, {
  deferInitialization: true,
});
amplitude.getInstance().logEvent("Event 1");
amplitude.getInstance().logEvent("Event 2");
amplitude.getInstance().logEvent("Event 3");
amplitude.getInstance().enableTracking();

웹 어트리뷰션

amplitude-js에서는 다음 구성을 활성화하여 웹 어트리뷰션을 활성화할 수 있습니다.

• config.includeGclid.
• config.includeFbclid.
• config.includeReferrer.
• config.includeUtm.

@amplitude/analytics-browser에서는 단일 구성으로 웹 속성을 제어합니다config.attribution.disabled. 기본값은 모든 캠페인 매개 변수를 캡처하는 false입니다. 이 구성은 amplitude-js에서 지원하는 것과 동일한 캠페인 매개 변수를 수집합니다.

플러시 또는 onExitPage

사용자가 페이지를 벗어날 때와 같이 일부 시나리오에서는 이벤트를 즉시 전송해야 합니다. 이 경우는 이벤트 페이로드를 일괄 처리로 전송하는 동안 사용자를 다른 페이지로 안내하는 추적 버튼 클릭 시에 일반적입니다.

amplitude-js에서는 onExitPage() 콜백을 사용합니다.

amplitude.getInstance().init(API_KEY, OPTIONAL_USER_ID, {
  onExitPage: () => {
    amplitude.sendEvents();
  },
});

콜백

amplitude-js에서는 초기화 후에 실행될 하나의 콜백 함수와 성공 및 오류 네트워크 요청에 대한 두 개의 별도의 콜백 함수를 전달합니다. init``@amplitude/analytics-browser는 Promise(및 async/await)를 지원하기 때문에 init(), track(), identify(), groupIdentify()와 같은 비동기 메서드는 사용자 정의 Promise 인터페이스를 반환합니다.

const initResult = await amplitude.init("YOUR_API_KEY").promise;
if (initResult.code === 200) {
  // success logic
} else {
  // error logic
}
const result = await amplitude.track("Button Clicked").promise;
if (result.code === 200) {
  // success logic
} else {
  // error logic
}