Ampli
AmpliはAmplitudeデータのアナリティクストラッキングプランに基づいてAmplitude SDK用の軽量ラッパーを動的に生成するため、イベントトラッキングが簡単になり、エラーが発生しにくくなります。
このドキュメントでは、Ampliの概要について説明しています。詳細については、Amplitude アカデミーをご覧ください。
主な記事
Ampliラッパーは、イベント名とプロパティ値を厳密に適用することで、ヒューマンエラーを防ぐためのタイプとメソッドを提供します。ラッパーコードにより、トラッキングプラン内のすべてのイベントとプロパティのオートコンプリートが可能になり、開発時とコンパイル時の静的型チェックも可能になります。
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と比較してみましょう。手入力された値を使用してイベントを送信すると、データ品質の問題が発生する可能性があり、データ管理者とエンジニア間の緊密な連携が必要です。
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ラッパーを生成して、イベントのインストルメンテーションステータスを検証することができます。これにより、イベントトラッキングコールを見逃したかどうかを簡単に把握できるようになるため、実装が完了しているという確信が得られます。
➜ 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ラッパーをダウンロードします。
ampli pull [source-name] [--path ./path/for/generated/ampli/wrapper]
AmpliラッパーはAmplitudeデータの特定のソースに接続します。オプションで、ソース名をパラメータとして指定できます。 そうでない場合、Ampliはいずれかを選択するよう求めるメッセージを表示します。
? Select a Source: web
ソース上で初めてampli pullを実行するとき、Ampliは開発言語と基盤となるAmplitude SDKを選択するよう求めます。後でソース設定を変更するには、ampli configureを実行して、別のプラットフォーム、言語、またはAmplitude SDKを選択してください。
? Select a platform: Browser
? Select a language: TypeScript
? Select a SDK: @amplitude/analytics-browser@^1.0 (recommended)
その後、Ampliは生成されたAmpliラッパーを指定されたパスで使用できるようにします。パスを指定しない場合、Ampli CLIはソースのプラットフォームに基づいてデフォルト値を選択します。
✔ Tracking library generated successfully.
↳ Path: ./ampli
イベント計測の検証
ampli statusを実行すると、プロジェクトディレクトリ内のソースコードがスキャンされ、ampli.songPlayed({ ... })などのイベントトラッキングコールがないかが確認されます。各イベントを検出した回数を出力します。
➜ ampli status
✔ Verifying event tracking implementation in source code
✔ Song Played (1 location)
✔ All events tracked: 1 found, 1 total
プロジェクトが実装していないイベントをトラッキングプランに含めると、ampli statusはエラーを返します。たとえば、新しいイベントSong Favoritedをトラッキングプランに追加したものの、プロジェクトではそれをインストルメンテーションしていない場合などにこのエラーが発生します。
➜ 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())を提供します。
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インスタンスを使用します。
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のすべての設定オプションをサポートしています。
ampli.load({
client: { apiKey: AMPLITUDE_API_KEY, configuration: { serverZone: "EU" } },
});
Ampliラッパーをプロジェクトに追加してイベントを追跡する
Ampli CLIを使用してAmpliラッパーをダウンロードします。
ampli pull [--path ./ampli]
ダウンロードしたソースコードをpathおよびampli.jsonに追加し、リポジトリとソースコントロールに追加します。
git add ./ampli ampli.json
git commit -m "Added Ampli wrapper"
ソース用に選択したAmplitude SDKに応じて、対応する依存関係をインストールします。
npm install @amplitude/analytics-browser
Ampli Wrapper を ampli pull からダウンロードし、依存関係をインストールしたら、それを使用してコード内のイベントを追跡します。
import { ampli, SongPlayed } from "./ampli";
ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });
ampli.songPlayed({ title: "Happy Birthday" });
ampli.flush();
Ampli CLIを使用して、プロジェクト内のAmpliラッパーのインストルメンテーション状態を確認します。
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.