ガイドとサーベイ Android SDK

AmplitudeのガイドとサーベイAndroid SDKを使用すると、Androidアプリケーションにガイドとサーベイをデプロイできます。

インストールと検証

以下の手順に従ってSDKをインストールし、アプリをAmplitudeプロジェクトに接続し、ガイドやサーベイがアプリに届くことを確認してください。

要件

ガイドとサーベイ Android SDK には以下が必要です:

• Android API レベル 24（Android 7.0）以上。
• Kotlin 1.8.22 以降。

ガイドとサーベイは、Amplitude Analyticsとは別に利用できます。

SDKのインストールと初期化

ガイドとサーベイは、既存のAmplitude実装環境（存在する場合）と最適に連携できるように、さまざまなインストールオプションをサポートしています。

Amplitude Analytics Android-Kotlin SDKの使用

アプリでAmplitude AnalyticsのAndroid-Kotlin SDKを使用している場合は、バージョン1.0以降を使用していることを確認してください。次に、アプリケーションのbuild.gradle.ktsファイルに以下の依存関係を追加します。

dependencies {
    // Amplitude Engagement SDK
    implementation("com.amplitude:amplitude-engagement-android:3.+")
    // Amplitude Analytics SDK (required dependency)
    implementation("com.amplitude:analytics-android:1.+")
}

SDKの初期化

import com.amplitude.android.engagement.AmplitudeEngagement
import com.amplitude.android.engagement.AmplitudeInitOptions
// Initialize the SDK
val amplitudeEngagement = AmplitudeEngagement(
    context = applicationContext,
    apiKey = "YOUR_API_KEY",
    options = AmplitudeInitOptions()
)
// Add the plugin to your Amplitude instance
val amplitude = Amplitude(applicationContext)
amplitude.add(amplitudeEngagement.getPlugin())

このコールでは、Amplitude Analytics Android SDKのプラグインシステムを使用して、ガイドとサーベイを既存のアナリティクス設定と統合します。プラグインを追加すると、アナリティクスとともにガイドとサーベイが初期化されます。ガイドとサーベイは同じ API キーとユーザー ID を共有しており、アナリティクスと直接通信します。 bootを個別に呼び出す必要はありません。

設定オプション

Amplitude Analytics Android-Kotlin SDK 1.0 以降を使用していない

アプリがAmplitude Analytics Android-Kotlin SDK 1.0以降を使用していない場合でも、ガイドとサーベイをインストールすることはできますが、アナリティクス SDK プラグインシステムを使用する代わりに.boot直接呼び出す必要があります。

アプリケーションのbuild.gradle.ktsファイルに以下の依存関係を追加してください。

dependencies {
    // Amplitude Engagement SDK
    implementation("com.amplitude:amplitude-engagement-android:2.+")
}

SDKの初期化

import com.amplitude.android.engagement.AmplitudeEngagement
import com.amplitude.android.engagement.AmplitudeInitOptions
// Initialize the SDK
val amplitudeEngagement = AmplitudeEngagement(
    context = applicationContext,
    apiKey = "YOUR_API_KEY",
    options = AmplitudeInitOptions()
)

設定オプション

SDKを起動する

// Basic boot with user ID
amplitudeEngagement.boot("USER_ID")
// Advanced boot with options
let bootOptions = AmplitudeBootOptions(
    userId: "USER_ID",
    deviceId: "DEVICE_ID",
    userProperties: mapOf("key" to "value")
    integrations = arrayOf({ event: BaseEvent ->
        // Custom event handler
        // Dummy example here:
        println("event: ${event.eventType} properties: ${event.eventProperties}")
    })
)
amplitudeEngagement.boot(options: bootOptions)

アプリケーションをプロジェクト設定に追加する

SDKをインストールした後、AndroidアプリケーションをAmplitudeプロジェクト設定に追加して、ガイドやサーベイを作成するときにプラットフォームオプションとして表示されるようにしてください。

アプリケーションを追加するには：

1. Amplitudeの_設定 > プロジェクト_に移動します。
2. プロジェクトを選択します。
3. ガイドとサーベイタブに移動します。
4. App Management セクションを展開し、+ Add App をクリックします。
5. ドロップダウンから Android を選択します。

アプリケーションを追加した後、Androidアプリユーザー向けのガイドやサーベイを作成または編集する際に、そのアプリケーションをプラットフォームオプションとして選択できます。

プレビューモードの設定と検証

ガイドやサーベイをアプリケーション内で直接プレビューすることで、ユーザーと同じ体験を確認できます。プレビュー機能を使用すると、コピー、ターゲット設定ルール、トリガーロジックの繰り返し調整が容易になり、インストールが正常に動作していることを確認できます。

モバイルURLスキームを特定する

URLスキームを特定するには：

1. Amplitudeの_設定 > プロジェクト_に移動します。
2. プロジェクトを選択します。
3. ［全般］タブに移動します。
4. **URLスキーム（モバイル）**フィールドを探します。
5. その値をコピーします（例：amp-abcdefgh12345678）。

Android Studio で URL スキームを追加する

プロジェクトの AndroidManifest.xml ファイルのメインアクティビティに次のインテントフィルターを追加します。

<activity android:name=".MainActivity">
    <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- Add your URL scheme from Amplitude Dashboard here -->
    <!-- ex: android:scheme="amp-12345" -->
    <data android:scheme="<your-unique-scheme-id>" />
    </intent-filter>
</activity>

プレビューリンクのURL処理

// In your Activity
override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    amplitudeEngagement.handleLinkIntent(intent)
}

QRコードスキャンによるインストールの確認

インストール作業がエンドツーエンドで行われていることを確認してください。

1. Amplitudeでガイドまたはサーベイを開き、プレビューをクリックします。
2. 表示されたQRコードをデバイスのカメラでスキャンするか、アプリがインストールされているデバイスでプレビューURLを開きます。
3. ガイドまたはサーベイがアプリ内で開くことを確認します。
4. 画面下部にある小さなAmplitudeロゴを探し、それをタップしてスーパーデバッガーを開きます。チェックする項目についてはスーパーデバッガーを参照してください。

アプリでプレビューが開かない場合や、ロゴが表示されない場合は、先に進む前に上記のURLスキーム設定手順を確認してください。

リファレンス

最小SDKバージョンを設定する（必要な場合）

SDKバージョン3.0.0以降でMinimum SDK versionをサポートしています。この設定は、古いSDKリリースで重大な問題を特定した場合の安全対策として使用してください。

SDK の最小バージョンを設定するには:

1. Amplitudeの_設定 > プロジェクト_に移動します。
2. プロジェクトを選択します。
3. ガイドとサーベイタブに移動します。
4. App Management セクションを展開し、+ Add App をクリックします。
5. ドロップダウンから Android を選択します。
6. 「Minimum SDK version」に値を入力します。

この値を設定すると、ガイドとサーベイは設定済みの最小値と各アプリビルドのSDKバージョンを比較します。

• アプリのビルドで古いバージョンの SDK を使用している場合、SDK はそのビルドで初期化されません。
• アプリのビルドで同じバージョンまたは新しいバージョンの SDK を使用している場合、SDK は期待どおりに初期化されます。

この設定を使用すると、アプリケーションリリースをロールバックすることなく、問題のある既知のSDKバージョンに関するガイドやサーベイを停止できます。

最小SDKバージョンの使用例

アプリバージョン120ではGuides and Surveys SDK3.0.2を使用しており、アプリバージョン121ではバグ修正が含まれるGuides and Surveys SDK3.1.0を使用しているとします。最小SDKバージョンを3.1.0に設定すると次のようになります。

• アプリのバージョン120では、ガイドとサーベイが読み込まれなくなりました。
• アプリのバージョン121は引き続きガイドとサーベイを読み込みます。

画面追跡と要素ターゲティング

画面追跡を有効にする

画面ベースのターゲティングと画面表示時間トリガーについては、screenを呼び出してください。ガイドとサーベイでは、画面の文字列（たとえば「HomeScreen」）をガイドまたはサーベイページのターゲティングセクション内の文字列と比較します。

// Track screen views to trigger guides based on screens
amplitudeEngagement.screen("HomeScreen")

エレメントターゲティングを有効にする

ピン、ツールチップ、カード埋め込みガイドでは、SDK が画面上の特定の要素をターゲットにする必要があります。

Jetpack Composeのピンとツールチップ

Amplitude Engagement の.amplitudeView修飾子を使用して、ピンやツールチップについて Jetpack Compose ビューにタグ付けします。 AmplitudeEngagementのインスタンスを .amplitudeView にパラメータとして渡します。 CompositionLocalProviderを構成してビュー階層内でアクセスするか、コンポーザブルビューにインスタンスをパラメータとして渡します。

// Jetpack Compose tagging for pins and tooltips
@Composable
fun MyView() {
    // Use your instance of Amplitude Engagement by creating a Composition context or passing as a param
    val engagement = LocalEngagement.current
    Box {
        Button(
            modifier = Modifier.amplitudeView(
                engagement,
                tag = "my-button",
                onTrigger = {
                    // Optional code to run with tap element action
                }
            )
        )
    }
}

Jetpack Compose カード埋め込み

カードの埋め込みには、.amplitudeView 修飾子ではなく AmplitudeView コンポーザブルが必要です。AmplitudeView はコンテンツをラップするため、SDK はターゲットの前後、またはターゲットの代わりにカードを挿入できます。修飾子は親レイアウトに兄弟コンテンツを挿入することはできません。

次の例では、ガイドとサーベイのダッシュボードで要素ターゲット文字列としてwelcome-bannerを使用してください。

import com.amplitude.android.engagement.ui.anchoring.AmplitudeView
@Composable
fun MyView() {
    val engagement = LocalEngagement.current
    AmplitudeView(
        engagement = engagement,
        tag = "welcome-banner",
    ) {
        Text("Welcome")
    }
}

Jetpack Compose の ProGuard ルール

リリースビルドで ProGuard または R8 コード縮小を有効にしている場合は、アプリのproguard-rules.proファイル (または同等の ProGuard 設定) にルールを追加してください。 コードの圧縮を行うと、ガイドおよびサーベイ SDK が要素タグを解決し、Compose 要素にピン、ツールチップ、カードの埋め込みを配置するために使用する Jetpack Compose のメタデータとアノテーションが削除される可能性があります。

ProGuardの設定に以下を追加してください。

-keepclassmembers class androidx.compose.ui.platform.AndroidComposeView {
  androidx.compose.ui.semantics.SemanticsOwner semanticsOwner;
}
# Keep Jetpack Compose runtime and compiler tags
# (This allows analytics tools to read composable structures)
-keep class androidx.compose.runtime.** { *; }
-keepclassmembers class * {
  @androidx.compose.runtime.* <fields>;
  @androidx.compose.runtime.* <methods>;
}
-keepnames class androidx.compose.ui.platform.** { *; }
# Keep attributes required for UI inspection and layout reflection
-keepattributes *Annotation*,Signature,InnerClasses,EnclosingMethod
-keepclassmembers class * {
  @com.amplitude.** <fields>;
  @com.amplitude.** <methods>;
}

これらのルールがなければ、ピン、ツールチップ、カード埋め込みは Jetpack Compose 画面で正しい対象要素に添付されない可能性があります。

Jetpack Compose 以外

ガイドとサーベイは、Jetpack Compose 以外のビューもサポートしています。SDKは、tag、contentDescription、またはresourceNameの各フィールドを使用して、一致するセレクターを確認します。これらのうち 1 つだけを設定する必要があります。

これは既存のレイアウト XML で設定するか、ビューインスタンスのプロパティを設定することでプログラムで設定できます。

<!-- in my_layout.xml -->
<LinearLayout>
    <!-- Set either contentDescription or tag to your desired selector -->
    <Button
        android:contentDescription="my-button"
        android:tag="my-button" />
</LinearLayout>

// Non Jetpack Compose Programmatic Tagging
val button = Button(this)
// Set the contentDescription
button.contentDescription = "my-button"
// Or set the tag
button.tag = "my-button"

ローカリゼーション

ガイドやアンケートをローカライズするには、初期化時にlocaleオプションを設定します。 言語またはロケールを設定しない場合、Amplitudeはデフォルトの言語を使用します。

// Set locale during initialization
val amplitudeEngagement = AmplitudeEngagement(
    context = applicationContext,
    apiKey = "YOUR_API_KEY",
    options = AmplitudeInitOptions(locale = "fr-FR")
)

SDK の初期化後に言語を動的に更新するには、このupdateLanguageメソッドを使用します。 呼び出しを行うと、新しいロケールで設定がupdateLanguage再取得されます。

amplitudeEngagement.updateLanguage(locale: String)

// Example: Update language to French with full locale
amplitudeEngagement.updateLanguage("fr-FR")
// Example: Update language to English with language code
amplitudeEngagement.updateLanguage("en")

その他のSDKメソッド

Amplitude Guides and Surveys 用の Android SDK には、以下の追加メソッドが含まれています。

• ライフサイクル: enable()と disable()を使用して、ガイドやサーベイを一時停止または再開できます。
• ターゲティングの更新: refresh() を使用して、ターゲティングデータを手動で更新します。ブート後の自動更新間隔を変更または無効にするには、setAutoRefreshInterval()を使用してください。
• テーマの管理: setThemeMode を使用して、ガイドやサーベイの視覚的なテーマ (ライト、ダーク、または自動) を設定します。
• コールバックを追加する: 名前付きのコールバックを登録し、[コールバックを実行] アクションを使用してガイドやサーベイからそれらをトリガーしてカスタムアプリロジックを実行します。
• ルーター設定: setRouterでルーターコールバックを定義して、ガイドやサーベイがアプリ内の画面ナビゲーションをどのように処理するかをカスタマイズします。
• ガイド/サーベイのリセット: reset を使用して、ガイドまたはサーベイを特定のステップに戻します。
• ガイド/サーベイの一覧表示: list()メソッドを使用して、公開中のガイドとサーベイの完全なリストとその現在のステータスを取得します。
• スマート インタラクション: キャッシュされたレイジタップ、非アクティブ、要素タップの状態をクリアするには resetSmartInteractions() を使用します。

SDKを有効化および無効化する

disable()を使用して、ガイドやサーベイが一時的に表示されないようにしたり、現在表示されているものを非表示にしたりします。通常動作を再開するには、enable()を使用してください。

// Temporarily disable the SDK
amplitudeEngagement.disable()
// Re-enable the SDK
amplitudeEngagement.enable()

ターゲティングデータを更新する

refresh() を使用して、ユーザープロパティの更新後に Amplitude からターゲティング評価を再取得します。ガイドまたは調査が表示されている場合、SDKは更新をスキップします。

amplitudeEngagement.refresh()

自動更新間隔を設定する

ターゲット設定データの定期的な更新を有効にします。 これは、ブート後に呼び出して間隔を変更または無効にできます。有効な場合、最小間隔は60秒です。無効にするには、0 または負の値に設定します。

amplitudeEngagement.setAutoRefreshInterval(seconds = 3600) // Every hour
amplitudeEngagement.setAutoRefreshInterval(seconds = 0)    // Disable

テーマを管理

アプリケーションがライトモードとダークモードをサポートしている場合は、ビジュアルテーマモードを設定してください。

// Set the theme mode
amplitudeEngagement.setThemeMode(ThemeMode.DARK) // Options: AUTO, LIGHT, DARK

コールバックを登録する

ガイドまたはサーベイボタンの「コールバックを実行」アクションを設定して、コールバックを実行します。

engagement.addCallback(key: String, func: () -> Unit)

engagement.addCallback("show-alert") {
    this.runOnUiThread {
        android.app.AlertDialog.Builder(this)
            .setTitle("Callback")
            .setMessage("Callback has been executed!")
            .setPositiveButton("OK", null)
            .show()
    }
}

ルータの設定

ガイドとサーベイが画面ナビゲーションを処理する方法を設定します。

engagement.setRouter { identifier ->
    // Your screen handling and navigation
}

ルーターを削除するには、unsetRouter() にお電話ください。

amplitudeEngagement.unsetRouter()

リセット

ガイドやサーベイを特定のステップにリセットできます。

amplitudeEngagement.reset(key = "GUIDE_KEY", stepIndex = 0)

List

すべてのライブガイドとサーベイのリストとそのステータスを取得できます。

val guidesAndSurveys = amplitudeEngagement.list()

表示する

特定のガイドやアンケートを表示します。画面ターゲット設定以外のターゲット設定ルールや制限を無視します。

amplitudeEngagement.show(key = "GUIDE_KEY")

イベントを転送する

Amplitude Analytics Android SDKプラグインを使用していない場合（つまり、boot直接呼び出した場合）、forwardEventを使用してガイドとサーベイで_On event tracked_トリガーを有効にしてください。転送されたイベントはAmplitudeサーバーに送信されません。 SDK はこれらをローカル トリガー評価にのみ使用します。

// Forward events from Amplitude to trigger guides
val event = BaseEvent()
amplitudeEngagement.forwardEvent(event)

スマートなインタラクションをリセットする

レイジタップ、ユーザーの非アクティブ状態、要素タップ検出など、スマートインタラクション検出器からキャッシュされた状態をすべてクリアするためにresetSmartInteractions()呼び出します。

amplitudeEngagement.resetSmartInteractions()

すべて閉じる

アクティブなすべてのガイドとサーベイを閉じます。

amplitudeEngagement.closeAll()

スーパーデバッガー

AmplitudeダッシュボードからプレビューQRコードをスキャンすると、画面下部に小さなAmplitudeロゴが表示されます。 これをタップすると、スーパーデバッガーパネルが開きます。

スーパーデバッガーには、詳細と設定という2つのタブがあります。

詳細タブ

_詳細_タブには、プレビューしているガイドまたはサーベイに関する情報が表示され、プレビューセッションの確認と制御を行うことができます。

ガイド / サーベイ：アクティブなガイドまたはサーベイの名前。タップすると、別のガイドやアンケートに切り替えることができます。

詳細:

• ステップ: 全ステップ数に対する現在のステップ番号 (たとえば、「1/3」)。コピーアイコンをタップして値をコピーします。
• ユーザー：プレビューセッションのユーザーID。コピーアイコンをタップしてコピーします。
• 画面：SDKが現在レポートしている画面名です。コピーアイコンをタップしてコピーします。

デバッグ: ガイドまたは調査が各条件チェックに合格したかどうかを示します。 各行が展開され、詳細が表示されます。

• 制限：ガイドまたはサーベイが表示制限に達したかどうか。展開して設定済みの制限を確認します。 制限を設定している場合は、ユーザー履歴のリセット をタップして履歴をリセットし、ガイドやアンケートを再度表示できるようにします。
• トリガー：ガイドまたは調査がトリガー条件を満たしているかどうか。展開すると、トリガータイプ、画面条件、ピンターゲット要素（該当する場合）を確認できます。
• スロットル：ガイドまたはサーベイがスロットル条件を満たしているかどうか。展開してスロットル設定を確認します。 <2>制限を無視する〼/2>をおんにすると、プレビューセッション中にスロットル制限を回避できます。

詳細設定：

• ピンのデバッグ：展開して、5秒ごとにピンの位置変更を有効にします。デバッガは定期的にピンの位置を再評価し、動的レイアウトでのピンの配置をデバッグするのに役立ちます。

パネルの下部：

• プレビューを再起動：ガイドまたは調査を最初のステップにリセットし、プレビューを再起動します。
• プレビューを閉じる: プレビュー モードを終了し、スーパー デバッガを閉じます。

設定タブ

_設定_タブには、現在のセッションのSDK設定と環境の詳細が表示されます。

SDK バージョン: アプリにインストールされている Engagement SDK のバージョンです。

インストール：

• タイプ：SDKのインストール方法（プラグインまたはスタンドアロンなど）。
• 構成：適用されるカスタム構成オプションの数とタイプ。

ユーザー:

• ユーザー ID: 起動時にSDKに渡されるユーザーIDです。
• プロパティ: 現在のセッションに設定されているすべてのユーザー プロパティ。

イベントフロー：イベントが正しく流れているかどうかを確認します：

• ガイドとサーベイSDKに流入するイベント: アナリティクスインスタンスからのイベントは、エンゲージメントSDKに到達します。
• Guides and Surveys SDKから送出されるイベント：Engagement SDKがイベントをAmplitudeに送信します。

サポート

**？**をタップします。_サポート_パネルを開くためのボタン。ここから次のことができます：

• SDKドキュメントやガイドとサーベイの概要へのリンクを開きます。
• バグレポートを提出する：デバッガーから直接バグレポートを送信できます。再現するステップ、予想される結果、実際の結果を入力してから、送信をタップします。

既知の制限事項

オフラインサポートなし

SDKは、ガイドやサーベイを取得して表示するためにアクティブなインターネット接続を必要とします。アプリが最初にロードされたときにデバイスがオフラインの場合、そのアプリセッションのガイドやサーベイは表示されません。

アニメーション化された要素と移動するコンテナ内の要素をターゲットに設定する

ピンやツールチップは、次のようなビューや要素をターゲットにすることはできません。

• アニメーション化されているか、アニメーション化されたコンテナ内にあります（画面上を移動します）。
• ユーザーの操作に基づいて移動できるコンテナ内。

変更履歴

モバイルSDKの変更履歴にアクセスしてください。