Node.js 앰플리 래퍼

Ampli는 JavaScript(ES6 이상)와 TypeScript(2.1 이상)로 작성된 Node.js 앱을 지원합니다. Ampli는 생성된 추적 라이브러리를 CJS 모듈로 패키징합니다.

빠른 시작

1. (전제 조건) Amplitude 데이터에 추적 계획 생성

   Amplitude 데이터에서 이벤트와 속성을 계획하십시오.

2. Amplitude SDK 설치

   bash

   복사

   npm install @amplitude/analytics-node
   

3. Ampli CLI 설치

   bash

   복사

   npm install -g @amplitude/ampli
   

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

   bash

   복사

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

5. Ampli 래퍼 초기화

   js

   API 키복사

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

6. 사용자 식별 및 사용자 속성 설정

   js

   복사

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

7. 강력하게 유형화된 메소드 및 클래스를 사용하여 이벤트 추적

   js

   복사

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

8. 애플리케이션 종료 전 이벤트 플러시

   js

   복사

   ampli.flush();
   

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

   shell

   복사

   ampli status [--update]
   

Amplitude SDK 설치

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

npm install @amplitude/analytics-node

Ampli CLI 설치

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

brew tap amplitude/ampli
brew install ampli

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

Ampli CLI pull 명령을 실행하여 Amplitude 데이터에 로그인하고 추적 계획에 맞게 강력한 형식의 Ampli 래퍼를 다운로드하십시오. 프로젝트 루트 디렉토리에서 Ampli CLI 명령을 실행하십시오.

ampli pull

API

Ampli는 편리한 메서드를 제공하는 Amplitude SDK 위에 얇은 퍼사드를 생성합니다. 또한 Ampli 래퍼는 ampli.client를 통해 기본 Amplitude SDK의 모든 메서드에 대한 액세스를 허용합니다. 자세한 내용은 Amplitude SDK 래핑을 참조하십시오.

로드

코드에서 Ampli를 초기화하십시오. load() 함수는 SDK의 동작을 구성하기 위해 옵션 객체를 받아들입니다.

다음 예제에서는 기본 구성을 재정의하기 위해 load를 초기화합니다.

ampli.load({
  client: {
    apiKey: AMPLITUDE_API_KEY,
    configuration: {
      minIdLength: 10,
    },
  },
});

Identify

앱에서 사용자를 식별하고 향후 발생할 모든 이벤트를 해당 사용자의 ID와 연관시키거나 해당 속성을 설정하기 위해 identify()을 호출하십시오.

Ampli 래퍼는 이벤트와 해당 속성에 대한 타입을 생성하는 것과 마찬가지로 사용자 속성에 대한 타입을 생성합니다.

identify() 함수는 선택 사항인 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.client.setGroup("groupType", "groupName");

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

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

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

그룹을 설정하면 groupType:groupName도 사용자 속성으로 설정됩니다. Amplitude는 해당 사용자의 groupType에 대한 기존 groupName 값과 그에 해당하는 사용자 속성 값을 덮어씁니다. groupType는 문자열입니다. groupName는 사용자가 여러 그룹에 속해 있음을 나타내는 문자열 또는 문자열 배열일 수 있습니다. 예를 들어 Joe가 orgId 10 및 20에 속해 있다면, groupName는 [10, 20]입니다.

코드는 다음과 같을 수 있습니다.

ampli.client.setGroup("orgId", ["10", "20"]);

추적

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

ampli.eventName(properties: EventNameProperties, options: EventOptions)

properties인수는 이벤트 속성을 전달합니다.

price 인수는 quantity, revenue 및 options과 같은 Amplitude 필드를 전달합니다.

예를 들어 다음 코드에서 추적 계획에는 songPlayed이라는 이벤트가 포함되어 있습니다. 이벤트에는 두 가지 필수 속성이 있습니다. songId 및 songFavorited. songId의 속성 유형은 문자열이며 songFavorited는 부울입니다.

이 이벤트는 Amplitude 필드를 정의합니다: deviceId. Amplitude 필드에 대한 자세한 내용은 HTTP V2 API 이벤트 배열 키 참조를 참조하십시오.

ampli.songPlayed(
  {
    songId: "songId", // string,
    songFavorited: true, // boolean
  },
  {
    deviceId: "a-device-id",
  },
);

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

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

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

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

플러시

Ampli 래퍼는 이벤트를 대기열에 넣고 구성에 따라 간격으로 이벤트를 전송합니다.

보류 중인 전체 이벤트를 즉시 전송하려면 flush()를 호출하십시오.

이 flush() 메서드는 계속하기 전에 보류 중인 모든 이벤트가 전송되도록 보장하는 데 사용할 수 있는 promise를 반환합니다. 애플리케이션을 종료하기 전에 flush()를 호출하십시오.

ampli.flush();

플러그인

플러그인은 Amplitude 동작을 확장합니다. 예를 들어 플러그인은 이벤트 속성(보강 유형)을 수정하거나 타사 API(목적지 유형)로 전송할 수 있습니다.

먼저, 플러그인을 정의합니다.

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

Ampli를 초기화한 후 플러그인을 추가하십시오.

ampli.client.add(new AddEventIdPlugin());

Ampli CLI

풀(Pull)

pull 명령은 Ampli 래퍼 코드를 프로젝트에 다운로드합니다. 프로젝트 루트에서 pull 명령을 실행합니다.

ampli pull

메시지가 나타나면 작업 공간에 로그인한 다음 소스를 선택합니다.

➜ 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 pull을 참조하십시오.

상태

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

자세한 내용은 ampli status을 참조하십시오.

@amplitude/node 런타임을 위해 Ampli(레거시)에서 마이그레이션

다음 단계에 따라 Ampli for @amplitude/node에서 Ampli for @amplitude/analytics-node로 마이그레이션하십시오.

1. 소스 런타임을 업데이트합니다.

   웹 앱에서 소스 페이지를 열고 업데이트할 Node.js 소스를 선택합니다. 모달에서 런타임을 TypeScript (Legacy)에서 TypeScript로 또는 JavaScript (Legacy)에서 JavaScript로 변경합니다.

2. 자세한 설정 및 사용 지침을 보려면 이 페이지의 단계를 따르십시오.

3. 프로젝트에서 기존 종속성을 제거합니다.

yarn remove @amplitude/node

4. 새 종속성을 추가합니다.

yarn add @amplitude/analytics-node

5. 최신 Ampli 래퍼를 가져오십시오.

ampli pull

6. 찾아 교체하십시오.

   Amplitude는 더 이상 미들웨어를 지원하지 않습니다. 새로운 플러그인 아키텍처가 대체합니다. 미들웨어에서 플러그인으로 마이그레이션합니다.