Android-Kotlin SDK

Kotlin Android SDK を使用すると、Amplitude にイベントを送信できます。

システム要件

Android Kotlin SDKは、Android APIレベル 21（Android 5.0 Lollipop）以降をサポートしています。

SDK をインストールする

Amplitudeは、依存関係を管理するためにAndroid StudioとGradleを使用することを推奨しています。

dependencies {
    implementation 'com.amplitude:analytics-android:1.+'
}

SDK を設定する

バッチ処理の動作を設定する

高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 SDKは、trackメソッドによってログに記録されたすべてのイベントをメモリにキューイングし、バックグラウンドでバッチ処理として書き込みを行います。flushQueueSizeおよびflushIntervalMillisを使用してバッチ動作をカスタマイズできます。 デフォルトでは、serverUrlはhttps://api2.amplitude.com/2/httpapiです。 一度に大量のデータを送信するには、useBatchをtrueに設定して、をバッチイベントアップロードAPIsetServerUrlに設定しますhttps://api2.amplitude.com/batch。通常モードとバッチモードの両方で、同じイベント アップロードしきい値とフラッシュ タイム間隔を使用します。

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    flushIntervalMillis = 50000
    flushQueueSize = 20
}

EU域内のデータレジデンシー

クライアントを初期化するときにサーバーゾーンを設定してAmplitudeのEUサーバーにデータを送信します。 SDKは、設定されている場合にサーバーゾーンに基づいてデータを送信します。

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    serverZone = ServerZone.EU
}

カスタムHTTPクライアント

SDKは、デフォルトでHttpURLConnectionをネットワークリクエストに使用します。 カスタムHTTPクライアントを使用するには、HttpClientInterfaceを実装してhttpClient設定オプションに渡します。

OkHttpをgzip圧縮で使用する

サンプルアプリケーションは、イベントアップロード用にgzip圧縮を使用したカスタムOkHttpクライアントを作成する方法を示しています。

• GzipRequestInterceptor - リクエスト本文を圧縮する OkHttp インターセプタです。
• CustomOkHttpClient - OkHttp を使用したHttpClientInterface実装。

カスタムクライアントを使用するには：

val httpClient = CustomOkHttpClient()
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    this.httpClient = httpClient
}
httpClient.initialize(amplitude.configuration)

追跡

イベントは、ユーザーがアプリケーションとどのように対話するかを表します。 たとえば、「再生された曲」というアクションはメモしておく必要がある場合があります。

amplitude.track("Song Played")

オプションでイベントプロパティを含めることもできます。

amplitude.track(
  "Song Played",
  mutableMapOf<String, Any?>("title" to "Happy Birthday")
)

より複雑なイベントについては、BaseEventオブジェクトを作成して追跡することができます。

var event = BaseEvent()
event.eventType = "Song Played"
event.eventProperties = mutableMapOf<String, Any?>("title" to "Happy Birthday")
event.groups = mutableMapOf<String, Any?>("test-group-type" to "test-group-value")
event.insertId = 1234
amplitude.track(event)

Identify

Identifyは、イベントを送信することなく、特定のユーザーのユーザープロパティを設定します。SDKは、個々のユーザープロパティに対するset、setOnce、unset、add、append、prepend、preInsert、postInsert、remove、clearAllなどの操作をサポートしています。 Identify インターフェイスを使用して操作を宣言します。 単一のIdentifyオブジェクトに複数の操作をチェーン化し、IdentifyオブジェクトをAmplitudeクライアントに渡してサーバーに送信することができます。

identify メソッドを使用して、ユーザーの ID を処理します。 これらのメソッドを適切に使用することで、イベントがデバイス、ブラウザ、その他のプラットフォームをまたいで移動する際に適切なユーザーにイベントを関連付けることができます。 これらのユーザープロパティ操作を含む identify コールを Amplitude サーバーに送信し、ユーザーのイベントを特定のユーザープロパティに関連付けます。

val identify = Identify()
identify.set("color", "green")
amplitude.identify(identify)

操作を指定する

このIdentifyオブジェクトは以下の操作をサポートしています：

val identify = Identify()
identify
    .set("color", "green")
    .setOnce("initial_source", "organic")
    .add("login_count", 1)
    .append("visited_pages", "home")
    .prepend("notifications", "new_feature")
    .unset("temporary_property")
amplitude.identify(identify)

すべてのユーザープロパティを消去する

現在のユーザーの、すべてのユーザープロパティをクリアするためにclearAll()を使用します。 この操作は元に戻せません。

val identify = Identify()
identify.clearAll()
amplitude.identify(identify)

自動キャプチャ

リリースv1.18.0以降、SDKは手動による計装なしでより多くのイベントを追跡できるようになりました。 以下のイベントを自動的に追跡するようにSDKを設定します。

• セッション。
• アプリケーションのライフサイクル。
• スクリーンビュー。
• ディープリンク。
• 要素の操作。
• フラストレーションのインタラクション：
  • レイジクリック。
  • デッドクリック。

自動キャプチャイベントの追跡を開始するようにAmplitudeを設定します。 それ以外の場合は、セッショントラッキングのみを有効にしておくために設定を省略してください。

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +sessions               // or `+AutocaptureOption.SESSIONS`
        +appLifecycles          // or `+AutocaptureOption.APP_LIFECYCLES`
        +deepLinks              // or `+AutocaptureOption.DEEP_LINKS`
        +screenViews            // or `+AutocaptureOption.SCREEN_VIEWS`
        +elementInteractions    // or `+AutocaptureOption.ELEMENT_INTERACTIONS`
        +frustrationInteractions // or `+AutocaptureOption.FRUSTRATION_INTERACTIONS`
    }
}

import com.amplitude.android.Amplitude
import com.amplitude.android.AutocaptureOption
// Using AutocaptureOption.ALL constant
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = AutocaptureOption.ALL
}
// Or using addAll() method with builder
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        addAll()
    }
}

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = setOf(AutocaptureOption.APP_LIFECYCLES)  // or use `setOf()` to disable autocapture.
}

セッションを追跡する

Amplitudeはデフォルトでセッション追跡を有効にします。autocaptureの設定にAutocaptureOption.SESSIONSを含めることで、SDKがセッションイベントを追跡するように明示的に設定したり、他の自動キャプチャ設定とあわせてセッションイベントトラッキングを有効にしたりできます。。

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +sessions    // or `+AutocaptureOption.SESSIONS`
    }
}

セッション追跡の詳細については、「ユーザーセッション」を参照してください。

アプリケーションのライフサイクルを追跡

autocaptureconfigurationにIncludeを含めることで、AutocaptureOption.APP_LIFECYCLESアプリケーションライフサイクルイベントトラッキングを有効にします。次のコードサンプルを参照してください。

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +appLifecycles    // or `+AutocaptureOption.APP_LIFECYCLES`
    }
}

この設定を有効にした後、Amplitudeは以下のイベントを追跡します。

• [Amplitude] Application Installed：インストール直後にユーザーが初めてアプリケーションを開いたときに起動します。
• [Amplitude] Application Updated: ユーザーがアプリケーションを更新した後にアプリケーションを開いたときに発火します。
• [Amplitude] Application Opened: ユーザーがアプリケーションを起動するか、最初に開いた後にアプリケーションをフォアグラウンドに移動したときに発生します。
• [Amplitude] Application Backgrounded: ユーザーがアプリケーションをバックグラウンドに移行したときに発生します。

画面ビューを追跡

autocaptureの設定にAutocaptureOption.SCREEN_VIEWSを含めることで、画面およびフラグメントの表示イベントの追跡を有効にします。 次のコードサンプルを参照してください。

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +screenViews    // or `+AutocaptureOption.SCREEN_VIEWS`
    }
}

この設定を有効にした後、Amplitudeは[Amplitude] Screen Viewedと[Amplitude] Fragment Viewedの両方のイベントを追跡します。 どちらのイベントにもスクリーン名プロパティが含まれています。 [Amplitude] Fragment Viewedイベントの場合、Amplitudeはフラグメント固有の追加プロパティをキャプチャします。

ディープリンクを追跡する

autocaptureの設定にAutocaptureOption.DEEP_LINKSを含めることで、ディープリンクのイベント追跡を有効にします。 次のコードサンプルを参照してください。

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +deepLinks    // or `+AutocaptureOption.DEEP_LINKS`
    }
}

この設定を有効にすると、AmplitudeはURLとリファラ情報を使用して[Amplitude] Deep Link Openedイベントを追跡します。

単一タスクのアクティビティでディープリンクを処理する

アクティビティが singleTop、singleTask または singleInstance起動モードを使用している場合、Androidは新しいアクティビティを作成する代わりに、アクティビティがすでに実行されている間に到着するディープリンクを配信しますonNewIntent()。この場合、Amplitudeがディープリンクを追跡できるように、setIntent()を呼び出してアクティビティのインテントを更新してください。

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent) // Required for Amplitude to track the deep link
}

要素のインタラクションを追跡する

Amplitudeはクリック可能な要素とのユーザーのやり取りを追跡することができ、従来のAndroid ViewsとJetpack Composeの両方をサポートしています。 このオプションを有効にするには、AutocaptureOption.ELEMENT_INTERACTIONS設定にautocaptureを含める必要があります。

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +elementInteractions    // or `+AutocaptureOption.ELEMENT_INTERACTIONS`
    }
}

この設定を有効にすると、ユーザーがアプリケーション内の要素とインタラクションを行うたびに、Amplitudeが[Amplitude] Element Interactedイベントを追跡します。

// Example: Adding testTag for better identification
Button(
    onClick = { /* handle click */ },
    modifier = Modifier.testTag("login_button")
) {
    Text("Log In")
}
Card(
    onClick = { /* handle click */ },
    modifier = Modifier.testTag("product_card_${product.id}")
) {
    // Card content
}

フラストレーションのやり取りを追跡する

Amplitudeは、Android ViewsとJetpack Composeの両方でクリック可能なUI要素を使用して、フラストレーションを起こすインタラクション（Rage ClickとDead Click）を追跡できます。 このオプションを有効にするには、AutocaptureOption.FRUSTRATION_INTERACTIONS設定にautocaptureを含める必要があります。

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +frustrationInteractions    // or `+AutocaptureOption.FRUSTRATION_INTERACTIONS`
    }
}

Rage Clickは、ユーザーが同じ要素を1秒以内に4回以上クリックした場合に発生します。クリックごとにデバイスに依存しないピクセル間隔が50ピクセル以内です。

レイジクリックが発生すると、Amplitudeはその[Amplitude] Rage Clickイベントを追跡します。

デッドクリックとは、インタラクティブ要素に対するユーザーの操作であり、その後3秒間にわたって目に見える変化はありません。

デッドクリックが発生すると、Amplitudeはその[Amplitude] Dead Clickイベントを追跡します。

フラストレーションのインタラクションタイプを設定する

FRUSTRATION_INTERACTIONSを有効にすると、Rage ClickとDead Clickの両方を追跡できます。 interactionsOptionsパラメータを使用して、各タイプを個別に有効または無効にできます。

import com.amplitude.android.Amplitude
import com.amplitude.android.InteractionsOptions
import com.amplitude.android.RageClickOptions
import com.amplitude.android.DeadClickOptions
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +frustrationInteractions
    }
    interactionsOptions = InteractionsOptions(
        rageClick = RageClickOptions(enabled = true),
        deadClick = DeadClickOptions(enabled = false)
    )
}

フラストレーションアナリティクスから特定の要素を無視する

一部のUI要素は、想定される高速クリックを生成したり、意味のあるフラストレーション信号を提供しなかったりします。 無視 API を使用して、これらの要素をフラストレーションアナリティクスから除外しながら、定期的なインタラクションイベントを追跡できます。

一般的なユースケース：

• ナビゲーション要素：戻るボタン、閉じるボタン、およびドローアトグル。
• マルチクリック要素：増分/減分ボタンや「いいね！」/「お気に入り」ボタンなどがあります。
• 読み込みインジケータ：プログレスバー、スピナー、読み込みボタン。
• 装飾要素：非機能的なUIコンポーネント。

Androidビュー

FrustrationAnalyticsUtilsを使用して、Androidビューのフラストレーション分析を無視します：

import com.amplitude.android.FrustrationAnalyticsUtils
// Ignore all frustration analytics for this view
val backButton = findViewById<Button>(R.id.back_button)
FrustrationAnalyticsUtils.ignoreFrustrationAnalytics(backButton)
// Ignore only rage clicks (allow dead click detection)
val incrementButton = findViewById<Button>(R.id.increment_button)
FrustrationAnalyticsUtils.ignoreFrustrationAnalytics(
    incrementButton,
    rageClick = true,
    deadClick = false
)
// Remove ignore marker from a view
FrustrationAnalyticsUtils.unignoreView(backButton)

Jetpack Compose

Modifier.ignoreFrustrationAnalytics()拡張機能を使用して、コンポーズ要素のフラストレーション分析を無視します：

import com.amplitude.android.ignoreFrustrationAnalytics
// Ignore all frustration analytics
Button(
    onClick = { finish() },
    modifier = Modifier.ignoreFrustrationAnalytics()
) { Text("Back") }
// Ignore only dead clicks (allow rage click detection)
Button(
    onClick = { submitForm() },
    modifier = Modifier.ignoreFrustrationAnalytics(
        rageClick = false,
        deadClick = true
    )
) { Text("Submit") }

パラメータの組み合わせ

ユーザーグループ

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

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

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

グループを設定すると、ユーザープロパティとして設定され、groupType:groupNameそのユーザーの groupType の既存値が対応するユーザープロパティ値とともに上書きされます。groupName は文字列であり、groupTypeユーザーが複数のグループに属していることを示す文字列または文字列の配列groupNameです。

// set group with a single group name
amplitude.setGroup("orgId", "15");

// set group with multiple group names
amplitude.setGroup("sport", arrayOf("tennis", "soccer"))

groupsを持つEvent オブジェクトをtrack に渡すことで、イベントレベルのグループを設定することもできます。イベントレベルのグループの場合、グループの指定はログに記録する特定のイベントにのみ適用され、setGroup IT を使用して明示的に設定しない限り、その指定はユーザーに永続しません。

val event = BaseEvent()
event.eventType = "event type"
event.eventProperties = mutableMapOf("event property" to "event property value")
event.groups = mutableMapOf("orgId" to "15")
amplitude.track(event)

グループ識別

Group Identify API を使用して、特定のグループのプロパティを設定または更新します。次の点に注意してください。

• 更新は将来のイベントにのみ影響を与え、過去のイベントを更新することはありません。
• 最大5つの固有のグループタイプと合計10のグループを追跡できます。

groupIdentifyメソッドは、グループタイプの文字列パラメータ、グループ名のオブジェクトパラメータ、およびAmplitudeがグループに適用するIdentifyオブジェクトを受け取ります。

val groupType = "plan"
val groupName = "enterprise"
val identify = Identify().set("key", "value")
amplitude.groupIdentify(groupType, groupName, identify)

収益の追跡

Amplitudeはユーザーが生み出した収益を追跡できます。 Amplitudeは、AmplitudeのイベントセグメンテーションとレベニューLTVチャートで使用される特別なフィールドを持つ個別の収益オブジェクトを通じて収益を追跡します。収益オブジェクトは、プラットフォーム内の収益に関連するデータを自動的に表示します。 収益オブジェクトは、以下の特別なプロパティとeventPropertiesフィールドを通じて、ユーザー定義のプロパティをサポートしています。

val revenue = Revenue()
revenue.productId = "com.company.productId"
revenue.price = 3.99
revenue.quantity = 3
amplitude.revenue(revenue)

カスタムユーザー識別子

アプリに独自のログインシステムがあり、ユーザーを追跡したい場合は、setUserIdいつでも呼び出してください。

amplitude.setUserId("user@amplitude.com")

現在のユーザー ID を取得するには、getUserId()を呼び出してください。

val userId = amplitude.getUserId()

カスタムデバイス識別子

deviceIdを使用して、新しいデバイスIDを割り当てます。 カスタムデバイスIDを設定する際は、その値が十分に一意であることを確認してください。 AmplitudeはUUIDの使用を推奨しています。

import java.util.UUID
amplitude.setDeviceId(UUID.randomUUID().toString())

ユーザーがログアウトしたときにリセットする

resetは、ログアウト後にユーザーを匿名化するためのショートカットです。以下の方法で行います：

• userIdをnullに設定します。
• 現在の設定に基づいてdeviceIdを新しい値に設定します。

空のuserIdと完全に新しいdeviceIdの場合、現在のユーザーはダッシュボードに新しいユーザーとして表示されます。

amplitude.reset()

SDKプラグイン

プラグインを使用すると、イベントプロパティを変更したり（エンリッチメントタイプ）、サードパーティAPIに送信したり（送信先タイプ）、などすることで、Amplitude SDKの動作を拡張できます。プラグインとは、メソッドsetup()とexecute()を持つオブジェクトです。

プラグインの種類

SDK は固定された順序で各イベントにプラグインを適用します。Beforeつまり、プラグインが最初に実行され、次にEnrichmentプラグインが実行され、次にDestinationプラグインが実行されます。 その他のプラグインタイプ（例：Observe）は、このパイプラインの外で実行されます。

• Beforeプラグイン (Plugin.Type.Before) は、すべてのエンリッチメントプラグインの前に実行されます。他のプラグインがイベントフィールドを読み取る前に、ITを早期にイベントフィールドの設定または保護に使用します。ITの形状はエンリッチメントプラグインと同じで、 type``Plugin.Type.Beforeに設定されています。
• Enrichmentプラグイン (Plugin.Type.Enrichment) は、ITが通過する際にイベントプロパティを追加するなど、各イベントを変更または拡張します。拡張タイプのプラグイン例を参照してください。
• Destinationプラグイン (Plugin.Type.Destination) は、イベントを送信先 (サードパーティ API など) に送信し、パイプラインを終了します。送信先タイプのプラグイン例を参照してください。
• プラグイン (Plugin.Type.Observe) はイベントパイプラインの外で実行されます。 Observeイベントを処理する代わりに、ITは 、 、 、およびコールバックを使用して ID onUserIdChanged``onDeviceIdChanged``onSessionIdChanged``onOptOutChangedとセッションの変更に対応します。ObservePluginクラスを拡張し、必要なコールバックをオーバーライドします。onUserIdChangedおよび onDeviceIdChangedは必須です。

次のObserveプラグインは、ユーザーがログインまたはログアウトしたときに反応します。

import com.amplitude.core.Amplitude
import com.amplitude.core.platform.ObservePlugin
class LoginObserverPlugin : ObservePlugin() {
    override lateinit var amplitude: Amplitude
    override fun onUserIdChanged(userId: String?) {
        // React to login or logout.
    }
    override fun onDeviceIdChanged(deviceId: String?) {}
}
amplitude.add(LoginObserverPlugin())

プラグインのセットアップ

このメソッドには、プラグインを使用できるように準備するためのロジックが含まれており、amplitudeインスタンスをパラメータとして受け取ります。 期待される戻り値は null です。 このメソッドの典型的な用途は、プラグインの依存関係をインスタンス化することです。プラグインが amplitude.add() を通じてクライアントに登録されている場合、SDK はこのメソッドを呼び出します。

Plugin.execute

このメソッドにはイベントを処理するためのロジックが含まれており、eventインスタンスをパラメータとして受け取ります。 拡張タイプのプラグインとして使用する場合、期待される戻り値は変更されたイベントまたは拡張されたイベントです。 送信先タイプのプラグインとして使用する場合、期待される戻り値は、キーとしてevent（BaseEvent）、code（数値）、message（文字列）を持つマップです。 SDK は、Identify、GroupIdentify、および Revenue イベントを含む各イベントに対してこのメソッドを呼び出します。これらのイベントはクライアントインターフェイスを使用して計測されます。

エンリッチメントタイプのプラグイン例

次のプラグインは、追加のイベントプロパティを追加することにより、計測された各イベントを変更します。

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import com.amplitude.core.Amplitude;
import com.amplitude.core.events.BaseEvent;
import com.amplitude.core.platform.Plugin;
import java.util.HashMap;
public class EnrichmentPlugin implements Plugin {
  public Amplitude amplitude;
  @NonNull
  @Override
  public Amplitude getAmplitude() {
    return this.amplitude;
  }
  @Override
  public void setAmplitude(@NonNull Amplitude amplitude) {
    this.amplitude = amplitude;
  }
  @NonNull
  @Override
  public Type getType() {
    return Type.Enrichment;
  }
  @Nullable
  @Override
  public BaseEvent execute(@NonNull BaseEvent baseEvent) {
    if (baseEvent.getEventProperties() == null) {
      baseEvent.setEventProperties(new HashMap<String, Object>());
    }
    baseEvent.getEventProperties().put("custom android event property", "test");
    return baseEvent;
  }
  @Override
  public void setup(@NonNull Amplitude amplitude) {
    this.amplitude = amplitude;
  }
}
amplitude.add(new EnrichmentPlugin());

送信先タイプのプラグインの例

送信先プラグインでは、track()、identify()、groupIdentify()、revenue()、およびflush()関数を上書きできます。

import com.amplitude.core.Amplitude;
import com.amplitude.core.events.BaseEvent;
import com.amplitude.core.platform.DestinationPlugin;
import com.segment.analytics.Analytics;
import com.segment.analytics.Properties;
public class SegmentDestinationPlugin extends DestinationPlugin {
  android.content.Context context;
  Analytics analytics;
  String writeKey;
  public SegmentDestinationPlugin(android.content.Context appContext, String writeKey) {
    this.context = appContext;
    this.writeKey = writeKey;
  }
  @Override
  public void setup(Amplitude amplitude) {
    super.setup(amplitude);
    analytics = new Analytics.Builder(this.context, this.writeKey)
    .build();
    Analytics.setSingletonInstance(analytics);
    }
  @Override
  public BaseEvent track(BaseEvent event) {
    Properties properties = new Properties();
    for (Map.Entry<String,Object> entry : event.getEventProperties().entrySet()) {
      properties.putValue(entry.getKey(),entry.getValue());
    }
    analytics.track(event.eventType, properties);
    return event;
    }
}
amplitude.add(
new SegmentDestinationPlugin(this, SEGMENT_WRITE_KEY)
)

プラグインを削除する

プラグインがイベントを処理することを停止するには、同じプラグインインスタンスを remove() に渡します。

val plugin = EnrichmentPlugin()
amplitude.add(plugin)
// Later, remove it.
amplitude.remove(plugin)

ネットワーク追跡プラグイン

ネットワークトラッキングプラグインは、OkHttp を介して行われたネットワーク要求と応答をキャプチャします。これには、URL、ステータスコード、タイミング情報が含まれます。 ネットワーク追跡は自動キャプチャの一部ではなく、手動での連携が必要です。追跡したい各OkHttpクライアントにプラグインをインターセプターとして追加し、ITをAmplitudeインスタンスに追加してください。このプラグインは、計測する OkHttp クライアントを通過するリクエストのみをキャプチャします。

インストール

ネットワーク追跡プラグインには、OkHttpへの依存関係が必要です。プロジェクトに追加するには：

dependencies {
    // OkHttp is required for the NetworkTrackingPlugin
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
}

設定

デフォルトの設定を使用し、OkHttpと統合するためのインターセプタとしてプラグインを追加します。

import com.amplitude.android.network.NetworkTrackingPlugin
// Create the plugin with default configuration
val networkPlugin = NetworkTrackingPlugin()
// Add the plugin as an interceptor to your OkHttp client
val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(networkPlugin)
    .build()
// Add the plugin to your Amplitude instance
amplitude.add(networkPlugin)

デフォルト設定では、*.amplitude.com以外のすべてのホストを、ステータスコード500～599を除いて追跡します。

NetworkTrackingOptionsを設定すると、トラッキング動作をカスタマイズし、どのリクエストを追跡するかをコントロールできます：

import com.amplitude.android.Amplitude
import com.amplitude.android.network.NetworkTrackingOptions
import com.amplitude.android.network.NetworkTrackingPlugin
import com.amplitude.android.network.NetworkTrackingOptions.CaptureRule
// Create custom capture rules
val options = NetworkTrackingOptions(
    captureRules = listOf(
        // Track all responses from your API domain with status code from 400 to 599
        CaptureRule(
            hosts = listOf("*.example.com", "example.com"),
            statusCodeRange = (400..599).toList()
        )
    ),
    // Ignore specific domains
    ignoreHosts = listOf("analytics.example.com", "*.internal.com"),
    // Whether to ignore Amplitude API requests
    ignoreAmplitudeRequests = true
)
// Create the plugin with options
val networkPlugin = NetworkTrackingPlugin(options)
// Add the plugin to your Amplitude instance
amplitude.add(networkPlugin)

captureRules = listOf(
    CaptureRule(
        hosts = listOf("\*"),
        statusCodeRange = (400..599).toList()
    ),
    CaptureRule(
        hosts = listOf("\*.example.com", "example.com"),
        statusCodeRange = (500..599).toList()
    )
)

URL、ヘッダー、リクエストボディをキャプチャする

ホストではなく URL でリクエストを照合する場合や、リクエストとレスポンスのヘッダーとボディをキャプチャするには、URL ベースのCaptureRuleコンストラクタを使用します。 URL をURLPattern.Exact または URLPattern.Regexと一致させ、HTTP メソッドでフィルタリングし、CaptureHeaderおよびCaptureBody を使用してヘッダーと本文のキャプチャをオプトインします。

import com.amplitude.android.network.NetworkTrackingOptions
import com.amplitude.android.network.NetworkTrackingOptions.CaptureRule
import com.amplitude.android.network.NetworkTrackingOptions.CaptureHeader
import com.amplitude.android.network.NetworkTrackingOptions.CaptureBody
import com.amplitude.android.network.NetworkTrackingOptions.URLPattern
val options = NetworkTrackingOptions(
    captureRules = listOf(
        CaptureRule(
            urls = listOf(
                URLPattern.Exact("https://api.example.com/v1/login"),
                URLPattern.Regex("^https://api\\.example\\.com/v1/.*")
            ),
            methods = listOf("POST"),
            statusCodeRange = (200..599).toList(),
            requestHeaders = CaptureHeader(allowlist = listOf("X-Request-Id")),
            responseHeaders = CaptureHeader(allowlist = listOf("X-Response-Id")),
            requestBody = CaptureBody(allowlist = listOf("user/*"), excludelist = listOf("**/password")),
            responseBody = CaptureBody(allowlist = listOf("profile/**"))
        )
    )
)
amplitude.add(NetworkTrackingPlugin(options))

追跡されたイベントプロパティ

プラグインがネットワークリクエストを追跡すると、以下のプロパティを持つ[Amplitude] Network Requestタイプのイベントを送信します：

プライバシーに関する考慮事項

ネットワークトラッキングプラグインは、デフォルトで次の機密情報をマスクします。

1. URL内の認証資格情報（username:password@domain.com）。
2. 一般的な機密性の高いクエリパラメータ（ユーザー名、パスワード、電子メール、電話番号など）。

デバッグ

設定とペイロードが正確であることを確認し、デバッグ中に異常なメッセージがないかをチェックしてください。 すべてが正常に見える場合は、flushQueueSizeまたはflushIntervalMillisの値を確認してください。 デフォルトでは、SDKはイベントを一括でキューイングおよび送信するため、個々のイベントがすぐにサーバーに送信されることはありません。SDKがイベントをサーバーに送信するのを待ってから、グラフでイベントを確認してください。

ログ

• ログレベルを「デバッグ」に設定すると、デバッグ中に有用な情報を収集できます。
• LoggerProviderのloggerProviderクラスをカスタマイズし、本番環境のサーバーにエラーメッセージを記録するなどの独自のロジックを実装してください。

プラグイン

送信先プラグインを使用して、設定値やイベントのペイロードをサーバーに送信する前に出力してください。 logLevelを「デバッグ」に設定し、以下のTroubleShootingPluginをプロジェクトにコピーしてから、プラグインをAmplitudeインスタンスに追加してください。

• Java TroubleShootingPlugin の例。
• Kotlin TroubleShootingPlugin の例。

イベントコールバック

イベントコールバックは、SDKがイベントを送信した後に実行されます（成功したイベントと失敗したイベントの両方について）。このメソッドを使用して、イベントステータスとメッセージをモニターできます。 詳細については、「コールバック」の設定を参照してください。

高度なトピック

ユーザーセッション

Amplitudeは、アプリがフォアグラウンドに移動したとき、またはSDKがバックグラウンドでイベントを追跡したときにセッションを開始します。 追跡されたイベントがないまま、アプリがminTimeBetweenSessionsMillisオプションで指定された時間よりも長くバックグラウンドにある場合、セッションは終了します。configuration.trackingSessionEvents、configuration.defaultTracking、configuration.autocaptureのいずれを通じてセッション追跡を有効にしているかに関わらず、セッションはアプリがフォアグラウンドにある間、常に継続します。

アプリがフォアグラウンドに入ると、Amplitudeはセッションの開始を追跡し、minTimeBetweenSessionsMillisに基づいてカウントダウンを開始します。 Amplitudeは、新しいイベントを追跡するたびにセッションを延長し、カウントダウンを再開します。 カウントダウンが期限切れになると、Amplitudeは次のイベントまで待機してセッション終了イベントを追跡します。

Amplitudeはデフォルトでセッションイベントのユーザープロパティを設定しません。 これらのプロパティを追加するには、identify()およびsetUserId()を使用します。 Amplitudeはユーザープロパティの状態を集約し、device_idやuser_idに基づいてユーザーとイベントを関連付けます。

Amplitudeがセッションを管理する方法により、イベントが欠落しているように見えたり、セッション追跡が不正確であるように見えたりしても、SDKは期待どおりに動作することができます。

• ユーザーがアプリに戻らなかった場合、Amplitudeはセッション開始イベントに対応するようにセッション終了イベントを追跡しません。
• バックグラウンドでイベントを追跡する場合、Amplitudeはユーザーがフォアグラウンドでアプリに費やす時間よりも長いセッション時間を認識する可能性があります。
• 最後のイベントとセッション終了イベントの間にユーザープロパティを変更した場合、セッション終了イベントには更新されたユーザープロパティが反映されます。このプロパティは、同じセッション内のイベントに関連付けられた他のプロパティとは異なる場合があります。この問題に対処するには、エンリッチメントプラグインを使用して、セッション終了イベント時にevent['$skip_user_properties_sync']をtrueに設定します。これにより、Amplitudeがその特定のイベントについてプロパティを同期するのを防ぐことができます。 詳細については、『コンバータ設定リファレンス』の記事にある$skip_user_properties_syncを参照してください。

Amplitudeはイベントをセッションごとにグループ化します。 同じセッション内で記録されたイベントは、同じsession_idを共有します。 Amplitudeではセッションが自動的に処理されるため、startSession()やendSession()を手動で呼び出す必要はありません。

セッション延長の時間枠を調整します。 デフォルトのセッション有効期限は30分です。

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    minTimeBetweenSessionsMillis = 10000
}

デフォルトでは、Amplitudeは自動的に[Amplitude] Start Sessionと[Amplitude] End Sessionのイベントを送信します。 SDKがこれらのイベントを送信しない場合でも、Amplitudeはsession_idを使用してセッションを追跡します。 これらのセッションイベントを無効にすることもできます。

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = setOf()
}

現在のセッション ID を取得するには、sessionIdプロパティを読み取ります。 Java では、合成getSessionId()アクセサを使用します。

val sessionId = amplitude.sessionId

また、イベントをセッション外として追跡することもできます。 セッション外のイベントの-1はsessionIdとなり、次のように動作します：

1. これらは現在のセッションの一部ではありません。
2. 現在のセッションを延長することはありません。
3. 新しいセッションを開始することはありません。
4. これらは、その後のイベントに対してsessionIdを変更することはありません。

潜在的なユースケースとしては、プッシュ通知から追跡されるイベントがあります。これは通常、顧客のアプリの使用状況とは関係ありません。

track(event, options)またはidentify(identify, options)を呼び出す際に、イベントをセッション外としてマークするには、EventOptionsでsessionIdを-1に設定してください。

val outOfSessionOptions = EventOptions().apply {
 sessionId = -1
}
amplitude.identify(
 Identify().set("user-prop", true),
 outOfSessionOptions
)
amplitude.track(
 BaseEvent().apply { eventType = "test event" },
 outOfSessionOptions
)

ログレベル

開発者コンソールに出力されるログのレベルを制御します。

• INFO：イベントに関する情報メッセージを表示します。
• WARN：エラーメッセージと警告を表示します。 このレベルでは、データに問題や異常を引き起こす可能性がある問題を記録します。 たとえば、このレベルでは、値が NULL であるプロパティに対して警告が表示されます。
• ERROR：エラーメッセージのみを表示します。
• DISABLE：すべてのログメッセージを抑制します。
• DEBUG：デバッグに役立つ可能性のあるエラーメッセージ、警告、および情報メッセージを表示します。

setLogLevelを呼び出す際は、希望するレベルを指定してログレベルを設定してください。

amplitude.logger.logMode = Logger.LogMode.DEBUG

ログアウト済みユーザーと匿名ユーザー

Amplitudeはユーザーデータを統合するため、既知のuserIdまたはdeviceIdに関連付けられたイベントは、既存のユーザーに紐付けられます。 ユーザーがログアウトした場合、Amplitudeはそのユーザーのログアウト後のイベントを、そのユーザーのレコードに統合することができます。 この動作を変更して、代わりに匿名ユーザーにこれらのイベントを記録することができます。

匿名ユーザーにイベントをログに記録するには：

1. userIdをnullに設定します。
2. 新しいdeviceIdを生成します。

現在のユーザーまたはデバイスから送信されたイベントは、Amplitudeでは新しいユーザーとして表示されます。 注：これを行うと、2人のユーザーが同じデバイスを使用していたことが確認できなくなります。

amplitude.reset()

追跡を無効にする

デフォルトでは、Android SDKは、carrier、city、country、ip_address、language、platformなどのいくつかのユーザープロパティを追跡します。 付属のTrackingOptionsインターフェースを使用して、個々のフィールドをカスタマイズしたり、表示・非表示を切り替えたりしてください。

TrackingOptionsインターフェイスを使用するには、クラスをインポートします。

import com.amplitude.android.TrackingOptions

apiKeyを使用してSDKを初期化する前に、設定に基づいてTrackingOptionsインスタンスを作成し、それをSDKインスタンスに設定してください。

val trackingOptions = TrackingOptions()
trackingOptions.disableCity().disableIpAddress().disableLatLng()
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    this.trackingOptions = trackingOptions
}

各フィールドのトラッキングを個別に制御できます。 各フィールドには対応するメソッドがあります (例: disableCountry, disableLanguage)。

キャリア

Amplitudeは、AndroidのTelephonyManager networkOperatorNameを使用してユーザーの携帯電話キャリアを特定します。このメソッドは、towerの現在登録されている通信事業者を返します。

COPPA制御

IDFA、IDFV、都市、IPアドレス、および位置情報追跡に関するCOPPA（児童オンラインプライバシー保護法）の制限をすべて有効または無効にできます。13 歳未満の子供から情報を求めるアプリは、COPPA に準拠する必要があります。

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    enableCoppaControl = true // Disables ADID, city, IP, and location tracking
}

広告主ID

Android 広告 ID は、Google Play ストアが提供する固有の識別子です。 この情報はデバイスだけでなく、ユーザーごとに固有であるため、モバイルアトリビューションに役立ちます。Android広告IDは、iOS上のIDFAと似ています。モバイルアトリビューションは、モバイルアプリのインストールをその元のTarget（広告キャンペーンやアプリストアの検索など）に帰属させるものです。ユーザーは広告IDを無効にすることを選択でき、子供をターゲットにしたアプリはまったく追跡できません。

Android広告IDを使用するには、以下の手順に従ってください。

1. play-services-ads-identifierを依存関係として追加してください。

   bash

   コピー

   dependencies {
     implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
   }
   

2. AD_MANAGER_APP 権限 Google Mobile Ads SDK バージョン17.0.0以降を使用する場合は、AndroidManifest.xmlにAD_MANAGER_APPを追加する必要があります。

   xml <manifest> <application> <meta-data android:name="com.google.android.gms.ads.AD_MANAGER_APP" android:value="true"/> </application> </manifest>

3. ProGuard例外を追加

   Amplitude Android SDKは、Google Playサービス内のクラスを使用するためにJava Reflectionを使用しています。 Android アプリケーションで Amplitude SDK を動作させるには、play-services-ads由来のクラスについて、proguard.proに以下の例外を追加してください。 -keep class com.google.android.gms.ads.** { *; }

4. AD_ID 権限

   アプリをAndroid 13以降を対象に更新する場合、ADIDをdeviceIdとして使用するには、マニフェストファイルに次のようにGoogle Playサービスの通常権限を宣言する必要があります：

   xml

   コピー

   <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
   

   詳細については、Googleの広告IDに関するドキュメントを参照してください。

広告IDをデバイスIDとして使用する

広告IDを取得するロジックを設定した後、useAdvertisingIdForDeviceIdを有効にして、広告IDをデバイスIDとして使用できるようにしてください。

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    useAdvertisingIdForDeviceId = true
}

アプリケーションセットID

アプリセットIDは、デバイスにインストールされている各アプリに対する固有の識別子です。 ユーザーがアプリをアンインストールするときにアプリセット ID を手動でリセットするか、アプリを開かずに 13 か月経過すると自動的にリセットされます。 Googleは、強力なアナリティクスをオプトアウトしたいユーザー向けに、広告IDに代わるプライバシーに配慮した代替手段としてアプリセットIDを設計しました。

アプリ セット ID を使用するには、次の手順に従ってください。

1. play-services-appsetを依存関係として追加してください。 2.35.3より前のバージョンの場合は、'com.google.android.gms:play-services-appset:16.0.0-alpha1'を使用してください

   bash

   コピー

   dependencies {
   implementation 'com.google.android.gms:play-services-appset:16.0.2'
   }
   

2. アプリセットIDをデバイスIDとして使用できるようにします。

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    useAppSetIdForDeviceId = true
}

デバイスIDのライフサイクル

SDKはデバイスIDを次の順序で初期化し、デバイスIDを最初に検出した有効な値に設定します。

1. インスタンスのデバイスID。
2. ADID（useAdvertisingIdForDeviceIdが有効で、必要なモジュールがインストールされている場合）。 詳細については、「広告主ID」を参照してください。
3. アプリケーションセットIDにSが追加されます（useAppSetIdForDeviceIdが有効で、必要なモジュールがインストールされている場合）。 詳細については、「アプリケーション セット ID」を参照してください。
4. ランダムに生成されたUUIDで、Rが追加されています。

1人のユーザーが複数のデバイスを使用

1人のユーザーが複数のデバイスを所有することができ、それぞれに異なるデバイスIDがあります。一貫性を保つために、これらのすべてのデバイスで一貫したユーザーIDを設定してください。デバイスIDが異なる場合でも、Amplitudeはそれらを単一のAmplitude IDにマージし、ユニークなユーザーとして識別することができます。

新しいデバイスへの転送

ユーザーが新しいデバイスに切り替えると、複数のデバイスに同じデバイスIDが割り当てられる場合があります。ユーザーが新しいデバイスに移行するとき、ユーザーは多くの場合、他の関連データと一緒にアプリケーションを移行します。 転送される特定のコンテンツはアプリケーションによって異なります。 一般的に、ITにはアプリケーションに関連付けられたデータベースとファイルディレクトリが含まれます。含まれている正確なアイテムは、アプリのデザインと開発者の選択によって異なります。 データベースやファイルディレクトリをあるデバイスから別のデバイスに転送しても、その中に保存されているデバイスIDは依然として存在する可能性があります。SDK が初期化中にそのデバイス ID を取得した場合、異なるデバイスが同じデバイス ID を使用することになる可能性があります。

デバイスIDを取得する

ヘルパーメソッドgetDeviceId()を使用して、現在のdeviceIdの値を取得します。

val deviceId = amplitude.getDeviceId();

デバイスを設定する方法については、カスタムデバイスIDを参照してください。

位置情報追跡

AmplitudeはデフォルトでユーザーイベントのIPを場所に変換します（GeoIP検索）。 アプリ独自の追跡ソリューションまたはユーザーデータがこの情報を上書きする場合があります。

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    locationListening = true
}

ユーザーを追跡から除外する

ユーザーはトラッキングを完全にオプトアウトしたい場合があります。つまり、Amplitude はユーザーのイベントや閲覧履歴を一切追跡しません。OptOutはユーザーのプライバシーに関する要求に応える方法を提供します。

optOutがtrueの状態にある間、Amplitudeはイベントを保存または送信しません。

// At initialization
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    optOut = true
}
// At runtime
amplitude.optOut = true
amplitude.optOut = false // Re-enable tracking

プッシュ通知イベント

Android SDKを使用してクライアント側にプッシュ通知イベントを送信しないでください。SDKがイベントを送信できるように、ユーザーがアプリを開いてAmplitude SDKを初期化する必要があるため、SDKはユーザーが次回アプリを開くまでイベントをAmplitudeサーバーに送信しません。このため、データが遅延する可能性があります。

import com.amplitude.common.Logger
import com.amplitude.core.LoggerProvider
class sampleLogger : Logger {
override var logMode: Logger.LogMode
 get() = Logger.LogMode.DEBUG
 set(value) {}
 override fun debug(message: String) {
 TODO("Handle debug message here")
 }
 override fun error(message: String) {
 TODO("Handle error message here")
 }
 override fun info(message: String) {
 TODO("Handle info message here")
 }
 override fun warn(message: String) {
 TODO("Handle warn message here")
 }
}
class sampleLoggerProvider : LoggerProvider {
 override fun getLogger(amplitude: com.amplitude.core.Amplitude): Logger {
 return sampleLogger()
 }
}
amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    loggerProvider = sampleLoggerProvider()
}

複数のインスタンス

Amplitudeの複数のインスタンスを作成できます。 同じinstanceNameを持つインスタンスは、ストレージとアイデンティティを共有します。 ストレージとIDを分離するには、インスタンスごとに一意のinstanceNameを使用してください。 詳細については、「設定」を参照してください。

val amplitude1 = Amplitude("api-key-1", applicationContext) {
    instanceName = "one"
}
val amplitude2 = Amplitude("api-key-2", applicationContext) {
    instanceName = "two"
}

オフラインモード

バージョン1.13.0以降、Amplitude Android Kotlin SDKはオフラインモードをサポートしています。SDK はイベントを追跡するたびにネットワーク接続を確認します。 デバイスがネットワークに接続されている場合、SDKはフラッシュをスケジュールします。 そうでない場合は、イベントをストレージに保存します。 また、SDKはネットワーク接続の変更を監視し、デバイスが再接続されたときに保存されているすべてのイベントをフラッシュします。

この機能を有効にするには、AndroidManifest.xmlにACCESS_NETWORK_STATE権限を追加してください。 それ以外の場合は、SDKはflushIntervalMillisおよびflushQueueSizeに基づいてイベントをフラッシュします。

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

独自のオフラインロジックを実装することもできます：

1. config.offlineをAndroidNetworkConnectivityCheckerPlugin.Disabledに設定すると、デフォルトのオフラインロジックが無効になります。
2. 自分でconfig.offline切り替えましょう。