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

Android SDK 統合ガイド

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

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

注記

これらの手順を完了するには、開発リソースが必要です。追加の支援が必要な場合は、Rokt のアカウントマネージャーにご連絡ください。Shopify ストアは、Rokt Ecommerce アプリ を使用して数秒で Rokt プレースメントを設定できます — コーディングは不要です!

1. 依存関係を追加する

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

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

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

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

注意

上記のコードサンプルでyour-keyyour-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-keyyour-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")
}

フォントを使用した初期化

One Platformで希望のフォントを提供する代わりに、または追加で、アプリケーションに既にバンドルされているフォントを利用することを選択できます。これにより、初期化時にフォントをダウンロードする可能性を排除し、ネットワーク使用率を低減し、ダウンロードエラーの可能性を減少させる利点があります。アプリケーションの assets ディレクトリにあるフォントリソースを使用するか、独自の Typeface オブジェクトを渡すことを選択できます。

フォントアセットの使用

アプリケーションの assets ディレクトリに保存されたフォントを利用することができます。このために、init メソッドにフォントのポストスクリプト名をアセットディレクトリ内のファイルパスにマップするマップを渡すことができます(アセットディレクトリはルートディレクトリ)。ポストスクリプト名はレイアウトで使用されているものと一致する必要がありますので、わからない場合はアカウントマネージャーに確認してください。

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

class YourApplication : Application() {
override fun onCreate() {
...
val options: MParticleOptions = MParticleOptions.builder(this)
.credentials(
"your-key", // Roktアカウント担当者によって提供されたキー
"your-secret" // Roktアカウント担当者によって提供されたシークレット
).environment(MParticle.Environment.Development) // データ環境を指定します:
.roktOptions(RoktOptions(fontFilePathMap = mapOf("Arial-Bold" to "fonts/arialbold.otf")))
.build()
MParticle.start(options)
...
}
}

3. ユーザーを識別する

SDKが初期化された後にユーザーがメールアドレスを提供するたびに(例えば、ログインや購入時)、identifyメソッドを呼び出して、そのメールをRoktに渡す必要があります。これにより、データが現在のユーザーに正しく関連付けられます。

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 メソッドを呼び出す

最後に、identifyRequestidentityCallback を作成した後、追加の属性を設定するために、作成した identifyRequestidentityCallback オブジェクトを渡して、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)

3. ユーザー属性の追跡

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")

4. ファネルイベントのキャプチャ

Rokt SDK を使用すると、イベント追跡を実装して、アプリ内でのユーザーの旅を説明するデータを収集できます。このデータを使用して、ユーザーの体験を最適化することができます。

SDK で記録できる主なイベントタイプは次の3つです:

  • スクリーンビューイベント: これは、アプリの画面が読み込まれたときにトリガーできるイベントです。
  • カスタムイベント: アプリ独自の情報を追跡するために作成する自由形式のイベントです。
  • コマースイベント: 電子商取引に特化したイベントで、カートへの商品追加や最終購入を含むショッピング体験のさまざまな段階を説明できます。

Rokt SDK のインテグレーションを初めて行う場合は、まずスクリーンビューの追跡を実装してください。カスタムイベントとコマースイベントの追跡については、Appendix を参照してください。

スクリーンビューを追跡する

追跡できる最も基本的なイベントタイプの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)

5. プレースメントを表示する

Rokt SDK の主な価値は、selectPlacements メソッドを通じてアンロックされます。これにより、提供する属性に基づいて顧客に対して非常に関連性の高いプレースメント(またはレイアウト)が提供されます。

Rokt の統合が初期化されたら、レイアウトがレンダリングされるページから selectPlacements メソッドを呼び出すことができます。これをできるだけ早く、必要なすべての属性が利用可能になった時点で呼び出すべきであり、ユーザーに最適なエクスペリエンスを確保します。

selectPlacements を呼び出す際には、少なくとも emailfirstnamelastnamebillingzipcode、および confirmationref 属性を提供しなければなりません。

オーバーレイプレースメント

val attributes = mapOf(
"email" to "j.smith@example.com",
"firstname" to "Jenny",
"lastname" to "Smith",
"billingzipcode" to "90210",
"confirmationref" to "54321",
)

// プレースメントにカスタムフォントを使用する場合、fontTypefaces マップを作成します
val fontTypefaces: MutableMap<String, WeakReference<android.graphics.Typeface>> = HashMap<String, WeakReference<android.graphics.Typeface>>()
fontTypefaces["Arial-Bold"] = WeakReference<android.graphics.Typeface>(yourTypefaceObject)

// また、プレースメント UI をカスタマイズできる `RoktConfig` などのオプションパラメータを渡すことも検討してください。特にアプリがダークモードまたはライトモードかどうかに基づきます。埋め込みビューやコールバックなどの追加のオプションパラメータは下に示されています。

val roktConfig = RoktConfig.Builder().colorMode(RoktConfig.ColorMode.LIGHT).build()

MParticle.getInstance()?.Rokt()?.selectPlacements(
identifier = "RoktExperience",
attributes = attributes,
fontTypefaces = fontTypefaces,
config = roktConfig,
embeddedViews = null, // オプションのプレースホルダー(以下の埋め込みプレースメントを参照)
callbacks = null, // オプションのコールバック(必要に応じて定義、以下参照)
)
注記

RoktExperience のビュー名や RoktEmbedded1 のプレースホルダー名を別の値に更新したい場合は、Rokt プレースメントが一貫して構成されるように、Rokt アカウント マネージャーに連絡してください。

サポートされている属性の完全なリストについては、Data Attributes を参照してください。

専任の Rokt チームが、ブランドと UX スタイルガイドに一致するように プレースメント レイアウト を設定します。

オプション関数

関数目的
Rokt.close()オーバーレイ配置を自動で閉じるために使用されます。

埋め込み配置

埋め込み配置は、UIに配置ビューを埋め込むことができる点を除いて、上記のオーバーレイ配置と同じ推奨事項と要件を共有しています。このセクションでは、Roktを通じて許可されるさまざまな高度な機能の例も提供します。Roktを通じてcallbacksパラメータに渡されるMpRoktEventCallbackクラスを使用すると、配置を生成および表示する際に発生するさまざまなイベントに対応できます。

Androidアプリが埋め込みレイアウトを必要とする場合は、RoktEmbeddedViewをレイアウトXMLファイルに追加します。

注記

これは埋め込みレイアウトを必要とするアプリにのみ適用されます。

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".MainActivity">

<com.mparticle.rokt.RoktEmbeddedView
android:id="@+id/roktEmbeddedView"
android:layout_width="match_parent"
android:layout_height="wrap_content"
app:layout_constraintEnd_toEndOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

配置の高さを動的に設定できるようにするため、配置の高さをwrap_contentに設定することをお勧めします。

import com.mparticle.rokt.RoktConfig
import com.mparticle.rokt.RoktEmbeddedView
import com.mparticle.MpRoktEventCallback
import com.mparticle.UnloadReasons

class ConfirmActivity : Activity() {
val callbacks = object : MpRoktEventCallback {
override fun onLoad() {
// Rokt配置が読み込まれたときのオプションのコールバック
}

override fun onUnload(reason: UnloadReasons) {
```kotlin
// Rokt配置がアンロードされるときのオプションのコールバック
}

override fun onShouldShowLoadingIndicator() {
// ローディングインジケータを表示するためのオプションのコールバック
}

override fun onShouldHideLoadingIndicator() {
// ローディングインジケータを非表示にするためのオプションのコールバック
}
}

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val instance = MParticle.getInstance()
setContentView(R.layout.activity_main)
val attributes = hashMapOf(
Pair("email", "j.smith@example.com"),
Pair("firstname", "Jenny"),
Pair("lastname", "Smith"),
Pair("mobile", "(323) 867-5309"),
Pair("postcode", "90210"),
Pair("country", "US"),
)
val roktWidget = findViewById<RoktEmbeddedView>(R.id.roktEmbeddedView)
val placeHolders = mapOf(Pair("RoktEmbedded1", WeakReference(roktWidget)))
val fontTypefaces: MutableMap<String, WeakReference<android.graphics.Typeface>> = HashMap<String, WeakReference<android.graphics.Typeface>>()
fontTypefaces["Arial-Bold"] = WeakReference<android.graphics.Typeface>(yourTypefaceObject)

val roktConfig = RoktConfig.Builder().colorMode(RoktConfig.ColorMode.LIGHT).build()

instance?.Rokt()?.selectPlacements(
identifier = "RoktExperience",
attributes = attributes,
fontTypefaces = fontTypefaces,
callbacks = callbacks,
embeddedViews = placeHolders,
config = roktConfig
)
}
}

グローバルイベントAPI

SDKは、Rokt.globalEvents APIを通じてストリームとしてステータスを提供します。SDKユーザーは、Kotlin Flowのメカニズムを利用してステータスを消費できます。

import com.rokt.roktsdk.RoktEvent

// owner: LifecycleOwner
owner.lifecycleScope.launch {
Rokt.globalEvents().collect { event ->
if (event is RoktEvent.InitComplete)
Log.d("Rokt", "received init completed $event")
}
}

イベント

SDKは、MParticle.getInstance()?.Rokt()?.events APIを通じて、各ページのイベントをストリームとして提供します。SDKユーザーは、Kotlin Flowのメカニズムを利用して、SDKが生成したイベントを消費できます。

import com.mparticle.MParticle

// owner: LifecycleOwner
owner.lifecycleScope.launch {
owner.lifecycle.repeatOnLifecycle(Lifecycle.State.CREATED) {
MParticle.getInstance()?.Rokt()?.events("RoktExperience").collect { roktEvent ->
Log.d("RoktEvent", "Event received $roktEvent")
}
}
}
イベント説明パラメータ
ShowLoadingIndicatorSDKがRoktのバックエンドを呼び出す前にトリガーされます
HideLoadingIndicatorSDKがRoktのバックエンドから成功または失敗を受け取ったときにトリガーされます
OfferEngagementユーザーがオファーにエンゲージしたときにトリガーされますplacementId: String
PositiveEngagementユーザーがオファーに積極的にエンゲージしたときにトリガーされますplacementId: String
FirstPositiveEngagementユーザーが初めてオファーに積極的にエンゲージしたときにトリガーされますplacementId: String, fulfillmentAttributes: FulfillmentAttributes
PlacementInteractiveプレースメントがレンダリングされ、インタラクティブになったときにトリガーされますplacementId: String
PlacementReadyプレースメントが表示する準備ができているが、まだコンテンツがレンダリングされていないときにトリガーされますplacementId: String
PlacementClosedユーザーによってプレースメントが閉じられたときにトリガーされますplacementId: String
PlacementCompletedオファーの進行が終了し、表示するオファーがこれ以上ないときにトリガーされます。
また、キャッシュがヒットしたが、取得したプレースメントが以前に解約されたため表示されないときにもトリガーされます
placementId: String
PlacementFailure何らかの失敗によってプレースメントを表示できなかった場合、または表示するプレースメントがないときにトリガーされますplacementId: String (optional)
OpenUrlパートナーアプリに送信するように設定されたURLがユーザーによって押されたときにトリガーされますplacementId: String, url: String
CartItemInstantPurchaseカタログアイテムの購入がユーザーによって開始されたときにトリガーされますplacementId: String, cartItemId: String, catalogItemId: String, currency: String, description: String, linkedProductId: String, totalPrice: Double, quantity: Int, unitPrice: Double

付録

デバッグ

Rokt.setLoggingEnabled(enable = true) APIを使用してRokt SDKからのデバッグログを有効にします。

アプリケーション設定の使用

アプリケーションは、独自のアプリケーション環境から設定を渡すことができます。これにより、Rokt SDKはシステムデフォルトに依存せずにアプリケーションのカスタム設定を使用できるようになります。

ColorModeオブジェクト
説明
LIGHTアプリケーションがライトモードになっています
DARKアプリケーションがダークモードになっています
SYSTEMアプリケーションがシステムカラーモードのデフォルトになっています
EdgeToEdgeDisplay ブール値
説明
true(デフォルト)アプリケーションはエッジトゥエッジ表示モードをサポートしています
falseアプリケーションはエッジトゥエッジ表示モードをサポートしていません
import com.mparticle.MParticle
import com.mparticle.rokt.RoktConfig

// アプリケーションがライトモードのみをサポートし、エッジトゥエッジ表示が有効になっている場合。
val roktConfig = RoktConfig.Builder()
.edgeToEdgeDisplay(true)
.build()

MParticle.getInstance()?.Rokt()?.selectPlacements(
identifier = "RoktExperience",
attributes = attributes,
config = roktConfig
)
CacheConfig オブジェクト
パラメータ説明
cacheDurationRokt SDK がエクスペリエンスをキャッシュする秒数のオプションの期間です。許可される最大値は90分で、デフォルト(値が提供されていない場合や無効な場合)は90分です。
cacheAttributesキャッシュキーとして使用されるオプションの属性です。nullの場合、selectPlacementsで送信されるすべての属性がキャッシュキーとして使用されます。
import com.mparticle.rokt.CacheConfig
import com.mparticle.rokt.RoktConfig

// 1200秒間エクスペリエンスをキャッシュし、メールと注文番号の属性をキャッシュキーとして使用します。
val roktConfig = RoktConfig.Builder()
.cacheConfig(CacheConfig(
cacheDurationInSeconds = 1200,
cacheAttributes = mapOf("email" to "j.smith@example.com", "orderNumber" to "123")
))
.build()

MParticle.getInstance()?.Rokt()?.selectPlacements(
identifier = "RoktExperience",
attributes = attributes,
config = roktConfig
)

カスタムイベントをトラッキングする

上記の指示に従って、配置と画面ビューのトラッキングを実装した後、追加のイベントトラッキングを実装したい場合があります。

MPEvent.Builderオブジェクトを使い、イベント名、イベントタイプ、カスタム属性のマップを渡すことで、カスタムイベントを定義しトラッキングすることができます。

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

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

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"))
// カスタム属性を通過させるマップを作成して、customAttributes builderメソッドに渡すこともできる。例えば:
// val customTransactionAttributes = mutableMapOf<String, String>()
// customTransactionAttributes["sale"] = "true"
// customTransactionAttributes["phone-booking"] = "true"
// .customAttributes(customTransactionAttributes)
.build()

MParticle.getInstance()?.logEvent(event)
この記事は役に立ちましたか?