노드 SDK용 Ampli

Ampli 래퍼는 Amplitude 데이터의 추적 계획을 기반으로 분석 이벤트를 추적하기 위해 생성되고 강력하게 유형화된 API입니다. 추적 라이브러리는 팀의 추적 계획에 있는 모든 이벤트에 대한 함수를 제공합니다. 함수의 인수는 이벤트의 속성에 해당합니다.

Ampli는 데이터에 정의된 이벤트와 속성에 대한 자동 완성을 제공하고 코드에서 이벤트 스키마를 적용하여 잘못된 계측을 방지함으로써 앱에 이점을 줄 수 있습니다.

빠른 시작

1. (전제 조건) Amplitude 데이터에서 추적 계획을 생성합니다.

2. Amplitude SDK를 설치합니다.

npm install @amplitude/node@^1.10.2 @amplitude/identify@^1.10.2 @amplitude/types@^1.10.2

3. Ampli CLI를 설치합니다.

npm install -g @amplitude/ampli

4. Ampli 래퍼를 여러분의 프로젝트에 가져옵니다.

ampli pull [--path ./src/ampli]

5. Ampli 래퍼를 초기화합니다.

import { ampli } from "./src/ampli";
ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });

6. 사용자를 식별하고 사용자 속성을 설정합니다.

ampli.identify("user-id", {
  userProp: "A trait associated with this user",
});

7. 강력하게 유형화된 메서드와 클래스를 사용하여 이벤트를 추적합니다.

ampli.songPlayed('ampli-user-id', { songId: 'song-1' });
ampli.track('ampli-user-id', new SongPlayed({ songId: 'song-2' });

8. 애플리케이션이 종료되기 전에 이벤트를 플러시합니다.

ampli.flush();

9. CLI를 사용하여 구축 상태를 확인합니다.

ampli status [--update]

SDK 설치

아직 설치하지 않은 경우 핵심 Amplitude SDK 의존성을 설치하십시오.

npm install @amplitude/node@^1.10.2 @amplitude/identify@^1.10.2 @amplitude/types@^1.10.2

Ampli 설치

Ampli CLI는 Homebrew 또는 NPM에서 설치할 수 있습니다.

npm install -g @amplitude/ampli

Ampli 래퍼를 프로젝트에 가져오십시오

프로젝트 루트에서 Ampli CLI pull명령을 실행하여 Amplitude 데이터에 로그인한 후 추적 계획에 맞게 강력하게 지정된 Ampli 래퍼를 다운로드하십시오.

ampli pull

CLI는 작업 공간에 로그인하고 소스를 선택하라는 메시지를 표시합니다.

➜ ampli pull
Ampli project is not initialized. No existing `ampli.json` configuration found.
? Create a new Ampli project here? Yes
? Organization: Amplitude
? Workspace: My Workspace
? Source: My Source

Ampli 초기화

코드에서 Ampli를 초기화하십시오.

import { ampli } from "./ampli";
ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });

load() 함수는 SDK의 동작을 구성하기 위해 옵션 객체를 필요로 합니다.

Identify

사용자 속성을 설정하려면 identify()호출하십시오. Ampli는 이벤트 및 이벤트 속성과 마찬가지로 사용자 속성에 대한 유형을 생성합니다.

identify() 함수는 선택적 properties, 선택적 사용자 userId및 선택적 options을 허용합니다.

예를 들어 추적 계획에 role라는 사용자 속성이 포함되어 있습니다. 속성의 유형은 문자열입니다.

ampli.identify("user-id", {
  role: "Admin",
});

options 인수를 사용하면 이 호출에 대해 Amplitude 필드를 전달할 수 있습니다(예: deviceId).

ampli.identify(
  "user-id",
  {
    role: "admin",
  },
  {
    deviceId: "my-device-id",
  },
);

그룹

사용자를 해당 그룹(예: 해당 부서 또는 회사)과 연결하기 위해 setGroup()을 호출합니다. setGroup() 함수는 필수 groupType 및 groupName을 받아들입니다.

ampli.setGroup("user-id", "Group name", "Group Value");

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

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

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

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

ampli.setGroup("user-id", "orgId", ["10", "20"]);

추적

이벤트를 추적하려면 이벤트에 해당하는 함수를 호출하십시오. 추적 계획의 모든 이벤트는 Ampli 래퍼에서 고유한 함수를 갖습니다. 호출은 다음 구조를 사용합니다.

ampli.eventName(
 userId: string | undefined,
 properties: EventProperties,
 options: EventOptions,
 extra: MiddlewareExtra
)

userId: 멀티 테넌트, 서버 환경에서 이벤트를 사용자와 연결하려면 각 추적 호출에 대해 userId를 제공해야 합니다.

properties: 추적 계획에서 이 이벤트에 특정한 이벤트 속성을 전달합니다.

options 인수를 사용하면 price, quantity, revenue와 같은 Amplitude 필드를 전달할 수 있습니다.

이 extra 인수를 사용하면 데이터를 미들웨어에 전달할 수 있습니다.

예를 들어 추적 계획에는 Song Played라는 이벤트가 포함되어 있습니다. SDK는 이름이 유효한 JavaScript가 되도록 카멜 케이스를 사용하여 이벤트에 대한 songPlayed함수를 생성합니다. 이벤트에는 두 가지 필수 속성이 있습니다. songId 및 songFavorited. songId의 속성 유형은 문자열이며 songFavorited는 부울입니다.

이 이벤트에는 두 개의 Amplitude 필드가 있습니다: price 및 quantity. Amplitude 필드에 대해 자세히 알아보십시오. 이 이벤트에는 하나의 MiddlewareExtra: myMiddleware가 있습니다. 미들웨어에 대해 더 알아보십시오.

ampli.songPlayed(
  "ampli-user-id",
  {
    songId: "songId", // string,
    songFavorited: true, // boolean
  },
  {
    price: 1.23,
    quantity: 2,
  },
  {
    myMiddleware: { myMiddlewareProp: "value to send to middleware" },
  },
);

또한 Ampli는 각 이벤트에 대한 클래스를 생성합니다.

const myEventObject = new SongPlayed({
  songId: "songId", // string,
  songFavorited: true, // boolean
});

Amplitrack를 사용하여 이벤트 객체 추적:

ampli.track(
  "ampli-user-id",
  new SongPlayed({
    songId: "songId", // string,
    songFavorited: true, // boolean
  }),
);

플러시

Ampli 래퍼는 이벤트를 큐에 넣고 구성에 따라 일정한 간격으로 이벤트를 전송합니다. Ampli는 flushQueueSize 또는 flushInterval이 해당 임계값에 도달할 때 자동으로 버퍼를 플러시하므로 정상적인 작동을 위해 flush()를 호출할 필요가 없습니다.

보류 중인 전체 이벤트를 즉시 전송하려면 flush()를 호출하십시오. 이 flush() 메서드는 계속하기 전에 Ampli가 모든 보류 중인 이벤트를 전송하도록 보장하는 데 사용할 수 있는 Promise를 반환합니다. 이 기능은 응용 프로그램을 종료하기 전에 유용합니다.

ampli.flush();

상태

다음 status명령을 사용하여 코드가 모든 추적된 이벤트를 구현하는지 확인하십시오.

ampli status [--update]

출력에는 상태가 표시되고 누락된 이벤트가 표시됩니다.

➜ ampli status
✘ Verifying event tracking implementation in source code
 ✔ Song Played (1 location)
 ✘ Song Stopped Called when a user stops playing a song.
Events Tracked: 1 missed, 2 total