iOS UX ヘルパー

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

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

システム	バージョン
RoktUXHelper	0.3.1
iOS	15.0+
パッケージマネージャー	Swift Package Manager
Swift	5+
Xcode	15+

SwiftUI

インストールガイド

このライブラリは、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 クラスは、構成の柔軟性を可能にする複数の初期化オプションを提供します。experienceResponse、location 名、optional config、およびイベントハンドラーのような必要なバインディングとパラメータを渡すことで初期化できます。

var body: some View {
    RoktLayoutView(experienceResponse: "{experience_response_json}",
                   location: "RoktEmbedded1",
                   config: roktConfig,
                   onUXEvent: { uxEvent in
                       // Handle UX events here
                   },
                   onPlatformEvent: { platformEvent in
                       // Send these platform events to Rokt API
                   })
}

UXイベント

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

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

備考

OpenUrl & onClose

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

onUXEvent: { uxEvent in // Handle UX events here
    // Handle open URL event
    // Here is a sample how to open different types of URLs
    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) // This must be called when the user is ready for the next offer
            }
        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) // This must be called when the user is ready for the next offer
                })
            }
        }
    }
},

すべてのイベント

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に送信する必要があります。使いやすさのために、platformEventは[String: Any]として定義されています

onPlatformEvent: { platformEvent in
    // Send these platform events to 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
            // Handle UX events here
            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
            // Send these platform events to Rokt API
        }
    )
}

オプション: アプリ設定

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

// if application supports only Light Mode.
let roktConfig = RoktUXConfig.builder()
                             .colorMode(.light)
                             .imageLoader(imageLoader)
                             .build()

ColorModeオブジェクト

値	説明
light	アプリケーションがライトモードである
dark	アプリケーションがダークモードである
system	アプリケーションがシステムのカラーモードにデフォルト設定されている

RoktUXImageLoader

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アカウントで設定するだけで、カスタムフォントを利用できるようになります。

UIKit

インストールガイド

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

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

必要なモジュールのインポート

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

import UIKit
import RoktUXHelper

RoktLayoutUIViewの初期化

RoktLayoutUIView クラスは、複数の初期化オプションを提供し、設定の柔軟性を可能にします。experienceResponse、location 名、RoktUXConfig などのオプションの設定パラメータ、およびイベントハンドラーを使用して初期化できます。

func loadRokt() {
    let experienceResponse = "{experience_response_json}"
    
    let roktView = RoktLayoutUIView(
        experienceResponse: experienceResponse,
        location: "RoktEmbedded1",
        config: roktConfig,
        onUXEvent: { uxEvent in 
            // Handle UX events here
        },
        onPlatformEvent: { platformEvent in
            // Send these platform events to Rokt API
        },
        onEmbeddedSizeChange: { newSize in
            // Handle view size changes if required
        }
    )
}

レイアウトへのビューの追加

初期化後、RoktLayoutUIView をビュー階層に追加する必要があります。ビューコントローラーでプログラム的に制約を設定するか、手動で配置することでこれを行うことができます。

// Add the RoktLayoutUIView to the view hierarchy
self.view.addSubview(roktView)

// Set constraints to position the RoktLayoutUIView
roktView.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
    roktView.topAnchor.constraint(equalTo: self.view.topAnchor),
    roktView.leadingAnchor.constraint(equalTo: self.view.leadingAnchor),
    roktView.trailingAnchor.constraint(equalTo: self.view.trailingAnchor),
    // Adjust the rest as needed
])

UXイベント

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

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

備考

OpenUrl & onClose

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

onUXEvent: { uxEvent in // Handle UX events here
    // Handle open URL event
    // Here is a sample how to open different types of URLs
    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) // This must be called when the user is ready for the next offer
            }
        default:
            let safariVC = SFSafariViewController(url: url)
            safariVC.modalPresentationStyle = .overFullScreen
            self.present(safariVC, animated: true, completion: {
               event.onClose?(event.id) // This must be called when the user is ready for the next offer
            })
        }
    }
},

すべてのイベント

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に送信する必要があります。使いやすさのために、platformEventは[String: Any]として定義されています

onPlatformEvent: { platformEvent in
    // Send these platform events to 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"
   }
}

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

まとめ

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

import UIKit
import RoktUXHelper
import SafariServices

class ViewController: UIViewController {
    
    // RoktUXImageLoader Implementation to download images
    let imageLoader: RoktUXImageLoader = RoktUXImageLoaderImpl()
    lazy var roktConfig = RoktUXConfig.builder().imageLoader(imageLoader).build()

    override func viewDidLoad() {
        super.viewDidLoad()
        loadRokt()
    }
    
    
    func loadRokt() {
        let experienceResponse = "{experience_response_json}"
        
        let roktView = RoktLayoutUIView(
            experienceResponse: experienceResponse,
            location: "RoktEmbedded1",
            config: roktConfig,
            onUXEvent: { uxEvent in // Handle UX events here
                // Handle open URL event
                // Here is a sample how to open different types of URLs
                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
                        self.present(safariVC, animated: true, completion: {
                            event.onClose?(event.id)
                        })
                    }
                }
            },
            onPlatformEvent: { platformEvent in
                // Send these platform events to Rokt API
            },
            onEmbeddedSizeChange: { newSize in
                // Handle view size changes if required
            }
        )
        self.view.addSubview(roktView)
        
        // Add the RoktLayoutUIView to the view hierarchy
        roktView.translatesAutoresizingMaskIntoConstraints = false
        // Set constraints to position the RoktLayoutUIView
        NSLayoutConstraint.activate([
            roktView.topAnchor.constraint(equalTo: self.view.topAnchor),
            roktView.leadingAnchor.constraint(equalTo: self.view.leadingAnchor),
            roktView.trailingAnchor.constraint(equalTo: self.view.trailingAnchor),
            // Adjust the rest as needed
        ])
    }
    
    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()
        }
    }
}

オプション: アプリ設定

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

// if application supports only Light Mode.
let roktConfig = RoktUXConfig.builder()
                             .colorMode(.light)
                             .imageLoader(imageLoader)
                             .build()

ColorModeオブジェクト

値	説明
light	アプリケーションがライトモードである
dark	アプリケーションがダークモードである
system	アプリケーションがシステムのカラーモードにデフォルト設定されている

RoktUXImageLoader

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アカウントで設定するだけで、カスタムフォントを利用できるようになります。