React Native SDK用のAmpli

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

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

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

クイックスタート

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

shell

npm install @amplitude/analytics-react-native @react-native-async-storage/async-storage

Ampli CLI をインストールします。
shell
```
npm install -g @amplitude/ampli
```
Ampli Wrapperのプロジェクトへのプル。
shell
```
ampli pull [--path ./src/ampli]
```

Ampli Wrapperを初期化します。

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

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

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

強力に型付けされたメソッドとクラスを使用してイベントを追跡します。
js
```
ampli.songPlayed({ songId: "song-1" });
ampli.track(new SongPlayed({ songId: "song-2" }));
```
アプリケーション終了前にイベントをフラッシュします。
js
```
ampli.flush();
```
CLI を使用して実装ステータスを確認します。
shell
```
ampli status [--update]
```

Amplitude SDKをインストールする

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

npm install @amplitude/analytics-react-native @react-native-async-storage/async-storage

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

デフォルト設定を上書きするために、loadで初期化する例を次に示します。

ampli.load({
  client: {
    apiKey: AMPLITUDE_API_KEY,
    configuration: {
      minIdLength: 10,
    },
  },
});

Identify

アプリ内のユーザーを識別し、今後のすべてのイベントをそのユーザーのIDに関連付けるか、ユーザーのプロパティを設定するには、identify()を呼び出します。

Ampli Wrapperがイベントとそのプロパティのタイプを作成するのと同様に、Ampli Wrapperはユーザープロパティのタイプを作成します。

identify()関数はオプションのuserId、オプションのユーザープロパティ、およびオプションのoptionsを受け入れます。

たとえば、トラッキングプランにroleというユーザープロパティが含まれているとします。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 を使用してユーザーを組織ごとにグループ化したいとします。ジョーはorgIdが10のグループに所属し、スーはorgIdが15のグループに所属しています。SueとJoeはどちらも特定のイベントを実行します。イベントセグメンテーションチャートでその組織をクエリできます。

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

グループを設定すると、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()を呼び出し、キューイングされたイベントが失われないようにしてください。

typescript

ampli.flush();

プラグイン

プラグインを使用すると、イベントプロパティを変更したり（エンリッチメントタイプ）、サードパーティAPIに送信したり（送信先タイプ）するなど、Amplitudeの動作を拡張できます。

まずはプラグインを定義します。エンリッチメントプラグインの例：

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コマンドを実行します。

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

Was this helpful?