Skip to main content

iOS UX Helper

Rokt UX Helper is an open source project that helps you render beautiful customer experiences in a server to server environment. You can find and contribute to the project on the Github page.

This document outlines the process for integrating RoktUXHelper into your iOS app, which works alongside the Server-to-Server integration(S2S) to deliver relevant experiences to your customers as they checkout. This guide assumes you are familiar with UIKit/SwiftUI and basic iOS development concepts.

SystemVersion
RoktUXHelper0.3.1
iOS15.0+
Package ManagerSwift Package Manager
Swift5+
Xcode15+

Installation Guide​

The library is available as a Swift Package Manager(SPM) dependency. To install it, add the following SPM dependency into your package.json file. This configuration ensures that your app will receive updates to the library up to, but not including, the next major release.

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

Import Required Modules​

To start using RoktLayoutView, you need to import the necessary modules into your view controller or class.

import SwiftUI
import RoktUXHelper

Initialize RoktLayoutView​

The RoktLayoutView class provides multiple initialization options, allowing for configuration flexibility. You can initialize it by passing required bindings and parameters like experienceResponse, location name, optional config, and event handlers. 

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 Events​

Use the onUXEvent handler to receive real-time feedback on user interactions.

At a minimum you must handle when a RoktUXEvent.OpenUrl event is triggered so you can open the link using the below example.

info

OpenUrl & onClose​

event.onClose?(event.id) is critical to be called after a URL has been opened and will notify the RoktUXHelper to execute some logic like moving to the next offer.

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
                })
            }
        }
    }
},
All events

UX Events​

EventDescriptionParams
OfferEngagementTriggered when the user engages with the offerlayoutId: String
PositiveEngagementTriggered when the user positively engages with the offerlayoutId: String
LayoutInteractiveTriggered when a layout has been rendered and is interactablelayoutId: String
LayoutReadyTriggered when a layout is ready to display but has not rendered content yetlayoutId: String
LayoutClosedTriggered when a layout is closed by the userlayoutId: String
LayoutCompletedTriggered when the offer progression reaches the end and no more offers are available to displaylayoutId: String
LayoutFailureTriggered when a layout could not be displayed due to some failurelayoutId: String (optional)
OpenUrlTriggered when a link needs to be openedurl: String, id: String, type: OpenURLType (internally/externally/passthrough), onClose: (String) -> Void, onError: (String: Error?) -> Void

Send platformEvents to Rokt​

Platform events are an essential part of integration and it has to be sent to Rokt via your backend. For ease of use, platformEvent is defined as [String: Any]

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

You can find a full list of events here.

Summary​

Integrating RoktLayoutView into your iOS app is straightforward and provides a flexible way to manage views and experiments. By following the steps outlined in this guide, you can add RoktLayoutView into your project and take full advantage of the powerful features offered by 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
        }
    )
}

Optional: App Configurations​

RoktUXConfig enables partner applications to provide custom configuration settings from their app environment. This allows RoktUXHelper to apply these configurations, offering more flexibility and control over the user experience, rather than relying exclusively on system defaults.

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

ColorMode object​

ValueDescription
lightApplication is in Light Mode
darkApplication is in Dark Mode
systemApplication defaults to System Color Mode

RoktUXImageLoader​

Rokt UX Helper accepts an optional RoktUXImageLoader to give partners flexibility over image downloads. In the sample RoktUXImageLoaderImpl, images are fetched asynchronously from a URL using URLSession and returned via a completion handler. If no ImageLoader is provided, RoktUXHelper defaults to using SwiftUI’s 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()
    }
}

Fonts​

Rokt UX Helper will be able to utilise custom fonts by simply registering them to your project and having them configured on your Rokt account in One Platform.

Was this article helpful?