Aller au contenu principal

iOS UX Helper

Rokt UX Helper est un projet open source qui vous aide à rendre des expériences client magnifiques 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 en parallèle 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 développement iOS de base.

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 Swift Package Manager (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, le nom de location, la config optionnelle, et les gestionnaires d'événements.

var body: some View {
    RoktLayoutView(experienceResponse: "{experience_response_json}",
                   location: "RoktEmbedded1",
                   config: roktConfig,
                   onUXEvent: { uxEvent in
                       // Gérer les événements UX ici
                   },
                   onPlatformEvent: { platformEvent in
                       // Envoyer ces événements de plateforme à l'API Rokt
                   })
}

É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 l'événement RoktUXEvent.OpenUrl lorsqu'il est déclenché afin de pouvoir ouvrir le lien en utilisant l'exemple ci-dessous.

info

OpenUrl & onCloseLien direct vers OpenUrl & onClose

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

onUXEvent: { uxEvent in // Gérer les événements UX ici
    // Gérer l'événement d'ouverture d'URL
    // Voici un exemple de comment ouvrir différents types d'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) // Cela doit être appelé lorsque l'utilisateur est prêt pour l'offre suivante
            }
        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) // Cela doit être appelé lorsque l'utilisateur est prêt pour l'offre suivante
                })
            }
        }
    }
},
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 le 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 disponiblelayoutId: String
LayoutFailureDéclenché lorsqu'une mise en page n'a pas pu être affichée en raison d'une défaillancelayoutId: String (optionnel)
OpenUrlDéclenché lorsqu'un lien doit être ouverturl: String, id: String, type: OpenURLType (internally/externally/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
    // Envoyer ces événements de plateforme à l'API Rokt
},
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é

Intégrer RoktLayoutView dans votre application iOS est simple et offre une manière flexible de gérer les vues et les expériences. En suivant les étapes décrites dans ce guide, vous pouvez ajouter RoktLayoutView à 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
            // Gérez les événements UX ici
            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
            // Envoyez ces événements de plateforme à l'API Rokt
        }
    )
}

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 applicatif. 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.

// si l'application ne prend en charge que le mode clair.
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 offrir aux partenaires une flexibilité sur le téléchargement des 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()
    }
}

Polices de caractèresLien direct vers Polices de caractères

Rokt UX Helper pourra utiliser des polices de caractères 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 Oct 29, 2025