Android UX Helper

Rokt UX Helperは、サーバー間環境で美しい顧客体験をレンダリングするのを助けるオープンソースプロジェクトです。このプロジェクトはGithubページで見つけることができ、貢献することもできます。

このドキュメントは、Rokt UX HelperをAndroidアプリに統合するプロセスを概説しており、サーバー間統合(S2S)と連携して、チェックアウト時に顧客に関連する体験を提供します。

システム	バージョン
UX Helper	0.4.0
Android バージョン/API レベル	5.0+ (API レベル 21)
パッケージマネージャー	Maven / Gradle
Compose BOM	2024.09.02

Jetpack Compose
XML

インストールガイド

モジュール（アプリレベル）の Gradle ファイル（通常は <project>/<app-module>/build.gradle.kts または <project>/<app-module>/build.gradle）に、Rokt UX Helper の依存関係を追加します。

Kotlin
Groovy

build.gradle.kts
implementation("com.rokt:roktux:0.1.0")

build.gradle
implementation 'com.rokt:roktux:0.1.0'

RoktLayout の初期化

RoktLayout を Compose ビューに追加

// サーバーからエクスペリエンスレスポンスを取得
val experienceResponse = viewModel.experienceResponse.collectAsState()

experienceResponse.value?.let { experienceResponse ->
    RoktLayout(
        experienceResponse = experienceResponse,
        location = "RoktEmbedded1",
        onUxEvent = { println("RoktEvent: UxEvent Received $it") },
        onPlatformEvent = { println("RoktEvent: onPlatformEvent received $it") },
        roktUxConfig = RoktUxConfig.builder()
            .imageHandlingStrategy(NetworkStrategy())
            .build(),
    )
}

UXイベント

onUXEventハンドラーを使用して、ユーザーのインタラクションに関するリアルタイムのフィードバックを受け取ります。

最低限、RoktUXEvent.OpenUrlイベントがトリガーされたときにリンクを開くために、以下の例を使用して処理する必要があります。

備考

OpenUrl - onClose

OpenUrlタイプのイベントを処理する際には、onCloseコールバックを呼び出すことが重要です。これにより、RoktUXHelperが次のオファーに進むなどのロジックを実行することを通知します。

Kotlin
Java

openUrlEvent.onClose.invoke(openUrlEvent.id)

openUrlEvent.getOnClose().invoke(openUrlEvent.getId());

Kotlin
Java

onUxEvent = { event ->
    println("RoktEvent: onUxEvent received $event")

    if (event is RoktUxEvent.OpenUrl) {
        val openUrlEvent = event as RoktUxEvent.OpenUrl
        when (openUrlEvent.type) {
            OpenLinks.Internally -> {
                // ユーザーをアプリ内に留めるためにAndroidXブラウザまたは類似の機能を開く
                val customTabsIntent = CustomTabsIntent.Builder().build()
                customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.url))

                openUrlEvent.onClose.invoke(openUrlEvent.id) // ユーザーが次のオファーの準備ができたときに呼び出す必要があります
            }
            OpenLinks.Externally, OpenLinks.Passthrough -> {
                // 外部ブラウザを開いてユーザーがアプリを離れることを許可する
                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.url))
                context.startActivity(intent)

                openUrlEvent.onClose.invoke(openUrlEvent.id) // ユーザーが次のオファーの準備ができたときに呼び出す必要があります
            }
        }
    }
}

roktUxEvent -> {
    // URLを開くイベントを処理
    // 異なるタイプのURLを開くサンプル
    if (roktUxEvent instanceof RoktUxEvent.OpenUrl openUrlEvent) {
        if (openUrlEvent.getType() == OpenLinks.Internally) {
            // ユーザーをアプリ内に留めるためにAndroidXブラウザまたは類似の機能を開く
            CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder().build();
            customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.getUrl()));

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId()); // ユーザーが次のオファーの準備ができたときに呼び出す必要があります
        } else {
            // 外部ブラウザを開いてユーザーがアプリを離れることを許可する
            final Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.getUrl()));
            context.startActivity(intent);

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId());  // ユーザーが次のオファーの準備ができたときに呼び出す必要があります
        }
    }
    return null;
}

すべてのイベント

UXイベント

イベント	説明	パラメータ
OfferEngagement	ユーザーがオファーに関与したときにトリガーされます	layoutId: String
PositiveEngagement	ユーザーがオファーに積極的に関与したときにトリガーされます	layoutId: String
LayoutInteractive	レイアウトがレンダリングされ、操作可能になったときにトリガーされます	layoutId: String
LayoutReady	レイアウトが表示準備ができているが、まだコンテンツがレンダリングされていないときにトリガーされます	layoutId: String
LayoutClosed	ユーザーによってレイアウトが閉じられたときにトリガーされます	layoutId: String
LayoutCompleted	オファーの進行が終了し、表示するオファーがもうないときにトリガーされます	layoutId: String
LayoutFailure	何らかの失敗によりレイアウトを表示できなかったときにトリガーされます	layoutId: String (オプション)
OpenUrl	リンクを開く必要があるときにトリガーされます	url: String, id: String, type: OpenLinks (internally/externally/Passthrough), onClose: (id: String) -> Unit, onError: (id: String, throwable: Throwable)

プラットフォームイベント

プラットフォームイベントは統合の重要な部分であり、バックエンドを通じてRoktに送信する必要があります。統合を容易にするために、オブジェクトはRoktPlatformEventsWrapper型であり、@Serializableを実装し、toJsonString関数を提供します。

Kotlin
Java

onPlatformEvent = { events ->
    // これらのプラットフォームイベントをRokt APIにイベントボディを含めて送信します
}

roktPlatformEvents -> {
    // これらのプラットフォームイベントをRokt APIにイベントボディを含めて送信します
    return null;
}

イベントの完全なリストはこちらで確認できます。

オプション: アプリ設定

カラーモード

カラーモードを使用すると、Roktレイアウトを表示する際に使用するテーマを固定できます。デフォルトでは、Roktは現在のシステムテーマに一致します。

Kotlin
Java

val config = RoktUxConfig.builder()
    .colorMode(ColorMode.DARK)
    .build()

final RoktUxConfig build = new RoktUxConfig.builder()
    .colorMode(ColorMode.DARK)
    .build();

RoktUxColorMode オブジェクト

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

ImageLoader

Rokt UX Helperでは、画像の読み込みにcoilが使用されています。UX Helperには、アプリで利用できるいくつかの組み込み画像ローダーがあります。最も簡単で推奨される実装方法はNetworkStrategyです。ただし、使用しているネットワークライブラリや好みに応じて、カスタム画像読み込み戦略を作成することもできます。

Kotlin
Java

val roktUxConfig = RoktUxConfig.builder()
    .imageHandlingStrategy(NetworkStrategy())
    .build()

final roktUxConfig = new RoktUxConfig.builder()
    .imageHandlingStrategy(new NetworkStrategy())
    .build();

フォント

val fontFamily = remember {
        val robotoLight = Font(resId = R.font.roboto_light, weight = FontWeight.W100)
        val robotoItalic = Font(resId = R.font.roboto_italic, weight = FontWeight.W400)
        FontFamily(robotoLight, robotoItalic)
    }

RoktUxConfig.builder()
    .composeFontMap(mapOf("roboto" to fontFamily))
    .build()

インストールガイド

Kotlin
Groovy

build.gradle.kts
implementation("com.rokt:roktux:0.1.0")

build.gradle
implementation 'com.rokt:roktux:0.1.0'

RoktLayoutの初期化

Rokt UX Helperを使用するには、アプリの関連するXMLにレイアウトを追加する必要があります。この例では、RoktEmbedded1を使用して、このビューに読み込まれるレイアウトを示しています。これはページの設定と一致している必要があります。

<com.rokt.roktux.RoktLayoutView
    android:id="@+id/roktLayoutView"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:location="RoktEmbedded1" />

Kotlin
Java

val roktLayoutView: RoktLayoutView = findViewById(R.id.roktLayoutView)
val experienceResponse: String = // サーバーからエクスペリエンスレスポンスを取得
val roktUxConfig = RoktUxConfig.builder()
            .build()

roktLayoutView.loadLayout(
    experienceResponse = experienceResponse,
    roktUxConfig,
    onUxEvent = { event ->
        // UXイベントをここで処理
    },
    onPlatformEvent = { platformEvent ->
        // これらのプラットフォームイベントをRokt APIに送信
    },
)

final RoktLayoutView roktLayoutView = findViewById(R.id.roktLayoutView);
final String experienceResponse = "";
final RoktUxConfig roktUxConfig = RoktUxConfig.builder()
            .build()

roktLayoutView.loadLayout(
    experienceResponse,
    roktUxConfig,
    roktUxEvent -> {
        // UXイベントをここで処理
        return null;
    },
    roktPlatformEvent -> {
        // これらのプラットフォームイベントをRokt APIに送信
        return null;
    }
);

UXイベント

onUXEventハンドラーを使用して、ユーザーのインタラクションに関するリアルタイムのフィードバックを受け取ります。

最低限、RoktUXEvent.OpenUrlイベントがトリガーされたときにリンクを開くために、以下の例を使用して処理する必要があります。

備考

OpenUrl - onClose

Kotlin
Java

openUrlEvent.onClose.invoke(openUrlEvent.id)

openUrlEvent.getOnClose().invoke(openUrlEvent.getId());

Kotlin
Java

onUxEvent = { event ->
    println("RoktEvent: onUxEvent received $event")

    if (event is RoktUxEvent.OpenUrl) {
        val openUrlEvent = event as RoktUxEvent.OpenUrl
        when (openUrlEvent.type) {
            OpenLinks.Internally -> {
                // ユーザーをアプリ内に留めるためにAndroidXブラウザまたは類似の機能を開く
                val customTabsIntent = CustomTabsIntent.Builder().build()
                customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.url))

                openUrlEvent.onClose.invoke(openUrlEvent.id) // ユーザーが次のオファーの準備ができたときに呼び出す必要があります
            }
            OpenLinks.Externally, OpenLinks.Passthrough -> {
                // 外部ブラウザを開いてユーザーがアプリを離れることを許可する
                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.url))
                context.startActivity(intent)

                openUrlEvent.onClose.invoke(openUrlEvent.id) // ユーザーが次のオファーの準備ができたときに呼び出す必要があります
            }
        }
    }
}

roktUxEvent -> {
    // URLを開くイベントを処理
    // 異なるタイプのURLを開くサンプル
    if (roktUxEvent instanceof RoktUxEvent.OpenUrl openUrlEvent) {
        if (openUrlEvent.getType() == OpenLinks.Internally) {
            // ユーザーをアプリ内に留めるためにAndroidXブラウザまたは類似の機能を開く
            CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder().build();
            customTabsIntent.launchUrl(context, Uri.parse(openUrlEvent.getUrl()));

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId()); // ユーザーが次のオファーの準備ができたときに呼び出す必要があります
        } else {
            // 外部ブラウザを開いてユーザーがアプリを離れることを許可する
            final Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.getUrl()));
            context.startActivity(intent);

            openUrlEvent.getOnClose().invoke(openUrlEvent.getId());  // ユーザーが次のオファーの準備ができたときに呼び出す必要があります
        }
    }
    return null;
}

すべてのイベント

UXイベント

イベント	説明	パラメータ
OfferEngagement	ユーザーがオファーに関与したときにトリガーされます	layoutId: String
PositiveEngagement	ユーザーがオファーに積極的に関与したときにトリガーされます	layoutId: String
LayoutInteractive	レイアウトがレンダリングされ、操作可能になったときにトリガーされます	layoutId: String
LayoutReady	レイアウトが表示準備ができているが、まだコンテンツがレンダリングされていないときにトリガーされます	layoutId: String
LayoutClosed	ユーザーによってレイアウトが閉じられたときにトリガーされます	layoutId: String
LayoutCompleted	オファーの進行が終了し、表示するオファーがもうないときにトリガーされます	layoutId: String
LayoutFailure	何らかの失敗によりレイアウトを表示できなかったときにトリガーされます	layoutId: String (オプション)
OpenUrl	リンクを開く必要があるときにトリガーされます	url: String, id: String, type: OpenLinks (internally/externally/Passthrough), onClose: (id: String) -> Unit, onError: (id: String, throwable: Throwable)

プラットフォームイベント

Kotlin
Java

onPlatformEvent = { events ->
    // これらのプラットフォームイベントをRokt APIにイベントボディを含めて送信します
}

roktPlatformEvents -> {
    // これらのプラットフォームイベントをRokt APIにイベントボディを含めて送信します
    return null;
}

イベントの完全なリストはこちらで確認できます。

オプション: アプリ設定

カラーモード

Kotlin
Java

val config = RoktUxConfig.builder()
    .colorMode(ColorMode.DARK)
    .build()

final RoktUxConfig build = new RoktUxConfig.builder()
    .colorMode(ColorMode.DARK)
    .build();

RoktUxColorMode オブジェクト

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

ImageLoader

Kotlin
Java

val roktUxConfig = RoktUxConfig.builder()
    .imageHandlingStrategy(NetworkStrategy())
    .build()

final roktUxConfig = new RoktUxConfig.builder()
    .imageHandlingStrategy(new NetworkStrategy())
    .build();

フォント

まず、フォントファイル、例: roboto_light.ttf をAndroidのリソースフォルダに追加し、RoktUxConfigを使用してUX Helperを設定します。以下の例はリソースに設定されたフォントのためのものですが、AssetFontItemを使用してアセット内のフォントもサポートしています。

Kotlin
Java

val robotoFonts: List<ResourceFontItem> = listOf(
    ResourceFontItem(R.font.roboto_light, FontItemWeight.W100, FontItemStyle.Normal),
    ResourceFontItem(R.font.roboto_light, FontItemWeight.W300, FontItemStyle.Normal),
    ResourceFontItem(R.font.roboto_italic, FontItemWeight.W400, FontItemStyle.Italic),
    ResourceFontItem(R.font.roboto_bold, FontItemWeight.W700, FontItemStyle.Normal),
    ResourceFontItem(R.font.roboto_black, FontItemWeight.W900, FontItemStyle.Normal),
    // 必要なフォントを追加
)

// 複数のフォントがある場合はここで作成し、fontFamilyMapに追加

val config = RoktUxConfig.builder()
    .xmlFontFamilyMap(mapOf("roboto" to robotoFonts))
    .build()

final List<ResourceFontItem> fontItems = Arrays.asList(
    new ResourceFontItem(R.font.roboto_light, FontItemWeight.W100, FontItemStyle.Normal),
    new ResourceFontItem(R.font.roboto_light, FontItemWeight.W300, FontItemStyle.Normal),
    new ResourceFontItem(R.font.roboto_italic, FontItemWeight.W400, FontItemStyle.Italic),
    new ResourceFontItem(R.font.roboto_bold, FontItemWeight.W700, FontItemStyle.Normal),
    new ResourceFontItem(R.font.roboto_black, FontItemWeight.W900, FontItemStyle.Normal)
    // 必要なフォントを追加
);

// 複数のフォントがある場合はここで作成し、fontFamilyMapに追加

final Map<String, List<ResourceFontItem>> fontFamilyMap = new HashMap<>();
fontFamilyMap.put("roboto", fontItems);

final RoktUxConfig config = new RoktUxConfig.builder()
    .xmlFontFamilyMap(fontFamilyMap)
    .build();

インストールガイド​

RoktLayout の初期化​

UXイベント​

OpenUrl - onClose​

UXイベント​

プラットフォームイベント​

オプション: アプリ設定​

カラーモード​

RoktUxColorMode オブジェクト​

ImageLoader​

フォント​

インストールガイド​

RoktLayoutの初期化​

UXイベント​

OpenUrl - onClose​

UXイベント​

プラットフォームイベント​

オプション: アプリ設定​

カラーモード​

RoktUxColorMode オブジェクト​

ImageLoader​

フォント​

インストールガイド

RoktLayout の初期化

UXイベント

OpenUrl - onClose

UXイベント

プラットフォームイベント

オプション: アプリ設定

カラーモード

RoktUxColorMode オブジェクト

ImageLoader

フォント

インストールガイド

RoktLayoutの初期化

UXイベント

OpenUrl - onClose

UXイベント

プラットフォームイベント

オプション: アプリ設定

カラーモード

RoktUxColorMode オブジェクト

ImageLoader

フォント