SDK iOS (Swift)

TraqioSDK est le SDK Traqio pour les apps iOS natives en Swift. iOS ne fournit aucun install referrer à une app : le SDK mesure donc avec les deux canaux qu’Apple met à disposition. Il enregistre chaque installation auprès de SKAdNetwork et tient sa valeur de conversion à jour à partir du mapping que vous publiez, et il transmet le jeton d’attribution Apple Ads — la seule source iOS déterministe. Il met aussi en file d’attente vos événements, enregistre les ouvertures de l’app et résout les universal links. Pas d’invite ATT, pas de presse-papiers, et pas d’IDFA sauf si vous l’activez.

Prérequis#

• iOS 14 ou ultérieur ; toolchain Swift 5.7.
• Frameworks : StoreKit et UIKit, plus AdServices (lié en weak — absent avant iOS 14.3).

Mise en place#

1. Ajoutez le paquet#

   Swift Package ManagerCocoaPods

   Package.swift

   // Package.swift
   .package(url: "https://github.com/khufuio/traqio-ios", from: "0.1.0")

   Dans Xcode : File → Add Package Dependencies, puis l’URL du dépôt ci-dessus.

   Le dépôt public et le pod ne sont pas encore ouverts. D’ici là, nous vous envoyons les sources du paquet : dans Xcode, File → Add Package Dependencies → Add Local…, puis choisissez son dossier.

2. Déclarez l’endpoint SKAdNetwork#

   Info.plist

   <key>NSAdvertisingAttributionReportEndpoint</key>
   <string>https://api.traqio.app</string>

   iOS envoie à Traqio une copie de chaque postback SKAdNetwork de votre app à cette adresse — l’origine seule, Apple ajoute son propre chemin. Sans elle, Traqio ne voit que ce que les réseaux publicitaires choisissent de déclarer.

3. Démarrez le SDK au lancement#

   SwiftUIUIKit

   import SwiftUI
   import TraqioSDK
   
   @main
   struct MyApp: App {
       init() {
           Traqio.start(sdkKey: "YOUR_SDK_KEY", endpoint: "https://api.traqio.app")
       }
       var body: some Scene {
           WindowGroup {
               ContentView()
                   .onOpenURL { Traqio.handleUrl($0) }
                   .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { Traqio.handleUserActivity($0) }
           }
       }
   }

   start enregistre l’installation auprès de SKAdNetwork, récupère votre mapping des valeurs de conversion, demande à AdServices le jeton Apple Ads et signale l’installation une seule fois. Tout s’exécute sur la file propre au SDK ; l’appel rend la main immédiatement.

4. Suivez les événements et définissez l’identifiant utilisateur#

   Traqio.setUserId(user.id)   // after sign-in — same id as RevenueCat's app_user_id
   Traqio.track("signup")
   Traqio.track("purchase", value: 9.99, currency: "EUR")

   Chaque valeur suivie fait aussi évoluer la valeur de conversion SKAdNetwork — rien d’autre à appeler. Noms d’événements : le vocabulaire partagé.

5. Transmettez les universal links#

   Le SDK ne fait pas de swizzling sur votre app delegate. Transmettez-lui ce qui ouvre l’app — en SwiftUI, les lignes onOpenURL et onContinueUserActivity ci-dessus ; avec des scenes :

   // UISceneDelegate — a warm open, then a cold start
   func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
       Traqio.handleUserActivity(userActivity)
   }
   
   func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options: UIScene.ConnectionOptions) {
       options.userActivities.forEach { Traqio.handleUserActivity($0) }
   }

   Seules les URL de tracking (https://<host>/c/<code>) quittent l’appareil ; les URL propres à votre app se résolvent en nil sans requête, et handleUserActivity renvoie false pour elles, si bien que votre routeur les gère toujours. Ajoutez applinks:<your domain> sous Signing & Capabilities → Associated Domains.

Recevoir les deep links#

let subscription = Traqio.onDeepLink { link in
    if let path = link.deepLink { router.open(path) }
}
// keep `subscription`; subscription.cancel() unsubscribes

Un seul callback pour le lien qui a ouvert l’app installée et pour le lien différé d’une nouvelle installation. Sur iOS, le lien différé n’est connu que si vous activez le rapprochement par IP pour l’app dans la console — désactivé par défaut, il oriente le premier écran et n’attribue jamais l’installation. Voir Deep links différés.

Valeurs de conversion#

Par défaut, le SDK définit la valeur de conversion SKAdNetwork à partir du mapping publié pour votre app : les revenus s’accumulent d’un lancement à l’autre, la valeur ne fait que monter, et le calendrier de verrouillage des fenêtres que vous configurez est appliqué sur l’appareil. Publiez le mapping avant votre première campagne — sans lui, l’installation est enregistrée mais les postbacks ne transportent rien à décoder. Voir Attribution iOS.

// Only if your app owns its own conversion-value schema — never together with
// the mapping published in the console: two writers, one six-bit value.
TraqioSkan.updateConversionValue(12, coarse: .medium, lockWindow: false)

Identifiant publicitaire (à activer)#

Désactivé par défaut : le SDK n’envoie aucun IDFA. Activez-le seulement si vous achetez sur des régies qui attribuent par l’IDFA — Unity Ads et AppLovin rattachent leur clic à votre installation grâce à lui, et la notification d’installation de Unity en a besoin. Il ne sert jamais d’identité à l’installation.

Traqio.start(sdkKey: "YOUR_SDK_KEY", endpoint: "https://api.traqio.app", collectAdvertisingId: true)

• Le SDK n’affiche jamais l’invite App Tracking Transparency. Demandez-la vous-même avant start : l’IDFA n’est lu que si l’utilisateur a déjà autorisé le suivi.
• Liez AdSupport dans votre app (la plupart des SDK publicitaires le font déjà). Traqio y accède à l’exécution sans le lier lui-même : une app qui laisse l’option désactivée n’embarque aucun code IDFA à cause de Traqio.
• Option activée, déclarez l’IDFA dans vos informations de confidentialité App Store.

API#

Pas encore dans ce SDK#

Le SDK Swift n’accepte pas encore de transactionId du store sur les achats, ne transmet pas les revenus publicitaires AdMob et n’efface pas un utilisateur depuis l’app. Les achats arrivent tout de même via RevenueCat ; l’effacement via l’appel côté serveur.

Questions fréquentes#

Le SDK iOS de Traqio a-t-il besoin d’App Tracking Transparency ?

Non. Il n’affiche jamais l’invite ATT, et ne lit l’IDFA que si vous l’activez et que votre app a déjà obtenu l’ATT elle-même. SKAdNetwork et le jeton d’attribution Apple Ads fonctionnent tous deux sans consentement ATT ; pour Apple Ads, c’est Apple qui décide du niveau de détail de sa réponse, d’après le statut ATT que l’utilisateur a déjà choisi pour votre app.

Quelle est la précision de l’attribution iOS avec Traqio ?

Les installations issues d’Apple Ads sont attribuées par installation, via le jeton AdServices. Les installations issues des autres réseaux sont attribuées via SKAdNetwork : Apple envoie un postback signé par installation au réseau publicitaire et à Traqio, au moins 24 heures après la fermeture de la fenêtre de conversion, avec un identifiant de campagne et une valeur de conversion sur six bits — et retient les détails des campagnes trop petites pour ses seuils de confidentialité. C’est une mesure au niveau de la campagne, pas de l’utilisateur.

Quelle est la version minimale d’iOS ?

iOS 14. Le jeton Apple Ads nécessite iOS 14.3 ou ultérieur ; sur les versions antérieures, le SDK n’a simplement aucun jeton à transmettre.