SDK para iOS (Swift)

TraqioSDK es el SDK de Traqio para apps iOS nativas en Swift. iOS no da a una app ningún install referrer, así que mide con los dos canales que ofrece Apple: registra cada instalación en SKAdNetwork y mantiene su valor de conversión al día según el mapeo que publicas, e informa del token de atribución de Apple Ads, la única fuente determinista en iOS. También pone en cola tus eventos, registra las aperturas de la app y resuelve los universal links. Sin aviso de ATT, sin portapapeles, y sin IDFA salvo que lo actives.

Requisitos#

• iOS 14 o posterior; toolchain de Swift 5.7.
• Frameworks: StoreKit y UIKit, además de AdServices (enlazado de forma débil: ausente antes de iOS 14.3).

Configuración#

1. Añade el paquete#

   Swift Package ManagerCocoaPods

   Package.swift

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

   En Xcode: File → Add Package Dependencies, y luego la URL del repositorio indicada arriba.

   El repositorio público y el pod aún no están abiertos. Mientras tanto, te enviamos el código fuente del paquete: en Xcode, File → Add Package Dependencies → Add Local…, y elige su carpeta.

2. Declara el endpoint de SKAdNetwork#

   Info.plist

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

   iOS envía a Traqio una copia de cada postback de SKAdNetwork de tu app a esta dirección: solo el origen, Apple añade su propia ruta. Sin ella, Traqio solo ve lo que las redes publicitarias deciden informar.

3. Arranca el SDK al iniciar la app#

   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 registra la instalación en SKAdNetwork, obtiene tu mapeo de valores de conversión, pide a AdServices el token de Apple Ads e informa de la instalación una sola vez. Todo se ejecuta en la cola propia del SDK; la llamada vuelve de inmediato.

4. Registra eventos y define el id de usuario#

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

   Cada valor registrado también actualiza el valor de conversión de SKAdNetwork: no hay que llamar a nada más. Nombres de eventos: el vocabulario compartido.

5. Reenvía los universal links#

   El SDK no hace swizzling de tu app delegate. Pásale lo que abre la app: en SwiftUI, las líneas onOpenURL y onContinueUserActivity de arriba; con escenas:

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

   Solo las URL de seguimiento (https://<host>/c/<code>) salen del dispositivo; las URL propias de tu app se resuelven como nil sin ninguna petición, y handleUserActivity devuelve false para ellas, así que tu router las sigue gestionando. Añade applinks:<your domain> en Signing & Capabilities → Associated Domains.

Recibir deep links#

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

Un único callback para el enlace que abrió la app ya instalada y para el enlace diferido de una instalación nueva. En iOS, el enlace diferido solo se conoce si activas la coincidencia por IP de la app en la consola: desactivada por defecto, enruta la primera pantalla y nunca atribuye la instalación. Consulta Deep links diferidos.

Valores de conversión#

Por defecto, el SDK define el valor de conversión de SKAdNetwork según el mapeo publicado para tu app: los ingresos se acumulan entre arranques, el valor solo sube, y el calendario de bloqueos de ventana que configuras se aplica en el dispositivo. Publica el mapeo antes de tu primera campaña: sin él, la instalación se registra pero los postbacks no llevan nada que decodificar. Consulta Atribución en 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)

Identificador publicitario (opcional)#

Desactivado por defecto: el SDK no envía ningún IDFA. Actívalo solo si compras en redes que atribuyen por el IDFA — Unity Ads y AppLovin vinculan su clic con tu instalación gracias a él, y la notificación de instalación de Unity lo necesita. Nunca se usa como identidad de la instalación.

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

• El SDK nunca muestra el aviso de App Tracking Transparency. Pídelo tú antes de start: el IDFA solo se lee si el usuario ya permitió el seguimiento.
• Enlaza AdSupport en tu app (la mayoría de SDK publicitarios ya lo hacen). Traqio accede a él en tiempo de ejecución sin enlazarlo: una app que deja la opción desactivada no incluye código de IDFA por culpa de Traqio.
• Con la opción activada, declara el IDFA en los detalles de privacidad de la App Store.

API#

Aún no está en este SDK#

El SDK de Swift aún no acepta un transactionId de la tienda en las compras, no informa de los ingresos publicitarios de AdMob ni borra a un usuario desde la app. Las compras siguen llegando a través de RevenueCat; el borrado, mediante la llamada del lado del servidor.

Preguntas frecuentes#

¿El SDK de Traqio para iOS necesita App Tracking Transparency?

No. Nunca muestra el aviso de ATT, y solo lee el IDFA si lo activas y tu app ya obtuvo el ATT por su cuenta. SKAdNetwork y el token de atribución de Apple Ads funcionan sin el consentimiento de ATT; para Apple Ads, es la propia Apple la que decide el nivel de detalle de su respuesta según el estado de ATT que el usuario ya eligió para tu app.

¿Qué precisión tiene la atribución en iOS con Traqio?

Las instalaciones de Apple Ads se atribuyen por instalación, mediante el token de AdServices. Las de otras redes se atribuyen mediante SKAdNetwork: Apple envía un postback firmado por instalación a la red publicitaria y a Traqio, al menos 24 horas después de que se cierre la ventana de conversión, con un identificador de campaña y un valor de conversión de seis bits, y retiene los detalles de las campañas demasiado pequeñas para sus umbrales de privacidad. Es una medición a nivel de campaña, no a nivel de usuario.

¿Cuál es la versión mínima de iOS?

iOS 14. El token de Apple Ads necesita iOS 14.3 o posterior; en versiones anteriores el SDK simplemente no tiene ningún token que informar.