On this page

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

Ampli for Node SDK

Ampliラッパーは、強く型付けされた生成APIであり、Amplitudeデータ内のトラッキングプランに基づいてアナリティクスイベントをトラッキングします。トラッキングライブラリは、チームのトラッキングプラン内のすべてのイベントの関数を公開します。関数の引数は、イベントのプロパティに対応します。

Ampliは、データで定義されたイベントとプロパティの自動補完機能を提供し、コード内でイベントスキーマを強制して不良な計測を防ぐことでアプリにメリットをもたらします。

JavaScriptのリアルタイム型チェックを有効にする

JavaScriptは型セーフな言語ではないため、TypeScriptのように静的型チェックは組み込まれていません。一般的な IDE の中には、JSDoc に基づく JavaScript でのリアルタイムの型チェックを許可しているものもあります。

より良い開発体験を提供するために、Ampli はすべてのメソッドとクラスに対して JSDoc を生成します。

VSCodeでJavaScriptのリアルタイム型チェックを有効にするには：

  1. 環境設定 > 設定に移動し、checkJsを検索します。
  2. JS/TS > 暗黙プロジェクト設定 > JSを確認を選択します。

この設定を有効化すると、タイプエラーは IDE に直接表示されます。

Jetbrainsも同様のサポートを提供しています：

  1. 環境設定 > エディタ > 検査 > JavaScript と TypeScript > 一般 に移動します。
  2. **「署名不一致」と「タイプ不一致」で、必要な厳密さに基づいて「重大度」**を「警告」または「エラー」に設定します。

Prettierによるリンティング

eslintとtslintのリンティングエラーを防ぐために、SDKが生成したファイルにはリンターを無効にするための以下の記述が含まれています。

/* tslint:disable */

/* eslint-disable */

Prettierには、これに対応する「コード内」の機能はありません。代わりに、生成されたpath/to/ampliを.prettierignoreファイルに追加してください。パスはampli pullを使用することで取得できます。詳細については、Prettierのドキュメントを参照してください。

クイックスタート

  1. （前提条件）Amplitudeデータで追跡計画を作成します。

  2. Amplitude SDKをインストールします。

bash
npm install @amplitude/node@^1.10.2 @amplitude/identify@^1.10.2 @amplitude/types@^1.10.2
  1. Ampli CLI をインストールします。
bash
npm install -g @amplitude/ampli
  1. Ampli Wrapperのプロジェクトへのプル。
bash
ampli pull [--path ./src/ampli]
  1. Ampli Wrapperを初期化します。
js
import { ampli } from "./src/ampli";
ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });
  1. ユーザーを識別し、ユーザープロパティを設定します。
js
ampli.identify("user-id", {
  userProp: "A trait associated with this user",
});
  1. 強力に型付けされたメソッドとクラスを使用してイベントを追跡します。
js
ampli.songPlayed('ampli-user-id', { songId: 'song-1' });
ampli.track('ampli-user-id', new SongPlayed({ songId: 'song-2' });
  1. アプリケーション終了前にイベントをフラッシュします。
js
ampli.flush();
  1. CLI を使用して実装ステータスを確認します。
bash
ampli status [--update]

SDKをインストールする

まだインストールしていない場合は、コアとなるAmplitude SDKの依存関係をインストールしてください。

bash
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 CLIpullコマンドを実行してAmplitudeデータにログインし、トラッキングプラン用の強力な型付きAmpli Wrapperをダウンロードしてください。

bash
ampli pull

CLIは、ワークスペースにログインしてソースを選択するように求めるメッセージを表示します。

bash
➜ 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の動作を設定するためにオプションオブジェクトが必要です。

オプションタイプ必須概要
disabledBooleanオプションAmpliラッパーが何らかの処理を実行するかどうかを指定します。trueの場合、Ampliラッパーへのすべての呼び出しはno-opになります。ローカル環境や開発環境で役立ちます。デフォルトはfalseです。
client.instanceAmplitudeClientclient.apiKeyが設定されていない場合は必須ですAmplitudeインスタンスを指定します。デフォルトでは、Ampliはユーザーのためにインスタンスを作成します。
client.apiKeyStringclient.instanceが設定されていない場合は必須ですAPIキーを指定します。このオプションは、デフォルト値であるトラッキングプランで設定されたAPIキーを上書きします。
client.optionsAmplitude.OptionsオプションAmplitudeClientのデフォルト設定を上書きします。

Identify

ユーザープロパティを設定するにはidentify()を呼び出します。Ampliは、イベントやイベントプロパティと同じように、ユーザープロパティにもタイプを作成します。

identify()関数はオプションのuserId、オプションユーザーのproperties、オプションのoptionsを受け入れます。

たとえば、トラッキングプランにroleというユーザープロパティが含まれているとします。プロパティのタイプは文字列です。

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

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

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

グループ

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

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

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

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

グループを設定する際には、groupTypeとgroupNameを定義してください。 前の例では、「orgId」は groupType であり、「10」と「15」は groupName の値です。 groupTypeのもう1つの例は'sport'で、groupNameの値には'tennis'や'baseball'などがあります。

グループを設定すると、groupType:groupNameがユーザープロパティとして設定され、そのユーザーのgroupTypeに既存するgroupNameの値もすべて上書きされます。groupTypeは文字列です。groupNameは、ユーザーが複数のグループに属していることを示す文字列または文字列の配列にすることができます。

たとえば、Joeが「orgId」の「10」と「20」に所属している場合、groupNameは「[10, 20]」となります。

コードは次のようになります：

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

追跡

イベントを追跡するには、そのイベントに対応する関数を呼び出します。 トラッキングプラン内のすべてのイベントには、Ampliラッパー内にそれぞれ専用の関数が生成されます。この呼び出しは次の構造を使用します。

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

userId：マルチテナントのサーバー環境では、イベントをユーザーに関連付けるために、各トラッキングコールにuserIdを指定する必要があります。

properties：トラッキングプラン内のこのイベントに固有のイベントプロパティを渡します。

options引数を使用すると、price、quantityおよびrevenueなどのAmplitudeフィールドを渡すことができます。

extra引数を使用すると、データをミドルウェアに渡すことができます。

たとえば、トラッキングプランには「再生された曲」というイベントが含まれています。 SDKは、名前を有効なJavaScriptにするために、キャメルケースを使用して、このイベントのsongPlayed関数を生成します。このイベントにはsongIdおよびsongFavoritedという2つの必須プロパティがあります。songIdのプロパティタイプは文字列で、songFavoritedはブール値です。

このイベントにはpriceとquantityという2つのAmplitudeフィールドがあります。Amplitudeフィールドの詳細についてはこちらをご覧ください。このイベントには1つのMiddlewareExtraがあります：myMiddleware。ミドルウェアについて詳しく知る。

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

また、Ampli はイベントごとにクラスを生成します。

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

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

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

フラッシュ

Ampli Wrapper はイベントをキューに入れ、設定に基づく間隔で送信します。 Ampliは、flushQueueSizeまたはflushIntervalがしきい値に達すると自動的にバッファをフラッシュするため、通常の運用ではflush()を呼び出す必要はありません。

保留中のイベントをすぐに送信するには、flush()を呼び出します。このflush()メソッドはPromiseを返します。このPromiseは、Ampliが処理を続行する前にすべての保留中のイベントを確実に送信するために使用できます。これはアプリケーションが終了する前に役立ちます。

js
ampli.flush();

ステータス

次のstatusコマンドを使用して、コードがすべての追跡イベントを実装していることを確認してください。

bash
ampli status [--update]

出力にはステータスと、欠落しているイベントが示されます。

bash
➜ 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

Was this helpful?