Android SDK インテグレーションガイド

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

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

注記

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

1. 依存関係を追加する1. 依存関係を追加するへの直接リンク

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

build.gradle.kts
build.gradle

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

dependencies {
    implementation "com.mparticle:android-rokt-kit:5.73.0"
    implementation "com.mparticle:android-core:5.73.0"
}

2. アプリでSDKを初期化する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)  // 環境を指定:
            .roktOptions(new RoktOptions(fontFilePathMap))
            .build();
        
        MParticle.start(options);
        ...
    }
}

3. ユーザーを識別する3. ユーザーを識別するへの直接リンク

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

3.1 `identifyRequest`を作成する31-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 追加のユーザー属性を設定する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` メソッドの呼び出し33-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. ユーザー属性のトラッキング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. ファネルイベントのキャプチャ4. ファネルイベントのキャプチャへの直接リンク

Rokt SDKを使用すると、イベントトラッキングを実装して、アプリ内でのユーザーの行動を記述するデータを収集できます。このデータを使用して、ユーザーエクスペリエンスを最適化することができます。

SDKで記録できる主なイベントタイプは3つあります:

スクリーンビューイベント: アプリの画面が読み込まれたときにトリガーできるイベントです。
カスタムイベント: アプリ固有の情報を追跡するために作成する自由形式のイベントです。
コマースイベント: eコマースに特化したイベントで、カートへのアイテム追加や最終購入など、ショッピング体験のさまざまな段階を記述できます。

Rokt SDKとの初回統合時には、まずスクリーンビュートラッキングを実装してください。カスタムイベントとコマースイベントのトラッキングについては、付録を参照してください。

スクリーンビューのトラッキングスクリーンビューのトラッキングへの直接リンク

トラッキングできる最も基本的なイベントタイプの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. プレースメントを表示する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)

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

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を通じて許可されるさまざまな高度な機能の例も提供します。MpRoktEventCallbackクラスは、callbacksパラメータを通じてRoktに渡され、配置を生成および表示する際に発生するさまざまなイベントに応答することができます。

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グローバルイベント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 (オプション)
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オブジェクトColorModeオブジェクトへの直接リンク

値	説明
LIGHT	アプリケーションはライトモードです
DARK	アプリケーションはダークモードです
SYSTEM	アプリケーションはシステムのカラーモードにデフォルト設定されています

EdgeToEdgeDisplay ブール値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 オブジェクトCacheConfig オブジェクトへの直接リンク

パラメータ	説明
cacheDuration	Rokt SDK がエクスペリエンスをキャッシュする秒単位のオプションの期間です。最大許容値は90分で、デフォルト（値が提供されていないか無効な場合）は90分です。
cacheAttributes	キャッシュキーとして使用されるオプションの属性です。nullの場合、`selectPlacements`で送信されたすべての属性がキャッシュキーとして使用されます。

import com.mparticle.rokt.CacheConfig
import com.mparticle.rokt.RoktConfig

// エクスペリエンスを1200秒間キャッシュし、emailとorderNumber属性をキャッシュキーとして使用する場合。
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
)

Jetpack Compose における RoktLayout のサポートJetpack Compose における RoktLayout のサポートへの直接リンク

Jetpack Compose を使用して実装された画面向けに、SDK は RoktLayout コンポーネントを提供し、Android アプリケーション内で Rokt のプレースメントをモダンで宣言的に統合することを可能にします。

RoktLayout クラスは、Rokt のプレースメントを表示するための Compose 互換のインターフェースを提供し、開発者が selectPlacements を手動で呼び出す必要なく Compose API の構文を使用できるようにします。これは、Overlay、BottomSheet、Embedded のプレースメントタイプをサポートしています。

Jetpack Compose コンポーネントの追加

import com.mparticle.kits.RoktLayout
import com.mparticle.MpRoktEventCallback
import com.mparticle.UnloadReasons

@Composable
fun MainScreen(modifier: Modifier = Modifier) {
    Column(
        modifier = modifier
            .background(Color.LightGray)
            .padding(8.dp),
    ) {
        val attributes = mapOf(
            "email" to "j.smith@example.com",
            "firstname" to "Jenny",
            "lastname" to "Smith",
            "mobile" to "(323) 867-5309",
            "postcode" to "90210",
            "country" to "US"
        )
        val callbacks = object : MpRoktEventCallback {
            override fun onLoad() = println("View loaded")
            override fun onUnload(reason: UnloadReasons) = println("View unloaded due to: $reason")
            override fun onShouldShowLoadingIndicator() = println("Show loading indicator")
            override fun onShouldHideLoadingIndicator() = println("Hide loading indicator")
        }
        val roktConfig = RoktConfig.Builder()
            .colorMode(RoktConfig.ColorMode.DARK)
            .cacheConfig(CacheConfig(
                cacheDurationInSeconds = 1200,
                cacheAttributes = mapOf("email" to "j.smith@example.com")
            ))
            .build()

        RoktLayout(
            sdkTriggered = true,
            identifier = "RoktExperience",
            attributes = attributes,
            location = "Location1",
            modifier = Modifier
                .fillMaxWidth()
                .background(Color.Black),
            mpRoktEventCallback = callbacks,
            config = roktConfig
        )
    }
}

パラメータパラメータへの直接リンク

パラメータ	タイプ	説明
sdkTriggered	Boolean	プレースメントがトリガーされるタイミングを制御します。
identifier	String	Roktビュー/エクスペリエンスの識別子 (例: "RoktExperience")。
location	String?	埋め込みプレースメントのためのオプションのロケーション名 (例: "Location1")。
attributes	Map<String, String>	プレースメントに渡す属性のマップ (例: ユーザー詳細のターゲティング)。
modifier	Modifier	レイアウト、スタイリング、UIの動作をカスタマイズするためのCompose `Modifier`。
callbacks	MpRoktEventCallback	プレースメントイベント（ロード、アンロード、ロード状態）を処理するためのオプションのコールバック。

カスタムイベントをトラッキングするカスタムイベントをトラッキングするへの直接リンク

上記の手順に従ってプレースメントと画面ビューのトラッキングを実装した後、追加のイベントトラッキングを実装したい場合があります。

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

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

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

Kotlin
Java

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)

Map<String, String> customAttributes = new HashMap<>();
customAttributes.put("category", "Destination Intro");
customAttributes.put("title", "Paris");

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ビルダーメソッドに渡すこともできます。例:
    //    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<>();
```java
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);
}

1. 依存関係を追加する1. 依存関係を追加する への直接リンク

2. アプリでSDKを初期化する2. アプリでSDKを初期化する への直接リンク

ユーザーの識別ユーザーの識別 への直接リンク

追加のユーザー属性を設定する追加のユーザー属性を設定する への直接リンク

フォントの初期化フォントの初期化 への直接リンク

フォントアセットの使用フォントアセットの使用 への直接リンク

3. ユーザーを識別する3. ユーザーを識別する への直接リンク

3.1 identifyRequestを作成する31-identifyrequestを作成する への直接リンク

3.2 追加のユーザー属性を設定する3.2 追加のユーザー属性を設定する への直接リンク

3.3 identify メソッドの呼び出し33-identify-メソッドの呼び出し への直接リンク

3. ユーザー属性のトラッキング3. ユーザー属性のトラッキング への直接リンク

4. ファネルイベントのキャプチャ4. ファネルイベントのキャプチャ への直接リンク

スクリーンビューのトラッキングスクリーンビューのトラッキング への直接リンク

5. プレースメントを表示する5. プレースメントを表示する への直接リンク

オーバーレイプレースメントオーバーレイプレースメント への直接リンク

オプション機能オプション機能 への直接リンク

埋め込み配置埋め込み配置 への直接リンク

グローバルイベントAPIグローバルイベントAPI への直接リンク

イベントイベント への直接リンク

付録付録 への直接リンク

デバッグデバッグ への直接リンク

アプリケーション設定の使用アプリケーション設定の使用 への直接リンク

ColorModeオブジェクトColorModeオブジェクト への直接リンク

EdgeToEdgeDisplay ブール値EdgeToEdgeDisplay ブール値 への直接リンク

CacheConfig オブジェクトCacheConfig オブジェクト への直接リンク

Jetpack Compose における RoktLayout のサポートJetpack Compose における RoktLayout のサポート への直接リンク

パラメータパラメータ への直接リンク

カスタムイベントをトラッキングするカスタムイベントをトラッキングする への直接リンク

コマースイベントのトラッキングコマースイベントのトラッキング への直接リンク