Node.js SDK 마이그레이션 가이드

Amplitude의 최신 Node.js SDK(@amplitude/analytics-node)는 플러그인 아키텍처와 내장형 타입 정의를 특징으로 합니다. 최신 Node.js SDK는 유지 관리 Node.js SDK@amplitude/node와 이전 버전과 호환되지 않습니다.

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

용어

@amplitude/node: Node.js SDK 유지 관리
@amplitude/analytics-node: 최신 Node.js SDK

종속성

package.json을 업데이트하여 유지 관리 Node.js SDK를 제거하고 최신 Node.js SDK를 설치하십시오.

json

{
  "dependencies": {
    "@amplitude/node": "*",
    "@amplitude/analytics-node": "^1"
  }
}

npm install @amplitude/analytics-node를 사용하여 @amplitude/analytics-node를 설치합니다.

계측

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

초기화

유지 관리 Node.js SDK는 네임스페이스 가져오기만 지원합니다. 최신 Node.js SDK는 네임스페이스 가져오기(import * as amplitude from '@amplitude/analytics-node')와 명명된 가져오기(import { init } from '@amplitude/analytics-node')를 모두 지원합니다. 이 문서의 예제에서는 명명된 가져오기를 사용합니다.

SDK를 초기화하려면 유효한 Amplitude API 키 및 구성 매개변수를 사용하여 init()를 호출하십시오.

import * as Amplitude from "@amplitude/node";
import { init } from "@amplitude/analytics-node";
var options = {};
const client = Amplitude.init(AMPLITUDE_API_KEY, options);
init(API_KEY, options);

구성

최신 Node.js SDK는 다른 구성 형태를 사용합니다. 최신 Node.js SDK는 더 이상 일부 구성 옵션을 지원하지 않습니다.

@amplitude/node	@amplitude/analytics-node
`debug`	`logLevel` 경고 수준으로 설정
`logLevel`	`logLevel`
`maxCachedEvents`	`flushQueueSize`
`retryTimeouts`	`flushMaxRetries`는 `retryTimeouts`에서와 같이 숫자 배열 대신 숫자로만 설정할 수 있습니다.
`optOut`	`optOut`
`retryClass`	지원되지 않습니다. 최신 Node.js SDK는 재시도 로직을 내부적으로 처리합니다.
`transportClass`	`transportProvider`
`serverUrl`	`serverUrl`
`uploadIntervalInSec`	`flushIntervalMillis`는 밀리초 단위이고 `uploadIntervalInSec`는 초 단위입니다.
`minIdLength`	`minIdLength`
`requestTimeoutMillis`	지원되지 않음
`onRetry`	지원되지 않습니다. 최신 Node.js SDK는 재시도 로직을 내부적으로 처리합니다.

이벤트 기록

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

import { track } from '@amplitude/analytics-node';
const eventProperties = {
    buttonColor: 'primary',
};
client.logEvent({
track({
  event_type: 'Button Clicked',
  user_id: 'user@amplitude.com',
  event_properties: eventProperties
});

플러시

flush() API는 동일하게 유지됩니다.

import { flush } from "@amplitude/analytics-node";
client.flush();
flush();

Identify

identify() API는 다른 서명을 사용합니다. 유지 관리 Node.js SDK 서명은 (userId: string | null, deviceId: string | null, identify: Identify)입니다. 최신 Node.js SDK 서명은 (identify: Identify, eventOptions?: EventOptions)입니다. EventOptions에 대한 자세한 내용은 EventOptions 참조를 참조하십시오.

import { identify, Identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.set("location", "LAX");
client.identify("user@amplitude.com", null, identifyObj);
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

미들웨어

미들웨어는 최신 Node.js SDK의 플러그인에 매핑됩니다. 최신 Node.js SDK는 두 가지 플러그인 유형을 지원합니다: 강화 플러그인과 목적지 플러그인입니다. 다음 예제에서는 이벤트 정보를 기록합니다.

+ import { add } from '@amplitude/analytics-node';
+ import { NodeConfig, EnrichmentPlugin, Event, PluginType } from '@amplitude/analytics-types';
- const loggingMiddleware: Middleware = (payload, next) => {
- console.log(`[amplitude] event=${payload.event} extra=${payload.extra}`);
- next(payload);
}
+ export class AddLogEventPlugin implements EnrichmentPlugin {
+ name = 'log-event';
+ type = PluginType.ENRICHMENT as const;
+ config?: NodeConfig;
+ async setup(config: NodeConfig): Promise<undefined> {
+ this.config = config;
+ return;
+ }
+ async execute(event: Event): Promise<Event> {
+ console.log(`[amplitude] event=${event}`);
+ return event;
+ }
+ }

addEventMiddleware() API는 add()에 매핑됩니다.

+ import { add } from '@amplitude/analytics-node';
- client.addEventMiddleware(new Middleware())
+ add(new Plugin());

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