Ampli

AmpliはAmplitudeデータのアナリティクストラッキングプランに基づいてAmplitude SDK用の軽量ラッパーを動的に生成するため、イベントトラッキングが簡単になり、エラーが発生しにくくなります。

このドキュメントでは、Ampliの概要について説明しています。詳細については、Amplitude アカデミーをご覧ください。

主な記事

Ampliがトラッキングプランから型付きラッパーを生成する図

Ampliラッパーは、イベント名とプロパティ値を厳密に適用することで、ヒューマンエラーを防ぐためのタイプとメソッドを提供します。ラッパーコードにより、トラッキングプラン内のすべてのイベントとプロパティのオートコンプリートが可能になり、開発時とコンパイル時の静的型チェックも可能になります。

typescript
import { ampli, SongPlayed } from "./ampli";
// Ampli tracks these 2 events as expected.
ampli.songPlayed({ title: "Happy Birthday" });
ampli.track(new SongPlayed({ title: "Song 2" }));
// The following 2 events don't track due to data quality issues.
// Instead, they generate type errors at build time with information
// about the expected property names and types.
// Error: Event 'Song Played' is missing required property 'title'
ampli.songPlayed({ name: "I Knew You Were Trouble" });
// Error: Property 'title' received 'boolean' expected type 'String'
ampli.songPlayed({ title: true });

これを汎用Amplitude SDKと比較してみましょう。手入力された値を使用してイベントを送信すると、データ品質の問題が発生する可能性があり、データ管理者とエンジニア間の緊密な連携が必要です。

typescript
import * as amplitude from "@amplitude/analytics-browser";
// Amplitude tracks these 2 events as expected
amplitude.track("Song Played", { title: "Happy Birthday" });
amplitude.track({
  event_type: "Song Played",
  event_properties: { title: "Song 2" },
});
// Amplitude tracks the following 2 events, but they have data quality issues
// that make them difficult to include in analysis. Typos and type errors are
// easy to create and hard to find and fix.
// Charts based on 'title' don't include this event, which sets 'name' instead.
amplitude.track("Song Played", { name: "I Knew You Were Trouble" });
// Charts based on event_type='Song Played' don't include this event.
// It also sets 'title' to boolean 'true' instead of the expected type 'String'.
amplitude.track("sonG Playd", { title: true });

Ampli CLIはAmpliラッパーを生成して、イベントのインストルメンテーションステータスを検証することができます。これにより、イベントトラッキングコールを見逃したかどうかを簡単に把握できるようになるため、実装が完了しているという確信が得られます。

shell
➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
✔ All events tracked: 1 found, 1 total

Amplitudeデータ

Amplitude Dataを使用すると、アプリケーション内で追跡したいイベントとプロパティを定義することにより、分析を計画できます。 Ampliでは、Amplitudeデータにトラッキングプランが必要であり、SDKソースにイベントを追加する必要があります。

次の例では、このトラッキングプランを使用しています。

  • webという名前のブラウザSDKソース。
  • タイプ String の必須プロパティtitleを持つイベントSong Played。
  • ソースwebに追加されたイベントSong Played。
  • productionという名前の環境です。

Ampli CLI

Ampli CLIはAmplitudeデータに接続し、指定されたソースのスキーマ情報を使用して、プロジェクト内のAmpliラッパーを生成および検証します。

Ampli CLIをインストールする

brew tap amplitude/ampli
brew install ampli

Ampliラッパーの生成

ampli pullを実行すると、Amplitudeデータに接続し、トラッキングプラン用にAmpliラッパーをダウンロードします。

shell
ampli pull [source-name] [--path ./path/for/generated/ampli/wrapper]

AmpliラッパーはAmplitudeデータの特定のソースに接続します。オプションで、ソース名をパラメータとして指定できます。 そうでない場合、Ampliはいずれかを選択するよう求めるメッセージを表示します。

shell
? Select a Source: web

ソース上で初めてampli pullを実行するとき、Ampliは開発言語と基盤となるAmplitude SDKを選択するよう求めます。後でソース設定を変更するには、ampli configureを実行して、別のプラットフォーム、言語、またはAmplitude SDKを選択してください。

shell
? Select a platform: Browser
? Select a language: TypeScript
? Select a SDK: @amplitude/analytics-browser@^1.0 (recommended)

その後、Ampliは生成されたAmpliラッパーを指定されたパスで使用できるようにします。パスを指定しない場合、Ampli CLIはソースのプラットフォームに基づいてデフォルト値を選択します。

shell
✔ Tracking library generated successfully.
  ↳ Path: ./ampli

イベント計測の検証

ampli statusを実行すると、プロジェクトディレクトリ内のソースコードがスキャンされ、ampli.songPlayed({ ... })などのイベントトラッキングコールがないかが確認されます。各イベントを検出した回数を出力します。

shell
➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
✔ All events tracked: 1 found, 1 total

プロジェクトが実装していないイベントをトラッキングプランに含めると、ampli statusはエラーを返します。たとえば、新しいイベントSong Favoritedをトラッキングプランに追加したものの、プロジェクトではそれをインストルメンテーションしていない場合などにこのエラーが発生します。

shell
➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
  ✘ Song Favorited
✘ ERROR Event tracking incomplete: 1 missed, 2 total

Ampliラッパー

トラッキングプラン用に生成されたSDK

Ampliラッパーは、Amplitude SDKの薄いファサードであり、トラッキングプラン内のすべてのイベントに便利なメソッド(例:ampli.songPlayed())とクラス(例:new SongPlayed())を提供します。

typescript
import { ampli, SongPlayed } from "./ampli";
ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });
ampli.client.setUserId("ampli@amplitude.com");
ampli.songPlayed({ title: "Happy Birthday" });
ampli.track(new SongPlayed({ title: "Song 2" }));
ampli.flush();

Amplitude SDKのラッピング

Ampliラッパーは、ampli.clientを通じて、基盤となるAmplitude SDKインスタンスのすべてのメソッドへのアクセスを提供します。インスタンスを直接設定することも、既存のインスタンスを提供することもできます。 指定しない場合、AmpliはデフォルトのAmplitude SDKインスタンスを使用します。

typescript
import * as amplitude from "@amplitude/analytics-browser";
import { ampli } from "./ampli";
import { CustomPlugin } from "./plugins";
// Initialize the Amplitude SDK instance
amplitude.init(AMPLITUDE_API_KEY);
// Provide the Amplitude SDK instance to Ampli
ampli.load({ client: { instance: amplitude } });
assertEqual(ampli.client, amplitude);
// Call methods directly on the Amplitude SDK
ampli.client.add(CustomPlugin);
ampli.client.setUserId("ampli@amplitude.com");
ampli.client.setGroup("team", "awesome");

基盤となるAmplitude SDKインスタンスを直接作成することなく設定するには、client.configurationをampli.load()に提供します。Ampliは、基盤となるAmplitude SDKのすべての設定オプションをサポートしています。

typescript
ampli.load({
  client: { apiKey: AMPLITUDE_API_KEY, configuration: { serverZone: "EU" } },
});

Ampliラッパーをプロジェクトに追加してイベントを追跡する

Ampli CLIを使用してAmpliラッパーをダウンロードします。

shell
ampli pull [--path ./ampli]

ダウンロードしたソースコードをpathおよびampli.jsonに追加し、リポジトリとソースコントロールに追加します。

shell
git add ./ampli ampli.json
git commit -m "Added Ampli wrapper"

ソース用に選択したAmplitude SDKに応じて、対応する依存関係をインストールします。

shell
npm install @amplitude/analytics-browser

Ampli Wrapper を ampli pull からダウンロードし、依存関係をインストールしたら、それを使用してコード内のイベントを追跡します。

typescript
import { ampli, SongPlayed } from "./ampli";
ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });
ampli.songPlayed({ title: "Happy Birthday" });
ampli.flush();

Ampli CLIを使用して、プロジェクト内のAmpliラッパーのインストルメンテーション状態を確認します。

shell
ampli status

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

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.

このページでは