Android SDK 統合ガイド
このページでは、Rokt Ecommerce の Android SDK を実装して、チェックアウト時により関連性のある顧客体験を提供する方法を説明します。SDK により、設定されたページで発火してこれらの体験をトリガーおよび追跡し、ユーザーやトランザクションのデータを Rokt に返し、パーソナライズと測定を行うことができます(たとえば確認ページにオファーを表示するなど)。
専任のアカウント担当者が、Android SDK 用にアカウントを設定する手助けをします。彼らは SDK を初期化するために必要な key および secret と、顧客に最も関連性の高い体験を提供するために必要な追加リソースを提供します。
これらの手順を完了するには、開発リソースが必要です。追加の支援が必要な場合は、Rokt のアカウントマネージャーにご連絡ください。Shopify ストアは、Rokt Ecommerce アプリ を使用して数秒で Rokt プレースメントを設定できます — コーディングは不要です!
1. 依存関係を追加する
SDKに必要な依存関係を含めるようにgradleファイルを更新します:
- build.gradle.kts
- build.gradle
dependencies {
implementation("com.mparticle:android-rokt-kit:5.70.2")
implementation("com.mparticle:android-core:5.70.2")
}
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-key
とyour-secret
を、あなたの専任のRoktアカウント担当者から提供されたキーとシークレットに置き換えてください。
- Kotlin
- Java
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)
}
}
import com.mparticle.MParticle;
import com.mparticle.MParticleOptions;
public class YourApplicationClass extends Application {
@Override
public void onCreate() {
super.onCreate();
MParticleOptions options = MParticleOptions.builder(this)
.configuration(kitOptions)
.credentials(
"your-key", // Roktアカウント担当者によって提供されたキー
"your-secret" // Roktアカウント担当者によって提供された秘密
).environment(MParticle.Environment.Production).build(); // 環境を指定します:
// .development を選択すると、統合のテスト中です。
// .production を選択すると、統合は本番データに対応しています。
// デフォルトは .autoDetect で、自動的に環境を検出しようとします
// 現在のユーザーを識別します:
IdentityApiRequest identifyRequest = IdentityApiRequest.withEmptyUser()
// ユーザーのメール アドレスがない場合、null 値を渡すことができます
.email("j.smith@example.com").build();
// ユーザーがメールアドレスで識別されている場合、追加のユーザー属性を設定します。
BaseIdentityTask identifyTask = new BaseIdentityTask()
.addSuccessListener(new TaskSuccessListener() {
@Override
public void onSuccess(IdentityApiResult identityApiResult) {
MParticleUser user = identityApiResult.getUser();
user.setUserAttribute("example attribute key", "example attribute value");
}
});
MParticle.start(options);
}
}
your-key
と your-secret
を上記のコードサンプルで、あなた専用のRoktアカウント担当者から提供されたキーと秘密に置き換えることを確認してください。
ユーザーを識別する
SDKが初期化されるとき、現在のユーザーを識別して、収集されたデータが正しくそれらに帰属され、彼らの行動に基づいて最も関連性の高い広告が表示されるようにします。
SDKの初期化スクリプトには、identifyRequestというオブジェクトが含まれています:
- Kotlin
- Java
val identifyRequest = IdentityApiRequest.withEmptyUser()
.email("j.smith@example.com")
.build()
IdentityApiRequest identifyRequest = IdentityApiRequest.withEmptyUser()
.email("j.smith@example.com")
.build();
identifyRequest
内で、ユーザーのメールアドレスをemail
フィールドに渡します。
追加のユーザー属性を設定する
初期化スクリプトには、ユーザーがメールアドレスで正常に識別された場合に追加のユーザー属性を設定することができるコールバック関数が含まれています。
- Kotlin
- Java
val identifyTask = BaseIdentityTask()
.addSuccessListener { identityApiResult ->
val user = identityApiResult.user
user.setUserAttribute("example attribute key", "example attribute value")
}
BaseIdentityTask identifyTask = new BaseIdentityTask()
.addSuccessListener(new TaskSuccessListener() {
@Override
public void onSuccess(IdentityApiResult identityApiResult) {
MParticleUser user = identityApiResult.getUser();
user.setUserAttribute("example attribute key", "example attribute value");
}
});
フォントを使用した初期化
One Platformで希望のフォントを提供する代わりに、または追加で、アプリケーションに既にバンドルされているフォントを利用することを選択できます。これにより、初期化時にフォントをダウンロードする可能性を排除し、ネットワーク使用率を低減し、ダウンロードエラーの可能性を減少させる利点があります。アプリケーションの assets
ディレクトリにあるフォントリソースを使用するか、独自の Typeface
オブジェクトを渡すことを選択できます。
フォントアセットの使用
アプリケーションの assets
ディレクトリに保存されたフォントを利用することができます。このために、init
メソッドにフォントのポストスクリプト名をアセットディレクトリ内のファイルパスにマップするマップを渡すことができます(アセットディレクトリはルートディレクトリ)。ポストスクリプト名はレイアウトで使用されているものと一致する必要がありますので、わからない場合はアカウントマネージャーに確認してください。
- Java
- Kotlin
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)
...
}
}
import com.mparticle.MParticle;
import com.mparticle.MParticleOptions;
public class YourApplication extends Application {
@Override
public void onCreate() {
...
Map<String, String> fontFilePathMap = new HashMap<>();
fontFilePathMap.put("Arial-Bold", "fonts/arialbold.otf");
MParticleOptions options = MParticleOptions.builder(this)
.credentials(
"your-key", // Roktアカウント担当者によって提供されたキー
"your-secret" // あなたのRoktアカウント 担当者から提供されたシークレット
)
.environment(MParticle.Environment.Development) // 環境を指定するにはenvironment:
.roktOptions(new RoktOptions(fontFilePathMap))
.build();
MParticle.start(options);
...
}
}
3. ユーザーを識別する
SDKが初期化された後にユーザーがメールアドレスを提供するたびに(例えば、ログインや購入時)、identifyメソッドを呼び出して、そのメールをRoktに渡す必要があります。これにより、データが現在のユーザーに正しく関連付けられます。
3.1 identifyRequest
を作成する
ユーザーを識別するには、まずユーザーのメールアドレスを含むidentifyRequest
オブジェクトを作成します。
ハッシュ化されていないメールアドレスを提供する場合は、次を使用します:
- Kotlin
- Java
val identifyRequest = IdentityApiRequest.withEmptyUser()
.email("j.smith@example.com")
.build()
IdentityApiRequest identifyRequest = IdentityApiRequest.withEmptyUser()
.email("j.smith@example.com")
.build();
3.2 追加のユーザー属性を設定する
次に、ユーザーを識別するときにコールバック関数を作成して追加のユーザー属性を設定するオプションがあります。identifyRequest
が成功すると、setUserAttribute
を使用して設定したユーザー属性がユーザーに割り当てられます。
- Kotlin
- Java
val identifyTask = BaseIdentityTask()
.addSuccessListener { identityApiResult ->
val user = identityApiResult.user
user.setUserAttribute("example attribute key", "example attribute value")
}
BaseIdentityTask identifyTask = new BaseIdentityTask()
.addSuccessListener(new TaskSuccessListener() {
@Override
public void onSuccess(IdentityApiResult identityApiResult) {
MParticleUser user = identityApiResult.getUser();
user.setUserAttribute("example attribute key", "example attribute value");
}
});
3.3 identify
メソッドを呼び出す
最後に、identifyRequest
と identityCallback
を作成した後、追加の属性を設定するために、作成した identifyRequest
と identityCallback
オブジェクトを渡して、identify
メソッドを呼び出します:
- Kotlin
- Java
MParticle.getInstance()?.Identity()?.identify(identifyRequest)
MParticle.getInstance().Identity().identify(identifyRequest);
例えば、Jane Smith という名前のユーザーを j.smith@example.com というメールアドレスで識別するために(そしてメールアドレスをハッシュ化する必要がない場合)、次のようにします:
- Kotlin
- Kotlin
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)
IdentityApiRequest identifyRequest = IdentityApiRequest.withEmptyUser()
.email("j.smith@example.com")
.build();
BaseIdentityTask identifyTask = new BaseIdentityTask()
.addSuccessListener(new TaskSuccessListener() {
@Override
public void onSuccess(IdentityApiResult identityApiResult) {
MParticleUser user = identityApiResult.getUser();
user.setUserAttribute("example attribute key", "example attribute value");
}
});
MParticle.getInstance().Identity().identify(identifyRequest);
3. ユーザー属性の追跡
Rokt SDKを使用して、イベントとは別にユーザー属性を収集することができます。イベントを追跡する際のカスタム属性とは分離されています。SDKは、特定のセッションで収集されたユーザー属性を、同じセッション内でトリガーされたイベントと関連付けます。
ユーザー属性を収集するために、次のコードをRokt SDKの初期化直後、イベントを記録する前にアプリで実行する必要があります。
- Kotlin
- Java
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")
import com.mparticle.MParticle;
import com.mparticle.MParticleUser;
// 現在のユーザーを取得します。これは、SDKの初期化中またはidentifyメソッドの呼び出しによってユーザーを識別している場合にのみ成功します。
MParticleUser currentUser = MParticle.getInstance().Identity().getCurrentUser();
// `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");
// 値のリストを含むユーザー属性を作成できます
List<String> attributeList = new ArrayList<>();
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つである必要があります。
- Kotlin
- Java
import com.mparticle.MParticle
val screenInfo = HashMap<String, String>()
screenInfo["rating"] = "5"
screenInfo["property_type"] = "hotel"
MParticle.getInstance()?.logScreen("Details", screenInfo)
import com.mparticle.MParticle;
HashMap<String, String> screenInfo = new HashMap<>();
screenInfo.put("rating", "5");
screenInfo.put("property_type", "hotel");
if (MParticle.getInstance() != null) {
MParticle.getInstance().logScreen("Details", screenInfo);
}
5. プレースメントを表示する
Rokt SDK の主な価値は、selectPlacements
メソッドを通じてアンロックされます。これにより、提供する属性に基づ いて顧客に対して非常に関連性の高いプレースメント(またはレイアウト)が提供されます。
Rokt の統合が初期化されたら、レイアウトがレンダリングされるページから selectPlacements
メソッドを呼び出すことができます。これをできるだけ早く、必要なすべての属性が利用可能になった時点で呼び出すべきであり、ユーザーに最適なエクスペリエンスを確保します。
selectPlacements を呼び出す際には、少なくとも email
、firstname
、lastname
、billingzipcode
、および confirmationref
属性を提供しなければなりません。
オーバーレイプレースメント
- Kotlin
- Java
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, // オプションのコールバック(必要に応じて定義、以下参照)
)
Map<String, String> attributes = new HashMap<>();
attributes.put("email", "j.smith@example.com");
attributes.put("firstname", "Jenny");
attributes.put("lastname", "Smith");
attributes.put("billingzipcode", "90210");
attributes.put("confirmationref", "54321");
// フォント書体のマップ
Map<String, WeakReference<android.graphics.Typeface>> fontTypefaces = new HashMap<>();
fontTypefaces.put("Arial-Bold", new WeakReference<>(yourTypefaceObject)); // yourTypefaceObject は有効な Typeface インスタンスである必要があります
RoktConfig roktConfig = new RoktConfig.Builder()
.colorMode(RoktConfig.ColorMode.LIGHT)
.build();
// Rokt selectPlacements を呼び出します
if (MParticle.getInstance() != null && MParticle.getInstance().Rokt() != null) {
MParticle.getInstance().Rokt().selectPlacements(
"RoktExperience", // 識別子
attributes, // 属性
null, // オプションのコールバック (適宜定義してください。以下を参照)
null, // オプションのプレースホルダー (以下の埋め込みプレースメントを参照)
fontTypefaces, // フォント書体
roktConfig // roktConfig
);
}
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
に設定することをお勧めします。
- Kotlin
- Java
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
)
}
}
import com.mparticle.kits.RoktKit;
import com.mparticle.rokt.RoktConfig;
import com.mparticle.MpRoktEventCallback;
import com.mparticle.UnloadReasons;
public class ConfirmActivity extends Activity {
private MpRoktEventCallback callbacks = new MpRoktEventCallback() {
@Override
public void onLoad() {
// Rokt配置がロードされるときのオプションのコールバック
}
@Override
public void onUnload(UnloadReasons reason) {
// Rokt配置がアンロードされるときのオプションのコールバック
}
@Override
public void onShouldShowLoadingIndicator() {
// ローディングインジケータを表示するためのオプションのコールバック
``` }
@Override
public void onShouldHideLoadingIndicator() {
// ローディングインジケーターを隠すためのオプショナルなコールバック
}
};
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
MParticle instance = MParticle.getInstance();
setContentView(R.layout.activity_main);
Map<String, String> attributes = new HashMap<>();
attributes.put("email", "j.smith@example.com");
attributes.put("firstname", "Jenny");
attributes.put("lastname", "Smith");
attributes.put("mobile", "(323) 867-5309");
attributes.put("postcode", "90210");
attributes.put("country", "US");
RoktEmbeddedView roktWidget = findViewById(R.id.roktEmbeddedView);
Map<String, WeakReference<RoktEmbeddedView>> placeHolders = new HashMap<>();
placeHolders.put("RoktEmbedded1", new WeakReference<>(roktWidget));
Map<String, WeakReference<android.graphics.Typeface>> fontTypefaces = new HashMap<>();
fontTypefaces.put("Arial-Bold", new WeakReference<>(yourTypefaceObject));
RoktConfig roktConfig = new RoktConfig.Builder()
.colorMode(RoktConfig.ColorMode.LIGHT)
.build();
if (instance != null && instance.Rokt() != null) {
instance.Rokt().selectPlacements(
"RoktExperience",
attributes,
callbacks,
placeHolders,
fontTypefaces,
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")
}
}
}
イベント | 説明 | パラメータ |
---|---|---|
ShowLoadingIndicator | SDKがRoktのバックエンドを呼び出す前にトリガーされます | |
HideLoadingIndicator | SDKが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 オブジェクト
パラメータ | 説明 |
---|---|
cacheDuration | Rokt 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
- ソーシャルメディアのインタラクションとシェア活動をキャプチャ
- Kotlin
- Java
val customAttributes = mapOf(
"category" to "Destination Intro",
"title" to "パリ",
)
val event = MPEvent.Builder("Video Watched", EventType.Navigation)
.customAttributes(customAttributes)
.build()
MParticle.getInstance()?.logEvent(event)
Map<String, String> customAttributes = new HashMap<>();
customAttributes.put("category", "Destination Intro");
customAttributes.put("title", "パリ");
MPEvent event = new MPEvent.Builder("Video Watched", EventType.Navigation)
.customAttributes(customAttributes)
.build();
if (MParticle.getInstance() != null) {
MParticle.getInstance().logEvent(event);
}
コマースイベントをトラッキングする
コマースイベントをトラッキングするには、次の3つのステップが必要です:
- 購入される商品または商品の定義
- トランザクション 要約を含むオブジェクトの作成
- イベントをログに記録し、商品定義とトランザクション要約を含める
- Kotlin
- Java
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)
import com.mparticle.commerce.CommerceEvent;
import com.mparticle.commerce.Product;
import com.mparticle.commerce.TransactionAttributes;
// 1. 商品を作成する
// 商品のカスタム属性をキー/バリューのペアとしてオプションのマップを作成する
Map<String, String> productAttributes = new HashMap<>();
productAttributes.put("ocean-view", "true");
productAttributes.put("balcony", "false");
Product product = new Product.Builder("Double Room - Econ Rate", "econ-1", 100.00)
.quantity(4.0)
.customAttributes(productAttributes)
.build();
// 2. トランザクションを要約する
TransactionAttributes attributes = new TransactionAttributes("foo-transaction-id")
.setRevenue(430.00)
.setTax(30.00);
Map<String, String> customTransactionAttributes = new HashMap<>();
customTransactionAttributes.put("sale", "true");
customTransactionAttributes.put("phone-booking", "true");
CommerceEvent event = new CommerceEvent.Builder(Product.PURCHASE, product)
.transactionAttributes(attributes)
.customAttributes(customTransactionAttributes)
.build();
if (MParticle.getInstance() != null) {
MParticle.getInstance().logEvent(event);
}