Ampli for Android-Kotlin SDK

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

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

クイックスタート

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

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

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

   kotlin

   コピー

   implementation 'com.amplitude:analytics-android:1.+'
   

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

   bash

   コピー

   npm install -g @amplitude/ampli
   

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

   bash

   コピー

   ampli pull [--path ./app/src/main/java/com/amplitude/ampli]
   

5. Ampliラッパーを初期化する

   kotlin

   APIキーコピー

   import com.amplitude.ampli.*
   ampli.load(appContext, LoadOptions(
     client = LoadClientOptions(apiKey = AMPLITUDE_API_KEY)
   ))
   

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

   kotlin

   コピー

   ampli.identify(userId, Identify(
       userProp = "A trait associated with this user"
   ))
   

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

   kotlin

   コピー

   ampli.songPlayed(songId = "song-1")
   ampli.track(SongFavorited(songId = "song-2"))
   

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

   kotlin

   コピー

   ampli.flush();
   

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

   bash

   コピー

   ampli status [--update]
   

Amplitude SDKをインストールする

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

implementation 'com.amplitude:analytics-android:1.+'

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()メソッドは設定オプション引数を受け入れます。

import com.amplitude.ampli.*
ampli.load(appContext, LoadOptions(
 client = LoadClientOptions(apiKey = AMPLITUDE_API_KEY)
))

Identify

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

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

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

たとえば、トラッキングプランにuserPropというユーザープロパティが含まれているとします。プロパティのタイプは文字列です。

ampli.identify(userId, Identify(
 userProp = "A trait associated with this user"
))

options引数を使用すると、この呼び出しのAmplitudeフィールド（deviceIdなど）を渡すことができます。

val eventOptions = EventOptions();
eventOptions.deviceId = "device-id";
ampli.identify(
 userId,
 Identify(
 userProp = "A trait associated with this user",
 ),
 eventOptions
)

グループ識別

アプリ内のグループを識別し、グループのプロパティを設定または更新するには、groupIdentify()を呼び出します。

Ampli がイベントとそのプロパティのタイプを作成するのと同じように、Ampli はグループプロパティのタイプを作成します。

groupIdentify()関数は文字列group_type、文字列group_name、グループイベントインスタンス、およびオプションのEventOptionsを受け取ります。

たとえば、トラッキングプランには、requiredBooleanという名前のブール値プロパティを持つtest group:android-java-ampliグループが含まれています。

ampli.groupIdentify("test group", "android-kotlin-ampli", Group(requiredBoolean = true))

グループ

ユーザーをグループ（部署や会社など）に関連付けるには、setGroup()を呼び出します。setGroup()関数は、必須のgroupType、およびgroupName、ならびにオプションのEventOptionsを受け入れます。

ampli.client?.setGroup("groupType", "groupName")

Amplitudeでは、ユーザーをグループに割り当てたり、それらのグループに対して「ユニーク数による集計」などのクエリを実行したりすることができます。 グループの少なくとも1人のメンバーが特定のイベントを実行した場合、そのグループはカウントに含まれます。

たとえば、orgIdを使用してユーザーを組織ごとにグループ化したいとします。ジョーはorgIdが10のグループに所属し、スーはorgIdが15のグループに所属しています。SueとJoeはどちらも特定のイベントを実行します。 イベントセグメンテーションチャートでその組織をクエリできます。

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

グループを設定すると、groupType:groupNameがユーザープロパティとして設定され、そのユーザーのgroupTypeに既存するgroupNameの値もすべて上書きされます。groupTypeは文字列です。groupNameは、ユーザーが複数のグループに属していることを示す文字列または文字列の配列にすることができます。たとえば、Joeが、orgId 10および20に属する場合、groupNameは[10, 20]になります。

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

ampli.client?.setGroup("orgId", arrayOf("10", "20"))

追跡

イベントを追跡するには、そのイベントに対応する関数を呼び出します。 トラッキングプラン内のすべてのイベントは、Ampliラッパー内で独自の関数を持っています。この呼び出しは次の構造を使用します。

ampli.eventName(...eventNameProperties)

options引数を使用すると、deviceIDなどのAmplitudeフィールドを渡すことができます。

たとえば、次のコードスニペットでは、トラッキングプランにsongPlayedというイベントが含まれています。このイベントにはsongIdおよびsongFavoritedという2つの必須プロパティがあります。songIdのプロパティタイプは文字列で、songFavoritedはブール値です。

ampli.songPlayed(
 songId = "songId", // String,
 songFavorited = true, // Boolean
)

また、Ampli はイベントごとにクラスを生成します。

val myEventObject = SongPlayed(
 songId = "songId", // String,
 songFavorited = true, // Boolean
);

汎用トラックメソッドを使用してイベントオブジェクトを送信します。

val options = EventOptions()
options.userId = "user_id"
ampli.track(SongPlayed(
 songId = "songId", // String
 songFavorited = true, // Boolean
 ), options);

フラッシュ

Ampliラッパーはイベントをキューに入れ、設定に基づく間隔で送信します。

保留中のイベントをすぐに送信するには、flush()を呼び出します。

flush()メソッドは、Promiseを返します。このPromiseは、Ampliが処理を続行する前にすべての保留中のイベントを確実に送信するために使用できます。アプリケーションが終了する前にflush()を呼び出し、キューイングされたイベントが失われないようにします。

AmpliはキューがflushQueueSizeに到達するか、タイマーがflushIntervalに到達すると、バッファ内のイベントを自動的にフラッシュします。

ampli.flush()

プラグイン

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

まずはプラグインを定義します。 次のコードは、送信先プラグインの例を示しています。

class SegmentDestinationPlugin(appContext: Context, segmentApiKey: String) : DestinationPlugin() {
 var analytics: Analytics? = null;
 val context: Context = appContext;
 init {
 analytics = Analytics.Builder(appContext, segmentApiKey).build()
 }
 override fun track(event: BaseEvent): BaseEvent {
 val eventProperties = Properties();
 event.eventProperties?.forEach { entry -> entry.value?.let {
 eventProperties.put(entry.key,
 it)
 } }
 analytics?.track(event.eventType, eventProperties);
 return event
 }
}

Ampli を初期化したあとでプラグインを追加してください。

ampli.client?.add(
 YourDestinationPlugin(this, DESTINATION_API_KEY)
 )

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の詳細をご覧ください。