Node.js Ampli Wrapper

Ampliは、JavaScript(ES6以降)とTypeScript(2.1以降)で記述されたNode.jsアプリをサポートしています。Ampliは生成されたトラッキングライブラリをCJSモジュールとしてパッケージ化します。

クイックスタート

1. （前提条件）Amplitudeデータでトラッキングプランを作成する

   Amplitudeデータでイベントやプロパティを計画しましょう。

2. Amplitude SDKをインストールする

   bash

   Copy

   npm install @amplitude/analytics-node
   

3. Ampli CLIをインストールする

   bash

   Copy

   npm install -g @amplitude/ampli
   

4. Ampliラッパーをプロジェクトに組み込む

   bash

   Copy

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

5. Ampliラッパーを初期化する

   js

   API keyCopy

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

6. ユーザーを識別し、ユーザープロパティを設定する

   js

   Copy

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

7. 強力に型付けされたメソッドとクラスを使用してイベントを追跡する

   js

   Copy

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

8. アプリケーション終了前のイベントのフラッシュ

   js

   Copy

   ampli.flush();
   

9. CLIを使用して実装ステータスを確認する

   shell

   Copy

   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",
});

オプションの引数を使用すると、この呼び出しのAmplitudeフィールド（deviceIdなど）を渡すことができます。

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

グループ

ユーザーをグループ（部署や会社など）に関連付けるには、setGroup()を呼び出します。setGroup()関数にはgroupTypeとgroupNameが必要です。

ampli.client.setGroup("groupType", "groupName");

Amplitudeはユーザーをグループに割り当て、それらのグループに対して「ユニーク数」などのクエリを実行します。グループの少なくとも1人のメンバーが特定のイベントを実行した場合、そのグループもカウントに含まれます。

たとえば、orgId を使用してユーザーを組織ごとにグループ化したいとします。 ジョーはorgIdが10のグループに所属し、スーはorgIdが15のグループに所属しています。SueとJoeはどちらも特定のイベントを実行します。 イベントセグメンテーションチャートでその組織をクエリできます。

グループを設定する際には、groupTypeとgroupNameを定義してください。上記の例では、orgIdはgroupTypeであり、10および15はgroupNameの値です。groupTypeのもう1つの例としては、sportがあり、そのgroupName値としてはtennisやbaseballがあります。

グループを設定すると、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引数はイベントプロパティを渡します。

options引数は、price、quantity、revenueなどのAmplitudeフィールドを渡します。

たとえば、次のコードでは、トラッキングプランにsongPlayedというイベントが含まれています。このイベントにはsongIdおよびsongFavoritedという2つの必須プロパティがあります。songIdのプロパティタイプは文字列で、songFavoritedはブール値です。

このイベントはAmplitudeフィールドを1つ定義します：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
});

Ampli trackを使用してイベントオブジェクトを追跡します：

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

フラッシュ

Ampliラッパーはイベントをキューに入れ、設定に基づく間隔で送信します。

保留中のイベントをすぐに送信するには、flush()を呼び出します。

flush()メソッドは、Promiseを返します。このPromiseは、Ampliが処理を続行する前にすべての保留中のイベントを確実に送信するために使用できます。アプリケーションを終了する前に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（レガシー）から移行する

以下の手順に従って、@amplitude/analytics-node用のAmpliから@amplitude/node用のAmpliに移行します。

1. ソースランタイムを更新します。

   Webアプリで、「ソース」ページを開き、更新するNode.jsソースを選択します。モーダルで、ランタイムをTypeScript (Legacy)からTypeScriptに変更するか、またはJavaScript (Legacy)からJavaScriptに変更します。

2. 詳細なセットアップと使用方法については、このページの手順に従ってください。

3. プロジェクトからレガシーな依存関係を削除します。

yarn remove @amplitude/node

4. 新しい依存関係を追加します。

yarn add @amplitude/analytics-node

5. 最新のAmpli Wrapperをプルしてください。

ampli pull

6. 検索と置換。

   Amplitudeはミドルウェアをサポートしなくなりました。新しいプラグインアーキテクチャへと置き換えられました。ミドルウェアからプラグインへの移行。