Aller au contenu principal

iOS UX Helper

Rokt UX Helper est un projet open source qui vous aide à rendre de belles expériences client dans un environnement serveur à serveur. Vous pouvez trouver et contribuer au projet sur la page Github.

Ce document décrit le processus d'intégration de RoktUXHelper dans votre application iOS, qui fonctionne avec l'intégration Server-to-Server (S2S) pour offrir des expériences pertinentes à vos clients lors de leur passage en caisse. Ce guide suppose que vous êtes familier avec UIKit/SwiftUI et les concepts de base du développement iOS.

SystèmeVersion
RoktUXHelper0.3.1
iOS15.0+
Gestionnaire de paquetsSwift Package Manager
Swift5+
Xcode15+

Guide d'installationLien direct vers Guide d'installation

La bibliothèque est disponible en tant que dépendance pour le gestionnaire de paquets Swift (SPM). Pour l'installer, ajoutez la dépendance SPM suivante dans votre fichier package.json. Cette configuration garantit que votre application recevra les mises à jour de la bibliothèque jusqu'à, mais sans inclure, la prochaine version majeure.

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

Importer les modules requisLien direct vers Importer les modules requis

Pour commencer à utiliser RoktLayoutView, vous devez importer les modules nécessaires dans votre contrôleur de vue ou classe.

import SwiftUI
import RoktUXHelper

Initialiser RoktLayoutViewLien direct vers Initialiser RoktLayoutView

La classe RoktLayoutView offre plusieurs options d'initialisation, permettant une flexibilité de configuration. Vous pouvez l'initialiser en passant les liaisons et paramètres requis comme experienceResponse, nom location, optional config, et des gestionnaires d'événements.

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

Événements UXLien direct vers Événements UX

Utilisez le gestionnaire onUXEvent pour recevoir des retours en temps réel sur les interactions utilisateur.

Au minimum, vous devez gérer quand un événement RoktUXEvent.OpenUrl est déclenché afin de pouvoir ouvrir le lien en utilisant l'exemple ci-dessous.

info

OpenUrl & onCloseLien direct vers OpenUrl & onClose

Il est crucial d'appeler event.onClose?(event.id) après qu'une URL a été ouverte, cela notifiera le RoktUXHelper pour exécuter une logique comme passer à l'offre suivante.

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
                })
            }
        }
    }
},
Tous les événements

Événements UXLien direct vers Événements UX

ÉvénementDescriptionParamètres
OfferEngagementDéclenché lorsque l'utilisateur interagit avec l'offrelayoutId: String
PositiveEngagementDéclenché lorsque l'utilisateur interagit positivement avec l'offrelayoutId: String
LayoutInteractiveDéclenché lorsqu'une mise en page a été rendue et est interactivelayoutId: String
LayoutReadyDéclenché lorsqu'une mise en page est prête à être affichée mais n'a pas encore rendu de contenulayoutId: String
LayoutClosedDéclenché lorsqu'une mise en page est fermée par l'utilisateurlayoutId: String
LayoutCompletedDéclenché lorsque la progression de l'offre atteint la fin et qu'aucune autre offre n'est disponible à afficherlayoutId: String
LayoutFailureDéclenché lorsqu'une mise en page n'a pas pu être affichée en raison d'une erreurlayoutId: String (optionnel)
OpenUrlDéclenché lorsqu'un lien doit être ouverturl: String, id: String, type: OpenURLType (interne/externe/passthrough), onClose: (String) -> Void, onError: (String: Error?) -> Void

Envoyer des platformEvents à RoktLien direct vers Envoyer des platformEvents à Rokt

Les événements de plateforme (platform events) sont une partie essentielle de l'intégration et doivent être envoyés à Rokt via votre backend. Pour faciliter l'utilisation, platformEvent est défini comme [String: Any]

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

Vous pouvez trouver une liste complète des événements ici.

RésuméLien direct vers Résumé

L'intégration de RoktLayoutView dans votre application iOS est simple et offre un moyen flexible de gérer les vues et les expériences. En suivant les étapes décrites dans ce guide, vous pouvez ajouter RoktLayoutView dans votre projet et profiter pleinement des fonctionnalités puissantes offertes par 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
        }
    )
}

Optionnel : Configurations de l'applicationLien direct vers Optionnel : Configurations de l'application

RoktUXConfig permet aux applications partenaires de fournir des paramètres de configuration personnalisés depuis leur environnement d'application. Cela permet à RoktUXHelper d'appliquer ces configurations, offrant plus de flexibilité et de contrôle sur l'expérience utilisateur, plutôt que de se fier exclusivement aux paramètres par défaut du système.

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

Objet ColorModeLien direct vers Objet ColorMode

ValeurDescription
lightL'application est en mode clair
darkL'application est en mode sombre
systemL'application utilise le mode couleur du système par défaut

RoktUXImageLoaderLien direct vers RoktUXImageLoader

Rokt UX Helper accepte un RoktUXImageLoader optionnel pour donner aux partenaires plus de flexibilité concernant le téléchargement d'images. Dans l'exemple RoktUXImageLoaderImpl, les images sont récupérées de manière asynchrone à partir d'une URL en utilisant URLSession et retournées via un gestionnaire de complétion. Si aucun ImageLoader n'est fourni, RoktUXHelper utilise par défaut AsyncImage de SwiftUI.

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

PolicesLien direct vers Polices

Rokt UX Helper pourra utiliser des polices personnalisées en les enregistrant simplement dans votre projet et en les configurant sur votre compte Rokt dans One Platform.

Cet article vous a-t-il été utile ?
Last updated Aug 4, 2026