メインコンテンツまでスキップ

Android SDK 統合ガイド

このページでは、Rokt Ads の Android SDK を実装して、チェックアウト時により関連性の高い顧客体験を提供する方法を説明します。SDK を使用すると、設定されたページで発火し、ユーザーとトランザクションデータを Rokt に戻してパーソナライズと測定を行うことで、これらの体験（確認ページでのオファー表示など）をトリガーおよび追跡できます。

専任のアカウント担当者が、Android SDK 用にアカウントを設定するのをサポートします。彼らは SDK を初期化するために必要な key と secret、および顧客に最も関連性の高い体験を提供するために必要な追加リソースを提供します。

注記

これらの指示を完了するには開発リソースが必要です。追加の支援が必要な場合は、Rokt のアカウントマネージャーにお問い合わせください。

1. 依存関係を追加する​

SDK に必要な依存関係を含めるように gradle ファイルを更新します:

dependencies {
    implementation("com.mparticle:android-rokt-kit:5.74.0")
    implementation("com.mparticle:android-core:5.74.0")
}

2. アプリで SDK を初期化する​

Android SDK は、Application クラスの onCreate() 内で MParticleOptions オブジェクトとビルダークラスを使用して構成できます。mParticle Android SDK は、他の SDK API 呼び出しが行われる前に初期化される必要があります。

:::注意 上記のコードサンプル内の your-key と your-secret を、専任のRoktアカウント担当者から提供されたキーとシークレットに置き換えてください。 :::

import com.mparticle.MParticle
import com.mparticle.MParticleOptions

class YourApplicationClass : Application() {
    override fun onCreate() {
        super.onCreate()
        // 現在のユーザーを識別します:
        // ユーザーのメールアドレスがない場合は、null値を渡すことができます
        val identifyRequest = IdentityApiRequest.withEmptyUser()
        // 未ハッシュのメールアドレスを使用している場合は、'email'に設定します。
        .email("j.smith@example.com")
        .build()
        // ユーザーがメールアドレスで識別されている場合、追加のユーザー属性を設定します。
        val identifyTask = BaseIdentityTask()
            .addSuccessListener { identityApiResult ->
                val user = identityApiResult.user
                user.setUserAttribute("example attribute key", "example attribute value")
            }
        val options: MParticleOptions = MParticleOptions.builder(this)
        .credentials(
            "your-key",   // Roktアカウント担当者から提供されたキー
            "your-secret" // Roktアカウント担当者から提供されたシークレット
        ).environment(MParticle.Environment.Development)  // 環境を指定します:
        // 統合をテスト中の場合は.developmentに設定します。
        // 統合が本番データに対応している場合は.productionに設定します。
        // デフォルトは.autoDetectで、環境を自動的に検出しようとします
        .build()

        MParticle.start(options)
    }
}
注意

上記のコードサンプル内の your-key と your-secret を、専任のRoktアカウント担当者から提供されたキーとシークレットに置き換えてください。

ユーザーを識別する​

SDKが初期化されると、現在のユーザーを識別することができ、収集されたデータが正しくそのユーザーに帰属され、彼らの行動に基づいて最も関連性の高い広告が表示されるようにします。

SDKの初期化スクリプトには、identifyRequest というオブジェクトが含まれています:

val identifyRequest = IdentityApiRequest.withEmptyUser()
.email("j.smith@example.com")
.build()

identifyRequest 内で、ユーザーのメールアドレスを email フィールドに渡します。

追加のユーザー属性を設定する​

初期化スクリプトには、ユーザーがメールアドレスで正常に識別された場合に追加のユーザー属性を設定できるコールバック関数が含まれています:

val identifyTask = BaseIdentityTask()
.addSuccessListener { identityApiResult ->
    val user = identityApiResult.user
    user.setUserAttribute("example attribute key", "example attribute value")
}

3. ユーザーを識別する​

ユーザーがメールアドレスを提供するたびに（例えば、ログイン時や購入時）、そのメールをRoktに渡すためにidentifyメソッドを呼び出す必要があります。これにより、データが現在のユーザーに正しく帰属されます。

3.1 identifyRequest を作成する​

ユーザーを識別するために、まずユーザーのメールアドレスを含む identifyRequest オブジェクトを作成します。

ハッシュされていないメールアドレスを提供する場合は、以下を使用します:

val identifyRequest = IdentityApiRequest.withEmptyUser()
    .email("j.smith@example.com")
    .build()

3.2 追加のユーザー属性を設定する​

次に、ユーザーを識別する際にコールバック関数を作成して追加のユーザー属性を設定するオプションがあります。identifyRequest が成功すると、setUserAttribute で設定したユーザー属性がそのユーザーに割り当てられます。

val identifyTask = BaseIdentityTask()
    .addSuccessListener { identityApiResult ->
        val user = identityApiResult.user
        user.setUserAttribute("example attribute key", "example attribute value")
    }

3.3 identify メソッドを呼び出す​

最後に、identifyRequest と identityCallback を作成した後、追加の属性を設定するために、作成した identifyRequest と identityCallback オブジェクトを渡して identify メソッドを呼び出します:

MParticle.getInstance()?.Identity()?.identify(identifyRequest)

例えば、Jane Smith という名前のユーザーを j.smith@example.com というメールアドレスで識別する場合（メールアドレスをハッシュする必要がない場合）は、次のようにします:

val identifyRequest = IdentityApiRequest.withEmptyUser()
    .email("j.smith@example.com")
    .build()

val identifyTask = BaseIdentityTask()
.addSuccessListener { identityApiResult ->
    val user = identityApiResult.user
    user.setUserAttribute("example attribute key", "example attribute value")
}

MParticle.getInstance()?.Identity()?.identify(identifyRequest)

4. ユーザー属性の追跡​

Rokt SDKを使用して、イベントとは別にユーザー属性を収集することができます。ユーザー属性は、イベントを追跡する際のカスタム属性とは別です。SDKは、特定のセッションで収集されたユーザー属性を、同じセッションでトリガーされたイベントと関連付けます。

ユーザー属性を収集するには、Rokt SDKを初期化した直後に、イベントをログに記録する前に、次のコードをアプリで実行する必要があります。

import com.mparticle.MParticle

// 現在のユーザーを取得します。これは、SDKの初期化中にユーザーを識別した場合、またはidentifyメソッドを呼び出した場合にのみ成功します。
val currentUser = MParticle.getInstance()?.Identity()?.currentUser

// `currentUser`に現在のユーザーを正常に設定したら、次のようにしてユーザー属性を設定できます:
currentUser?.setUserAttribute("custom-attribute-name", "custom-attribute-value")
// 注意: すべてのユーザー属性（リスト属性やタグを含む）は、異なる名前を持つ必要があります。

// Roktは、可能な限り多くの次のユーザー属性を設定することを推奨します:
currentUser?.setUserAttribute("firstname", "John")
currentUser?.setUserAttribute("lastname", "Doe")
// 電話番号は '1234567890' または '+1 (234) 567-8901' の形式でフォーマットできます
currentUser?.setUserAttribute("mobile", "3125551515")
currentUser?.setUserAttribute("age", "33")
currentUser?.setUserAttribute("gender", "M")
currentUser?.setUserAttribute("city", "Brooklyn")
currentUser?.setUserAttribute("state", "NY")
currentUser?.setUserAttribute("zip", "123456")
currentUser?.setUserAttribute("dob", "yyyymmdd")
currentUser?.setUserAttribute("title", "Mr")
currentUser?.setUserAttribute("language", "en")
currentUser?.setUserAttribute("value", "52.25")
currentUser?.setUserAttribute("predictedltv", "136.23")

// 値のリストを含むユーザー属性を作成することができます
val attributeList = ArrayList<String>()
attributeList.add("documentary")
attributeList.add("comedy")
attributeList.add("romance")
attributeList.add("drama")
currentUser?.setUserAttributeList("favorite-genres", attributeList)

// ユーザー属性を削除するには、removeUserAttributeを呼び出し、属性名を渡します。すべてのユーザー属性は同じキー空間を共有します。
currentUser?.removeUserAttribute("attribute-to-remove")

5. 画面ビューのキャプチャ​

最も基本的なイベントタイプの1つは、画面ビューを追跡することです。画面ビューをログに記録するには、画面が読み込まれるとすぐに MParticle.getInstance().logScreen() メソッドを呼び出し、画面の名前を文字列として渡し、任意の説明属性を含むハッシュマップをオプションで渡します。

渡す名前は、'homepage' や 'product detail page' のような限られたセットの画面の1つであるべきです。

import com.mparticle.MParticle

val screenInfo = HashMap<String, String>()
screenInfo["rating"] = "5"
screenInfo["property_type"] = "hotel"

MParticle.getInstance()?.logScreen("Details", screenInfo)

6. コンバージョンの追跡​

コンバージョンを追跡するには、顧客がコンバージョンした後に読み込まれる最も適切なページ、例えば購入確認ページや「ありがとう」ページで次のコードスニペットを実行します。

コードスニペットをサイトに貼り付ける際には、以下を確認してください：

  1. setUserAttribute 呼び出しのサンプルユーザー属性を、ユーザーまたは顧客の実際の値に置き換えます。Roktは少なくとも以下のユーザー属性を設定することを推奨します：
    • firstname
    • lastname
    • zipcode
    • mobile
  2. サンプルのコンバージョンイベント属性を、コンバージョンイベントの実際の値に置き換えます。

コンバージョンイベントをログに記録する際には、できるだけ多くのユーザー属性とイベント属性を含めることで、Roktのキャンペーン最適化能力を向上させることができます。

MParticleUser currentUser = MParticle.getInstance().Identity().getCurrentUser();
currentUser.setUserAttribute("firstname", "John");
currentUser.setUserAttribute("lastname", "Doe");
currentUser.setUserAttribute("mobile", "3125551515");
currentUser.setUserAttribute("zip", "98103");

val customAttributes = mapOf(
    "conversiontype" to "signup",   // コンバージョンの種類
    "confirmationref" to "54321",   // トランザクションID / 注文ID
    "amount" to "",                 // トランザクション金額 例: 300.5
    "currency" to "",               // トランザクション通貨 例: USD
    // 独自のカスタムイベント属性を追跡できます！
    "CUSTOM_EVENT_ATTRIBUTE_NAME" to "CUSTOM_EVENT_ATTRIBUTE_VALUE"
)

val event = MPEvent.Builder("conversion", MParticle.EventType.Transaction)
    .customAttributes(customAttributes)
    .build()

MParticle.getInstance()?.logEvent(event)

付録​

KotlinとJavaの両方でサポートされているカスタムイベントタイプは次のとおりです:

  • Navigation - アプリ内でのユーザーのナビゲーションフローとページ遷移を追跡
  • Location - ユーザーの位置情報に基づくインタラクションと移動を記録
  • Search - 検索クエリと検索関連のユーザーアクションをキャプチャ
  • Transaction - 金銭取引と購入関連の活動をログ
  • UserContent - レビュー、コメント、投稿などのユーザー生成コンテンツを追跡
  • UserPreference - ユーザー設定、好み、カスタマイズの選択を記録
  • Social - ソーシャルメディアのインタラクションと共有活動をキャプチャ
val customAttributes = mapOf(
"category" to "Destination Intro",
"title" to "Paris",
)

val event = MPEvent.Builder("Video Watched", EventType.Navigation)
.customAttributes(customAttributes)
.build()

MParticle.getInstance()?.logEvent(event)

コマースイベントのトラッキング​

コマースイベントをトラッキングするには、以下の3つのステップが必要です：

  1. 購入される商品または商品の定義
  2. 取引概要を含むオブジェクトの作成
  3. 商品の定義と取引概要を含むイベントのログ記録
import com.mparticle.commerce.CommerceEvent
import com.mparticle.commerce.Product
import com.mparticle.commerce.TransactionAttributes

// 1. 商品を作成

// 商品のカスタム属性を文字列のキー/バリューペアとしてオプションで作成
val customAttributes = mutableMapOf<String, String>()
customAttributes["ocean-view"] = "true"
customAttributes["balcony"] = "false"

val product = Product.Builder("Double Room - Econ Rate", "econ-1", 100.00)
    .quantity(4.0)
    // 上で作成したカスタム属性のマップを含める
    .customAttributes(customAttributes)
    .build()

// 2. 取引を要約

val attributes = TransactionAttributes("foo-transaction-id")
    .setRevenue(430.00)
    .setTax(30.00)

// 3. 購入イベントをログ記録

val event = CommerceEvent.Builder(Product.PURCHASE, product)
    .transactionAttributes(attributes)
    // 購入イベントのオプションのカスタム属性をキー/バリューペアのマップとして追加可能
    .customAttributes(mapOf("sale" to "true", "phone-booking" to "true"))
    // カスタム属性ビルダーメソッドに渡されるマップを作成することも可能。例：
    //    val customTransactionAttributes = mutableMapOf<String, String>()
    //    customTransactionAttributes["sale"] = "true"
    //    customTransactionAttributes["phone-booking"] = "true"
    //    .customAttributes(customTransactionAttributes)
    .build()

MParticle.getInstance()?.logEvent(event)
この記事は役に立ちましたか？
Last updated Oct 29, 2025