Last updated 2025年3月6日

Android UX ヘルパー

Rokt UX ヘルパーは、サーバー間環境で美しい顧客体験をレンダリングするのに役立つオープンソースプロジェクトです。プロジェクトは Github ページ で確認および貢献できます。

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

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

Jetpack Compose

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Installation from './_installation.md';
import ColorMode from './_colorMode.md';
import ImageLoader from './_imageLoader.md';
import Events from './_events.md';

<Installation />

## RoktLayout の初期化
Compose ビューに RoktLayout を追加します

```kotlin
// サーバーから体験レスポンスを取得する
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(),
    )
}

<ColorMode />

<ImageLoader />

### フォント

```kotlin
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()

XML

インストールガイド

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

Kotlin

build.gradle.kts

implementation("com.rokt:roktux:0.1.0")

Groovy

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

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に送信
    },
)

Java

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

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

Kotlin

openUrlEvent.onClose.invoke(openUrlEvent.id)

Java

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

Kotlin

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 -> {
                // ユーザーがアプリを離れることを許可する外部ブラウザを開きます
                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(openUrlEvent.url))
                context.startActivity(intent)

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

Java

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: OpenURLType (内部/外部), onClose: (id: String) -> Unit, onError: (id: String, throwable: Throwable)

PlatformEvents

プラットフォームイベントは統合の重要な部分であり、バックエンド経由でRoktに送信される必要があります。統合を簡素化するために、このオブジェクトはRoktPlatformEventsWrapperタイプであり、@Serializableを実装し、toJsonString関数を提供します。

Kotlin

onPlatformEvent = { events ->
    // これらのプラットフォームイベントをイベント本文と共にRokt APIに送信します
}

Java

roktPlatformEvents -> {
    // これらのプラットフォームイベントをイベント本文と共にRokt APIに送信します
    return null;
}

イベントの完全なリストはこちらで見つけることができます。

オプション: アプリ設定

カラーモード

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

Kotlin

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

Java

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

RoktUxColorModeオブジェクト

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

ImageLoader

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

Kotlin

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

Java

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

フォント

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

Kotlin

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

Java

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();