Aller au contenu principal

Guide d'Intégration du SDK iOS

Cette page explique comment implémenter le SDK iOS pour Rokt Ads afin de fournir des expériences client plus pertinentes lors du passage en caisse. Le SDK vous permet de déclencher et de suivre ces expériences (comme l'affichage d'offres sur les pages de confirmation) en se déclenchant sur des pages configurées et en transmettant les données utilisateur et de transaction à Rokt pour la personnalisation et la mesure.

Votre représentant de compte dédié vous aidera à configurer votre compte pour le SDK iOS. Ils vous fourniront à la fois la clé et le secret nécessaires pour initialiser le SDK ainsi que des ressources supplémentaires nécessaires pour rendre les expériences les plus pertinentes pour vos clients.

remarque

Ces instructions nécessitent des ressources de développement pour être complétées. Si vous avez besoin d'une assistance supplémentaire, veuillez contacter votre gestionnaire de compte Rokt.

1. Ajouter le SDK Rokt à votre application iOS​

En utilisant soit SPM soit CocoaPods, incluez le SDK Rokt dans votre application :

CocoaPods​

Pour intégrer le SDK en utilisant CocoaPods, spécifiez-le dans votre Podfile avec :

pod 'mParticle-Apple-SDK', '~> 8.0'
pod 'mParticle-Rokt','~> 8.0'

SPM​

Pour intégrer le SDK en utilisant Swift Package Manager :

  1. Ouvrez votre projet dans Xcode, et allez à l'onglet "Package Dependencies".
  2. Cliquez sur le bouton + sous la liste des Packages.
  3. Entrez l'URL du dépôt https://github.com/mParticle/mparticle-apple-sdk dans la boîte de recherche en haut à droite, choisissez mparticle-apple-sdk dans la liste des packages, et changez "Dependency Rule" en "Up to Next Major Version".
  4. Cliquez sur le bouton "Add Package" en bas à droite, et choisissez le "Package Product" appelé mParticle-Apple-SDK. Si vous souhaitez utiliser une version du SDK qui n'inclut pas le support de suivi de localisation, choisissez mParticle-Apple-SDK-NoLocation.
  5. Répétez les étapes 3 et 4 pour l'URL du dépôt Rokt Kit https://github.com/mparticle-integrations/mparticle-apple-integration-rokt.git.
    • Si vous choisissez le package product mParticle-Apple-SDK-NoLocation, vous devrez importer le SDK en utilisant import mParticle_Apple_SDK_NoLocation au lieu de import mParticle_Apple_SDK.

2. Initialiser le SDK Rokt​

Pour initialiser le SDK, insérez le snippet d'initialisation suivant dans votre fichier AppDelegate :

attention
  • Assurez-vous de remplacer your-key et your-secret par la clé et le secret fournis par votre équipe dédiée Rokt.
import mParticle_Apple_SDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // Initialiser le SDK
    let options = MParticleOptions(key: "your-key",
    secret: "your-secret")
    // Spécifiez l'environnement de données avec environment:
    // Réglez-le sur .development si vous testez encore votre intégration.
    // Réglez-le sur .production si votre intégration est prête pour les données de production.
    // La valeur par défaut est .autoDetect qui tente de détecter automatiquement l'environnement
    options.environment = .development
    // Identifiez l'utilisateur actuel :
    let identifyRequest = MPIdentityApiRequest.withEmptyUser()
    // Si vous utilisez une adresse e-mail non hachée, définissez-la dans 'email'.
    identifyRequest.email = "j.smith@example.com"
    // Si l'utilisateur est identifié avec son adresse e-mail, définissez des attributs utilisateur supplémentaires.
    options.identifyRequest = identifyRequest
    options.onIdentifyComplete =  {(result: MPIdentityApiResult?, error: Error?) in
    if let user = result?.user {
        user.setUserAttribute("example attribute key", value: "example attribute value")
    } else {
        //gérer l'échec - voir la section "Gestion des erreurs" ci-dessous
    }
}
    MParticle.sharedInstance().start(with: options)
    return true
}

2.1 Identifier l'utilisateur lors de l'initialisation​

Lorsque le SDK est initialisé, il peut identifier l'utilisateur actuel afin que toutes les données collectées lui soient correctement attribuées et pour s'assurer qu'il voit les publicités les plus pertinentes en fonction de son comportement.

Le script d'initialisation du SDK inclut un objet appelé identifyRequest :

let identifyRequest = MPIdentityApiRequest.withEmptyUser()
identifyRequest.email = "j.smith@example.com"
options.identifyRequest = identifyRequest

2.2 Définir des attributs utilisateur supplémentaires​

Le script d'initialisation inclut une fonction de rappel (callback) qui vous permet de définir des attributs utilisateur supplémentaires si l'utilisateur est identifié avec succès via son adresse e-mail :

options.onIdentifyComplete =  {(result: MPIdentityApiResult?, error: Error?) in
    if let user = result?.user {
        user.setUserAttribute("example attribute key", value: "example attribute value")
    } else {
        //gérer l'échec - voir la section "Gestion des erreurs" ci-dessous
    }
}

3. Identifier l'utilisateur au fur et à mesure que les données deviennent disponibles​

Chaque fois que l'utilisateur fournit son adresse e-mail après l'initialisation du SDK (par exemple, lorsqu'il se connecte ou effectue un achat), vous devez appeler la méthode identify pour transmettre son e-mail à Rokt. Cela garantit que les données sont correctement attribuées à l'utilisateur actuel.

3.1 Créer un identifyRequest​

Pour identifier l'utilisateur, commencez par créer un objet identifyRequest pour contenir l'adresse e-mail de l'utilisateur.

Si vous fournissez une adresse e-mail non hachée, utilisez :

let identifyRequest = MPIdentifyApiRequest.withEmptyUser()
identifyRequest.email = "j.smith@example.com"

3.2 Définir des attributs utilisateur supplémentaires​

Ensuite, vous avez la possibilité de définir des attributs utilisateur supplémentaires lors de l'identification d'un utilisateur en créant une fonction de rappel (callback). Si la requête identifyRequest réussit, alors les attributs utilisateur que vous définissez avec setUserAttribute sont assignés à l'utilisateur.

let identifyCallback = {(result: MPIdentifyApiResult?) in
    if let user = result?.user {
        user.setUserAttribute("example attribute key", value: "example attribute value")
    }
}

3.3 Appeler la méthode identify​

Enfin, après avoir créé votre identifyRequest et votre identityCallback, pour définir des attributs supplémentaires, appelez la méthode identify, en passant les objets identifyRequest et identityCallback que vous venez de créer :

MParticle.sharedInstance().identity.identify(identifyRequest, completion: identityCallback)

Par exemple, pour identifier un utilisateur nommé Jane Smith avec l'adresse e-mail j.smith@example.com (et vous n'avez pas besoin de hacher son adresse e-mail), vous utiliseriez :

let identifyRequest = MPIdentifyApiRequest.withEmptyUser()
identifyRequest.email = "j.smith@example.com"

let identifyCallback = {(result: MPIdentifyApiResult?) in
    if let user = result?.user {
        user.setUserAttribute("example attribute key", value: "example attribute value")
    }
}

MParticle.sharedInstance().identity.identify(identifyRequest, completion: identityCallback)

4. Suivre les Attributs Utilisateur​

Vous pouvez utiliser le SDK Rokt pour collecter des attributs utilisateur séparément des événements. Les attributs utilisateur sont distincts des attributs personnalisés lors du suivi des événements. Le SDK associera tous les attributs utilisateur collectés dans une session donnée aux événements déclenchés dans la même session.

Pour collecter des attributs utilisateur, le code suivant doit être exécuté dans votre application immédiatement après l'initialisation du SDK Rokt, et avant que vous ne journalisiez un événement.

import mParticle_Apple_SDK

// Récupérez l'utilisateur actuel. Cela ne réussira que si vous avez identifié l'utilisateur lors de l'initialisation du SDK ou en appelant la méthode identify.
let currentUser = MParticle.sharedInstance().identity.currentUser

// Une fois que vous avez correctement défini l'utilisateur actuel sur `currentUser`, vous pouvez définir des attributs utilisateur avec :
currentUser?.setUserAttribute("custom-attribute-name", value: "custom-attribute-value")
// Remarque : tous les attributs utilisateur (y compris les attributs de liste et les tags) doivent avoir des noms distincts.

// Rokt recommande de définir autant que possible les attributs utilisateur suivants :
currentUser?.setUserAttribute("firstname", value: "John")
currentUser?.setUserAttribute("lastname", value: "Doe")
// Les numéros de téléphone peuvent être formatés soit comme '1234567890', soit comme '+1 (234) 567-8901'
currentUser?.setUserAttribute("mobile", value: "3125551515")
currentUser?.setUserAttribute("age", value: "33")
currentUser?.setUserAttribute("gender", value: "M")
currentUser?.setUserAttribute("city", value: "Brooklyn")
currentUser?.setUserAttribute("state", value: "NY")
currentUser?.setUserAttribute("zip", value: "123456")
currentUser?.setUserAttribute("dob", value: "yyyymmdd")
currentUser?.setUserAttribute("title", value: "Mr")
currentUser?.setUserAttribute("language", value: "en")
currentUser?.setUserAttribute("value", value: "52.25")
currentUser?.setUserAttribute("predictedltv", value: "136.23")

// Vous pouvez créer un attribut utilisateur pour contenir une liste de valeurs
currentUser?.setUserAttributeList("favorite-genres", values: ["documentary", "comedy", "romance", "drama"])

// Pour supprimer un attribut utilisateur, appelez removeUserAttribute et passez le nom de l'attribut. Tous les attributs utilisateur partagent le même espace de clés.
currentUser?.removeAttribute("attribute-to-remove")

5. Capturer les vues d'écran​

L'un des types d'événements les plus basiques que vous pouvez suivre est la vue d'écran.

Lors de la première intégration avec le SDK Rokt, commencez par implémenter le suivi des vues d'écran. Pour en savoir plus sur le suivi des événements personnalisés et commerciaux, consultez l'Annexe.

Suivre les vues d'écran​

L'un des types d'événements les plus basiques que vous pouvez suivre est la vue d'écran. Pour enregistrer une vue d'écran, appelez la méthode .logScreen, en passant le nom de l'écran sous forme de chaîne de caractères. Le nom que vous passez doit être l'un des ensembles limités de pages, comme 'homepage' ou 'product detail page'. Vous pouvez également inclure des attributs personnalisés supplémentaires dans le tableau eventInfo.

MParticle.sharedInstance().logScreen(
"homepage",
eventInfo: ["custom-attribute": customValue]
)

6. Suivre les conversions​

Pour suivre une conversion, exécutez l'extrait de code suivant sur la page la plus appropriée qui se charge après qu'un client a converti, comme une page de confirmation d'achat ou une page de "remerciement".

Lorsque vous collez l'extrait de code dans votre site, assurez-vous de :

  1. Remplacer les attributs utilisateur d'exemple dans les appels setUserAttribute par les valeurs réelles pour votre utilisateur ou client. Rokt recommande de définir au moins les attributs utilisateur suivants :
    • firstname
    • lastname
    • zipcode
    • mobile
  2. Remplacer les attributs d'événement de conversion d'exemple par les valeurs réelles de votre événement de conversion.

Lors de l'enregistrement d'un événement de conversion, vous devriez inclure autant d'attributs utilisateur et d'attributs d'événement que possible pour améliorer la capacité de Rokt à optimiser vos campagnes.

let currentUser = MParticle.sharedInstance().identity.currentUser
currentUser?.setUserAttribute("firstname", value: "John")
currentUser?.setUserAttribute("lastname", value: "Doe")
currentUser?.setUserAttribute("zipcode", value: "98103")
currentUser?.setUserAttribute("mobile", value: "3125551515")


if let event = MPEvent(name: "conversion", type: .transaction) {
    event.customAttributes = [
        "conversiontype": "signup",     // type de conversion
        "confirmationref": "54321",     // ID de transaction / ID de commande
        "amount": "",                   // Montant de la transaction ex. 300.5
        "currency": "",                 // Devise de la transaction ex. USD
        // Vous pouvez suivre vos propres attributs d'événement personnalisés !
        "CUSTOM_EVENT_ATTRIBUTE_NAME" : "CUSTOM_EVENT_ATTRIBUTE_VALUE"
    ]
    MParticle.sharedInstance().logEvent(event)
}

Annexe​

Suivre les événements personnalisés​

Vous pouvez définir et suivre des événements personnalisés en appelant logEvent et en passant le nom de l'événement, le type d'événement et un tableau optionnel contenant tous les attributs personnalisés pour l'événement.

if let event = MPEvent(name: "Video Watched", type: .navigation) {
    event.customAttributes = ["category": "Destination Intro", "title": "Paris"]
    MParticle.sharedInstance().logEvent(event)
}

Les types d'événements personnalisés pris en charge sont :

  • navigation - Suivre les flux de navigation des utilisateurs et les transitions de page au sein de votre application
  • location - Enregistrer les interactions et mouvements basés sur la localisation de l'utilisateur
  • search - Capturer les requêtes de recherche et les actions utilisateur liées à la recherche
  • transaction - Consigner les transactions financières et les activités liées aux achats
  • userContent - Suivre le contenu généré par les utilisateurs comme les avis, commentaires ou publications
  • userPreference - Enregistrer les paramètres utilisateur, préférences et choix de personnalisation
  • social - Capturer les interactions sur les réseaux sociaux et les activités de partage
</TabItem>

<TabItem value="Objective-C">

* `MPEventTypeNavigation` - Suivre les flux de navigation des utilisateurs et les transitions de page au sein de votre application
* `MPEventTypeLocation` - Enregistrer les interactions et mouvements basés sur la localisation de l'utilisateur
* `MPEventTypeSearch` - Capturer les requêtes de recherche et les actions utilisateur liées à la recherche
* `MPEventTypeTransaction` - Consigner les transactions financières et les activités liées aux achats
* `MPEventTypeUserContent` - Suivre le contenu généré par les utilisateurs comme les avis, commentaires ou publications
* `MPEventTypeUserPreference` - Enregistrer les paramètres, préférences et choix de personnalisation de l'utilisateur
* `MPEventTypeSocial` - Capturer les interactions sur les réseaux sociaux et les activités de partage

</TabItem>

</Tabs>

#### Suivre les événements commerciaux

Le suivi d'un événement commercial nécessite trois étapes :
1. Définir le ou les produits achetés dans une variable en utilisant `MPProduct.init` 
2. Créer un objet MPTransactionAttributes pour enregistrer les détails qui résument la transaction
3. Définir le type d'action et d'événement produit, puis appeler la méthode `logEvent`, en incluant votre définition de produit et le résumé de la transaction

<Tabs
    queryString="codeLanguage"
    className="unique-tabs"
    defaultValue="Swift"
    values={[ {label: 'Swift', value: 'Swift'}, {label: 'Objective-C', value: 'Objective-C'}, ]}>

<TabItem value="Swift">

```swift
// 1. Define the product(s)
let product = MPProduct.init(name: "Double Room",
sku: "econ-1",
quantity: 4,
price: 100.00)

// 2. Summarize the transaction
let attributes = MPTransactionAttributes.init()
attributes.transactionId = "foo-transaction-id"
attributes.revenue = 430.00
attributes.tax = 30.00

// 3. Log the commerce event.
// Several types of "actions" are supported, such as AddToCart and Checkout. This example uses the Purchase product action.
let action = MPCommerceEventAction.purchase;
let event = MPCommerceEvent.init(action: action, product: product)
event.transactionAttributes = attributes
MParticle.sharedInstance().logEvent(event)

Lors de l'enregistrement d'une action produit, vous devez spécifier l'un des types d'action produit suivants :

  • AddToCart
  • RemoveFromCart
  • Checkout
  • CheckoutOption
  • Click
  • ViewDetail
  • Purchase
  • Refund
  • AddToWishlist
  • RemoveFromWishlist
  • Unknown
Cet article vous a-t-il été utile ?
Last updated Oct 29, 2025