Aller au contenu principal

Assistant UX iOS

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 en parallèle avec l'intégration Server-to-Server (S2S) pour offrir des expériences pertinentes à vos clients pendant leur passage à la 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'installation​

La bibliothèque est disponible en tant que dépendance du Swift Package Manager (SPM). Pour l'installer, ajoutez la dépendance SPM suivante à votre fichier package.json. Cette configuration garantit que votre application recevra des 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 requis​

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

import SwiftUI
import RoktUXHelper

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 tels que experienceResponse, le nom location, config optionnel et les gestionnaires d'événements.

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

Événements UX​

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

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

info

OpenUrl & onClose​

event.onClose?(event.id) est crucial pour être appelé après qu'une URL ait été ouverte et informera le RoktUXHelper d'exécuter une logique comme passer à l'offre suivante.

onUXEvent: { uxEvent in // Gérez les événements UX ici
    // Gérez l'événement d'ouverture de l'URL
    // Voici un exemple de la façon d'ouvrir différents types d'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) // Ceci doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
            }
        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) // Ceci doit être appelé lorsque l'utilisateur est prêt pour la prochaine offre
                })
            }
        }
    }
},
Tous les événements

É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'un layout a été rendu et est interactiflayoutId: String
LayoutReadyDéclenché lorsqu'un layout est prêt à s'afficher mais n'a pas encore rendu de contenulayoutId: String
LayoutClosedDéclenché lorsqu'un layout est fermé 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'un layout n'a pas pu s'afficher en raison d'un écheclayoutId: String (optionnel)
OpenUrlDéclenché lorsqu'un lien doit être ouverturl: String, id: String, type: OpenURLType (interne/externe), onClose: (String) -> Void, onError: (String: Error?) -> Void

Envoyer des platformEvents à Rokt​

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

onPlatformEvent: { platformEvent in
    // Envoyer ces événements de plateforme à l'API Rokt
},
Exemple de 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"
   }
}

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

Résumé​

Intégrer 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 à votre projet et tirer pleinement parti des fonctionnalités puissantes proposées 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'application​

RoktUXConfig permet aux applications partenaires de fournir des paramètres de configuration personnalisés à partir de 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.

// si l'application ne prend en charge que le mode clair.
let roktConfig = RoktUXConfig.builder()
                             .colorMode(.light)
                             .imageLoader(imageLoader)
                             .build()

Objet ColorMode​

ValeurDescription
lightL'application est en mode clair
darkL'application est en mode sombre
systemL'application utilise le mode couleur système

RoktUXImageLoader​

Rokt UX Helper accepte un RoktUXImageLoader optionnel pour offrir aux partenaires une flexibilité sur 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 renvoyé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​

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 ?