Last updated

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

import Installation from './_installation.md';
import Configurations from './_configurations.md';
import Events from './_events.md';

<Installation />

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

```swift
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
                       // UXイベントをここで処理します
                   },
                   onPlatformEvent: { platformEvent in
                       // これらのプラットフォームイベントをRokt APIに送信します
                   })
}

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

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

:::info

### OpenUrl と onClose
`event.onClose?(event.id)` は URL が開かれた後に呼び出されることが重要であり、RoktUXHelper に次のオファーに移動するためのいくつかのロジックを実行させる通知を行います。

:::

```swift
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) // ユーザーが次のオファーの準備ができたときに呼び出す必要があります
                })
            }
        }
    }
},

概要

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に送信します
        }
    )
}

UIKit

import Installation from './_installation.md'; import Configurations from './_configurations.md'; import Events from './_events.md';

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

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 
            // UXイベントをここで処理
        },
        onPlatformEvent: { platformEvent in
            // このプラットフォームイベントをRokt APIへ送信
        },
        onEmbeddedSizeChange: { newSize in
            // 必要に応じてビューサイズの変更を処理
        }
    )
}

レイアウトにビューを追加する

初期化が完了したら、RoktLayoutUIView をビュー階層に追加する必要があります。ビューコントローラーで制約を設定したり、手動で位置を決めたりしてプログラム的に行うことができます。

// RoktLayoutUIView をビュー階層に追加
self.view.addSubview(roktView)

// 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),
    // 必要に応じて調整
])

UX イベント

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

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

備考

OpenUrl & 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
            self.present(safariVC, animated: true, completion: {
               event.onClose?(event.id) // ユーザーが次のオファーの準備ができたときにこれを呼び出す必要があります
            })
        }
    }
},

概要

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

import UIKit
import RoktUXHelper
import SafariServices

class ViewController: UIViewController {
    
    // RoktUXImageLoader実装を使用して画像をダウンロード
    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 // ここで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
                        self.present(safariVC, animated: true, completion: {
                            event.onClose?(event.id)
                        })
                    }
                }
            },
            onPlatformEvent: { platformEvent in
                // これらのプラットフォームイベントをRokt APIに送信
            },
            onEmbeddedSizeChange: { newSize in
                // 必要に応じてビューサイズの変更を処理
            }
        )
        self.view.addSubview(roktView)
        
        // RoktLayoutUIViewをビュー階層に追加
        roktView.translatesAutoresizingMaskIntoConstraints = false
        // RoktLayoutUIViewの位置を設定するための制約を設定
```swift
NSLayoutConstraint.activate([
            roktView.topAnchor.constraint(equalTo: self.view.topAnchor),
            roktView.leadingAnchor.constraint(equalTo: self.view.leadingAnchor),
            roktView.trailingAnchor.constraint(equalTo: self.view.trailingAnchor),
            // 必要に応じて他を調整します
        ])
    }
    
    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()
        }
    }
}