Node.js SDK

Node.js SDK를 사용하면 Amplitude에 이벤트를 전송할 수 있습니다.

SDK 설치

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

npm install @amplitude/analytics-node

SDK 초기화

계측하기 전에 SDK를 초기화해야 합니다. 초기화에는 Amplitude 프로젝트의 API 키가 필요합니다. SDK를 초기화한 후에는 애플리케이션의 어디에서나 사용할 수 있습니다.

import { init } from "@amplitude/analytics-node";
// Option 1, initialize with API_KEY only
init(API_KEY);
// Option 2, initialize including configuration
init(API_KEY, {
  flushIntervalMillis: 30 * 1000, // Sets request interval to 30s
});

SDK 구성

일괄 처리 동작 구성

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

import * as amplitude from "@amplitude/analytics-node";
amplitude.init(API_KEY, {
  // 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,
});

EU 데이터 상주

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

import * as amplitude from "@amplitude/analytics-node";
amplitude.init(API_KEY, {
  serverZone: amplitude.Types.ServerZone.EU,
});

디버깅

개발자 콘솔에 인쇄되는 로그 수준을 제어합니다.

• None: 모든 로그 메시지를 억제합니다.
• Error: 오류 메시지만 표시합니다.
• Warn: 오류 메시지와 경고를 표시합니다. logLevel을 명시적으로 지정하지 않은 경우 이 값이 기본값입니다.
• Verbose: 유용한 메시지를 표시합니다.
• Debug: 모든 SDK 공용 메소드 호출에 대한 함수 컨텍스트 정보를 비롯하여 디버깅에 유용할 수 있는 오류 메시지, 경고 및 유용한 메시지를 표시합니다. 이 로깅 모드는 개발 단계에서만 사용하십시오.

원하는 logLevel 수준으로 구성하여 로그 수준을 설정합니다.

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

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

사용자 고유의 구현을 사용하여 loggerProvider를 구성하여 로거를 설정하십시오.

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

디버그 모드

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

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

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

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

이벤트 추적

이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어 '버튼 클릭됨'은 기록해야 할 동작일 수 있습니다.

import { track } from "@amplitude/analytics-node";
// Track a basic event
track("Button Clicked", undefined, {
  user_id: "user@amplitude.com",
});
// Track events with optional properties
const eventProperties = {
  buttonColor: "primary",
};
track("Button Clicked", eventProperties, {
  user_id: "user@amplitude.com",
});

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

이벤트를 여러 Amplitude 프로젝트에 기록하려면 각 Amplitude 프로젝트에 대해 별도의 인스턴스를 생성하십시오. 그런 다음 Amplitude를 호출하려는 모든 위치에 인스턴스 변수를 전달하십시오. 각 인스턴스는 독립적인 apiKeys, userIds, deviceIds 및 설정을 허용합니다.

import * as amplitude from "@amplitude/analytics-node";
const defaultInstance = amplitude.createInstance();
defaultInstance.init(API_KEY_DEFAULT);
const envInstance = amplitude.createInstance();
envInstance.init(API_KEY_ENV, {
  instanceName: "env",
});

사용자 속성

사용자 속성은 사용자가 앱 첫 사용 후 어떤 작업을 수행했을 때의 사용자를 이해하는 데 도움이 됩니다(예: 사용자의 기기 세부 정보, 환경 설정, 언어).

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

사용자 속성 설정

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

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

Identify.set

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

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

Identify.setOnce

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.setOnce("initial-location", "SFO");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.add

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.add("travel-count", 1);
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

사용자 속성의 배열

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

Identify.prepend

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.prepend("visited-locations", "LAX");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.append

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.append("visited-locations", "SFO");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.preInsert

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.preInsert("unique-locations", "LAX");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.postInsert

이 메서드는 사용자 속성에 값이 아직 존재하지 않는 경우 해당 값을 사용자 속성에 사후 삽입합니다. 사후 삽입은 주어진 목록의 끝에 값을 삽입하는 것을 의미합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우, SDK는 새 값을 사후 추가하기 전에 빈 목록으로 초기화합니다. 사용자 속성에 기존 값이 있으면 이 메서드는 아무 작업도 수행하지 않습니다.

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.postInsert("unique-locations", "SFO");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

Identify.remove

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

import { Identify, identify } from "@amplitude/analytics-node";
const identifyObj = new Identify();
identifyObj.remove("unique-locations", "JFK");
identify(identifyObj, {
  user_id: "user@amplitude.com",
});

사용자 그룹

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

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

그룹을 설정할 때 groupType 및 groupName를 정의하십시오. 이전 예시에서 'orgId'는 groupType이고 '10'과 '15'는 groupName에 대한 값입니다. groupType의 또 다른 예로는 'tennis' 및 'baseball'과 같은 groupName 값을 가진 'sport'가 있을 수 있습니다.

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

import { setGroup } from "@amplitude/analytics-node";
// set group with a single group name
setGroup("orgId", "15", {
  user_id: "user@amplitude.com",
});

import { setGroup } from "@amplitude/analytics-node";
// set group with multiple group names
setGroup("sport", ["soccer", "tennis"], {
  user_id: "user@amplitude.com",
});

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

import { track } from "@amplitude/analytics-node";
track(
  {
    event_type: "event type",
    event_properties: { eventPropertyKey: "event property value" },
    groups: { orgId: "15" },
  },
  undefined,
  {
    user_id: "user@amplitude.com",
  },
);

그룹 속성

Group Identify API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트하십시오. 이러한 업데이트는 앞으로 진행되는 이벤트에만 영향을 줍니다.

이 groupIdentify() 메소드는 그룹 유형 및 그룹 이름 문자열 매개변수와 그룹에 적용되는 Identify 객체를 허용합니다.

import { Identify, groupIdentify } from "@amplitude/analytics-node";
const groupType = "plan";
const groupName = "enterprise";
const event = new Identify();
event.set("key1", "value1");
groupIdentify(groupType, groupName, identify, {
  user_id: "user@amplitude.com",
});

수익 추적

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

사용자의 수익을 추적하려면 사용자가 수익을 창출할 때마다 수익을 호출하십시오. 예를 들어 고객이 제품 3대를 3.99달러에 구매했습니다.

import { Revenue, revenue } from "@amplitude/analytics-node";
const event = new Revenue()
  .setProductId("com.company.productId")
  .setPrice(3.99)
  .setQuantity(3);
revenue(event, {
  user_id: "user@amplitude.com",
});

수익 인터페이스

이벤트 버퍼 플러시

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

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

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

await init(AMPLITUDE_API_KEY).promise;
track("Button Clicked", undefined, {
  user_id: "user@amplitude.com",
});
await flush().promise;

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

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

import { setOptOut } from "@amplitude/analytics-node";
setOptOut(true);

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

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

import { setOptOut } from "@amplitude/analytics-node";
setOptOut(false);

콜백

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

import { track } from "@amplitude/analytics-node";
// Using async/await
const results = await track("Button Clicked", undefined, {
  user_id: "user@amplitude.com",
}).promise;
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)
// Using promises
track("Button Clicked", undefined, {
  user_id: "user@amplitude.com",
}).promise.then((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 메소드는 Amplitude 클라이언트 인스턴스에 플러그인을 추가합니다. 플러그인은 이벤트를 처리하고 전송하는 데 도움이 될 수 있습니다.

import { add } from "@amplitude/analytics-node";
add(new Plugin());

제거

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

import { remove } from "@amplitude/analytics-node";
remove(plugin.name);

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

• plugin.setup()
  • 설명: 선택 사항입니다. setup 함수는 플러그인을 추가할 때 또는 첫 번째 초기화 중 더 나중에 발생하는 시점에 호출되는 선택적 메서드입니다. 이 함수는 1) Amplitude 구성과 2) Amplitude 인스턴스의 두 가지 매개변수를 허용합니다. Amplitude 구성 또는 인스턴스에 종속되는 설정 운영 및 작업을 위해 이를 사용하십시오. 예를 들어 변수에 기준선 값을 할당하거나 이벤트 리스너 설정을 비롯한 다양한 작업을 수행할 수 있습니다.
• plugin.execute()
  • 설명:
    • 유형:보강에 대한 선택 사항입니다. 보강 플러그인의 경우, execute 함수는 각 이벤트에서 호출되는 선택적 메소드입니다. 이 함수는 새 이벤트를 반환해야 합니다. 그렇지 않으면 SDK가 전달된 이벤트를 큐에서 삭제합니다. 이벤트에서 속성을 추가 또는 제거하거나, 이벤트를 필터링하거나, 추적된 각 이벤트에 대해 전체 작업을 수행해야 하는 경우에 이를 사용하십시오.
    • 목적지 플러그인의 경우 execute 함수는 각 이벤트에서 호출되는 필수 메서드입니다. 이 함수는 event(BaseEvent), code(숫자) 및 message(문자열) 키를 가진 응답 객체를 반환해야 합니다. 이를 사용하여 타사 엔드포인트에 이벤트를 전송할 수 있습니다.

플러그인 예제

import { init, add } from '@amplitude/analytics-node';
import { NodeConfig, EnrichmentPlugin, Event, PluginType } from '@amplitude/analytics-types';
export class AddEventIdPlugin implements EnrichmentPlugin {
  name = 'add-event-id';
  type = PluginType.ENRICHMENT as const;
  currentId = 100;
  config?: NodeConfig;
  /**
   * setup() is called on plugin installation
   * example: client.add(new AddEventIdPlugin());
   */
  async setup(config: NodeConfig): Promise<undefined> {
     this.config = config;
     return;
  }
  /**
   * execute() is called on each event instrumented
   * example: client.track('New Event');
   */
  async execute(event: Event): Promise<Event> {
    event.event_id = this.currentId++;
    return event;
  }
}
init('API_KEY');
add(new AddEventIdPlugin());

사용자 지정 HTTP 클라이언트

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

import { Transport } from '@amplitude/analytics-types';
class MyTransport implements Transport {
 async send(serverUrl: string, payload: Payload): Promise<Response | null> {
 // check example: https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/analytics-client-common/src/transports/fetch.ts
 }
}
amplitude.init(API_KEY, {
 transportProvider: new MyTransport(),
});