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

iOS UX ヘルパー

Rokt UX ヘルパーは、サーバー間環境で美しい顧客体験をレンダリングするのを助けるオープンソースプロジェクトです。プロジェクトの詳細や貢献については、Githubページをご覧ください。

このドキュメントは、RoktUXHelperをiOSアプリに統合するプロセスを説明しており、サーバー間統合(S2S)と連携して、チェックアウト時にお客様に関連する体験を提供します。このガイドは、UIKit/SwiftUIおよび基本的なiOS開発の概念に精通していることを前提としています。

システムバージョン
RoktUXHelper0.3.1
iOS15.0+
パッケージマネージャーSwift Package Manager
Swift5+
Xcode15+

インストールガイドインストールガイド への直接リンク

このライブラリは、Swift Package Manager(SPM)の依存関係として利用可能です。インストールするには、以下のSPM依存関係をpackage.jsonファイルに追加します。この設定により、次のメジャーリリースまでのライブラリの更新をアプリが受け取ることが保証されます。

dependencies: [
    .package(url: "https://github.com/ROKT/rokt-ux-helper-ios.git", .upToNextMajor(from: "0.1.0"))
]

必要なモジュールのインポート必要なモジュールのインポート への直接リンク

RoktLayoutViewを使用開始するには、必要なモジュールをビューコントローラーまたはクラスにインポートする必要があります。

import SwiftUI
import RoktUXHelper

RoktLayoutViewの初期化RoktLayoutViewの初期化 への直接リンク

RoktLayoutViewクラスは複数の初期化オプションを提供しており、設定の柔軟性を可能にします。experienceResponse、location名、optional config、およびイベントハンドラのような必要なバインディングとパラメータを渡すことで初期化できます。

var body: some View {
    RoktLayoutView(experienceResponse: "{experience_response_json}",
                   location: "RoktEmbedded1",
                   config: roktConfig,
                   onUXEvent: { uxEvent in
                       // UXイベントをここで処理
                   },
                   onPlatformEvent: { platformEvent in
                       // これらのプラットフォームイベントをRokt APIに送信
                   })
}

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

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

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

備考

OpenUrl & onCloseOpenUrl & onClose への直接リンク

event.onClose?(event.id)は、URLが開かれた後に呼び出すことが重要で、次のオファーに進むなどのロジックを実行するためにRoktUXHelperに通知します。

onUXEvent: { uxEvent in // ここでUXイベントを処理します
    // URLを開くイベントを処理
    // 異なるタイプのURLを開く方法のサンプル
    if let event = uxEvent as? RoktUXEvent.OpenUrl,
        let url = URL(string: event.url) {
        switch event.type {
        case .externally:
            UIApplication.shared.open(url) { _ in
               event.onClose?(event.id) // ユーザーが次のオファーの準備ができたときにこれを呼び出す必要があります
            }
        default:
            let safariVC = SFSafariViewController(url: url)
            safariVC.modalPresentationStyle = .overFullScreen
            if let rootVC = UIApplication.shared.connectedScenes
                .compactMap({ ($0 as? UIWindowScene)?.keyWindow }).last?.rootViewController {
                rootVC.present(safariVC, animated: true, completion: {
                    event.onClose?(event.id) // ユーザーが次のオファーの準備ができたときにこれを呼び出す必要があります
                })
            }
        }
    }
},
すべてのイベント

UXイベント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 (internally/externally/passthrough), onClose: (String) -> Void, onError: (String: Error?) -> Void

RoktにplatformEventsを送信するRoktにplatformEventsを送信する への直接リンク

Platform eventsは統合の重要な部分であり、バックエンドを通じてRoktに送信する必要があります。使いやすさのために、platformEventは[String: Any]として定義されています。

onPlatformEvent: { platformEvent in
    // これらのplatform eventsをRokt APIに送信します
},
ペイロードの例
{
   "events":[
      {
         "instanceGuid":"6A764CDC-CCC5-4976-8121-5179E45757FB",
         "eventTime":"2024-10-28T03:56:18.502Z",
         "pageInstanceGuid":"",
         "eventType":"SignalInitialize",
         "sessionId":"DE110000-1000-1000-1000-100000000000",
         "attributes":[
            
         ],
         "metadata":[
            {
               "name":"clientTimeStamp",
               "value":"2024-10-28T03:56:18.502Z"
            },
            {
               "name":"captureMethod",
               "value":"ClientProvided"
            }
         ],
         "token":"...",
         "parentGuid":"b2170040-e74f-49db-819e-317ebd7f92ac"
      }
   ],
   "integration":{
      "deviceLocale":"en_AU",
      "version":"1.0",
      "packageName":"com.rokt.roktuxhelperdemo.RoktUX-Demo",
      "operatingSystemVersion":"17.5",
      "deviceType":"Phone",
      "platform":"iOS",
      "operatingSystem":"iOS",
      "deviceModel":"iPhone 16",
      "packageVersion":"1.0",
      "layoutSchemaVersion":"2.1.0",
      "name":"UX Helper iOS",
      "framework":"Swift"
   }
}

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

概要概要 への直接リンク

RoktLayoutViewをiOSアプリに統合することは簡単で、ビューや実験を管理する柔軟な方法を提供します。このガイドに記載された手順に従うことで、プロジェクトにRoktLayoutViewを追加し、RoktUXHelperが提供する強力な機能を最大限に活用できます。


var body: some View {
    RoktLayoutView(
        experienceResponse: "{experience_response_json}",
        location: "RoktEmbedded1",
        config: roktConfig,
        onUXEvent: { uxEvent in
            // UXイベントをここで処理
            if let event = uxEvent as? RoktUXEvent.OpenUrl,
                let url = URL(string: event.url) {
                switch event.type {
                case .externally:
                    UIApplication.shared.open(url) { _ in
                        event.onClose?(event.id)
                    }
                default:
                    let safariVC = SFSafariViewController(url: url)
                    safariVC.modalPresentationStyle = .overFullScreen
                    if let rootVC = UIApplication.shared.connectedScenes
                        .compactMap({ ($0 as? UIWindowScene)?.keyWindow }).last?.rootViewController {
                        rootVC.present(safariVC, animated: true, completion: {
                            event.onClose?(event.id)
                        })
                    }
                }
            }
        },
        onPlatformEvent: { platformEvent in
            // これらのプラットフォームイベントをRokt APIに送信
        }
    )
}

オプション: アプリ設定オプション: アプリ設定 への直接リンク

RoktUXConfigは、パートナーアプリケーションがアプリ環境からカスタム設定を提供できるようにします。これにより、RoktUXHelperはこれらの設定を適用し、システムデフォルトに依存するだけでなく、ユーザーエクスペリエンスに対する柔軟性と制御を提供します。

// アプリケーションがライトモードのみをサポートする場合。
let roktConfig = RoktUXConfig.builder()
                             .colorMode(.light)
                             .imageLoader(imageLoader)
                             .build()

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

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

RoktUXImageLoaderRoktUXImageLoader への直接リンク

Rokt UX Helperは、画像ダウンロードに対する柔軟性をパートナーに提供するために、オプションのRoktUXImageLoaderを受け入れます。サンプルのRoktUXImageLoaderImplでは、画像がURLSessionを使用してURLから非同期に取得され、完了ハンドラーを介して返されます。ImageLoaderが提供されない場合、RoktUXHelperはSwiftUIのAsyncImageをデフォルトで使用します。

import UIKit
import RoktUXHelper
class RoktUXImageLoaderImpl : RoktUXImageLoader {
    
    func loadImage(urlString: String, completion: @escaping (Result<UIImage?, any Error>) -> Void) {
        guard let url = URL(string: urlString) else { return }
        
        let task = URLSession.shared.dataTask(with: url) { data, response, error in
            guard let data = data else { return }
            DispatchQueue.main.async {
                completion(.success(UIImage(data: data)))
            }
        }
        
        task.resume()
    }
}

フォントフォント への直接リンク

Rokt UX Helper は、プロジェクトにカスタムフォントを登録し、One Platform 上の Rokt アカウントで設定することで、カスタムフォントを利用できるようになります。

この記事は役に立ちましたか？
Last updated Oct 29, 2025