Ampli for Browser SDK 1.0

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

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

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

クイックスタート

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

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

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

   shell

   コピー

   npm install @amplitude/analytics-browser
   

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

   shell

   コピー

   npm install -g @amplitude/ampli
   

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

   shell

   コピー

   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({ songId: "song-1" });
   ampli.track(new SongPlayed({ songId: "song-2" }));
   

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

   js

   コピー

   ampli.flush();
   

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

   shell

   コピー

   ampli status [--update]
   

Amplitude SDKをインストールする

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

npm install @amplitude/analytics-browser

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」を使用して、ユーザーが所属する組織に基づいてユーザーをグループ化したい場合などです。 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]となります。

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

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ｎフィールドが定義されています：deviceId。詳細については、Amplitudeフィールドを参照してください。

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 {
  BrowserConfig,
  EnrichmentPlugin,
  Event,
} from "@amplitude/analytics-types";
export class AddEventIdPlugin implements EnrichmentPlugin {
  name = "add-event-id";
  type = "enrichment" as const;
  currentId = 100;
  /**
   * setup() is called on plugin installation
   * example: client.add(new AddEventIdPlugin());
   */
  setup(config: BrowserConfig): 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を参照してください。