Javascript SDK用Ampli

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

Ampliはデータで定義されたイベントとプロパティにオートコンプリート機能を提供し、コード内でイベントスキーマを強制的に適用することで、不正なインストルメンテーションを防ぎます。

Amplitudeデータは、JavaScript（ES6以上）およびTypeScript（2.1以上）で記述されたブラウザアプリからのアナリティクスイベントの追跡をサポートしています。Ampliは生成されたトラッキングライブラリをCJSモジュールとしてパッケージ化します。

クイックスタート

（前提条件）Amplitudeデータでトラッキングプランを作成する
Amplitudeデータでイベントやプロパティを計画しましょう。
Amplitude SDKをインストールする

shell

npm install amplitude-js@^8.21.0

Ampli CLIをインストールする

shell

npm install -g @amplitude/ampli

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

shell

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

Ampliラッパーを初期化する

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

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

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

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

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

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

ampli.flush();

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

shell

ampli status [--update]

Amplitude SDKをインストールする

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

npm install amplitude-js@^8.21.0

ブラウザでAmpliを使用する場合、Amplitudeでは、JavaScriptスニペットではなくモジュールとしてamplitude-js@^8.21.0をロードすることを推奨します。

Ampli CLIをインストールする

Ampli CLIは、HomebrewまたはNPMからインストールできます。

brew tap amplitude/ampli
brew install ampli

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

Ampli CLI pullコマンドを実行してAmplitudeデータにログインし、トラッキングプラン用の強く型付けされたAmpliラッパーをダウンロードしてください。プロジェクトのルートディレクトリからAmpli CLIコマンドを実行します。

bash

ampli pull

API

Ampliは、便利なメソッドを提供するAmplitude SDK上に薄いファサードを生成します。また、Ampliラッパーは、ampli.clientを通じて、基盤となるAmplitude SDKのすべてのメソッドへのアクセスも提供します。詳細については、Amplitude SDKのラッピングを参照してください。

ロード

コードでAmpliを初期化します。load()関数には、SDKの動作を設定するためにオプションオブジェクトが必要です。

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

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.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もユーザープロパティとして設定され、そのユーザーのgroupTypeに設定されている既存のgroupNameの値と対応するユーザープロパティ値が上書きされます。groupTypeは文字列であり、groupNameにはユーザーが複数のグループに属していることを示す文字列または文字列の配列のいずれかを指定できます。たとえば、JoeがorgId、10および20に属する場合、groupNameは[10, 20]になります。

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

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

追跡

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

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

properties引数はイベントプロパティを渡します。

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

たとえば、次のコードでは、トラッキングプランにsongPlayedというイベントが含まれています。このイベントにはsongIdおよびsongFavoritedという2つの必須プロパティがあります。songIdのプロパティタイプはstringで、songFavoritedはブール値です。このイベントはまた、AmplitudeフィールドであるdeviceIdも定義します。詳細については、Amplitudeフィールドを参照してください。

ampli.songPlayed(
  {
    songId: "songId", // string,
    songFavorited: true, // boolean
  },
  {
    deviceId: "a-device-id",
  },
  {
    myMiddleware: { myMiddlewareProp: "value to send to middleware" },
  },
);

また、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()を呼び出します。

typescript

ampli.flush();

Ampli CLI

Pull

pullコマンドはAmpliラッパーコードをプロジェクトにダウンロードします。プロジェクトのルートからpullコマンドを実行します。

bash

ampli pull

プロンプトが表示されたらワークスペースにログインし、ソースを選択します。

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 pullを参照してください。

ステータス

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

詳細については、ampli statusを参照してください。

これは役に立ちましたか？