# SDK para iOS (Swift)

URL: https://traqio.app/es/docs/sdks/ios
Last updated: 2026-10-22

Añade Traqio a una app iOS nativa: TraqioSDK registra instalaciones en SKAdNetwork, fija valores de conversión según tu mapeo e informa de Apple Ads.

`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

### Añade el paquete

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

CocoaPods:
```ruby
# Podfile
pod 'TraqioSDK', '~> 0.1'
```

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.

### Declara el endpoint de SKAdNetwork

Info.plist:
```xml
<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.

### Arranca el SDK al iniciar la app

SwiftUI:
```swift
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) }
        }
    }
}
```

UIKit:
```swift
import UIKit
import TraqioSDK

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Traqio.start(sdkKey: "YOUR_SDK_KEY", endpoint: "https://api.traqio.app")
    return true
}
```

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

### Registra eventos y define el id de usuario

```swift
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](https://traqio.app/es/docs/concepts/events-and-revenue#names).

### 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:

```swift
// 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

```swift
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](https://traqio.app/es/docs/concepts/deep-linking#deferred).

## 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](https://traqio.app/es/docs/concepts/ios-attribution).

```swift
// 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.

```swift
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

| Llamada | Qué hace |
| --- | --- |
| start(sdkKey:endpoint:userId:deepLinking:consent:collectAdvertisingId:) | Arranca una vez; registra en SKAdNetwork, informa de Apple Ads y envía la instalación. |
| track(_:value:currency:) | Pone un evento en cola y actualiza el valor de conversión. |
| setUserId(_:) | Asocia tu id de usuario a partir de ahora. |
| setConsent(_:) | Guarda el consentimiento del usuario para compartir con redes publicitarias. |
| appOpened() | Informa tú mismo de una vuelta al primer plano; las apps UIKit lo obtienen automáticamente. |
| onDeepLink(_:) | Se suscribe a los deep links; llama a cancel() en la suscripción devuelta para dejar de recibirlos. |
| handleUrl(_:) · handleUserActivity(_:) | Resuelve la URL que abrió la app. |
| getDeferredDeepLink(_:) | El enlace diferido de la instalación, o nil. |
| TraqioSkan.updateConversionValue(_:coarse:lockWindow:) | Define tú mismo el valor de conversión (solo con esquema propio). |

## 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](https://traqio.app/es/docs/integrations/revenuecat); el borrado, mediante la [llamada del lado del servidor](https://traqio.app/es/docs/concepts/privacy#erasure).

> **Qué se puede probar hoy** La parte del SDK (la instalación en Eventos en directo, el mapeo obtenido) se ve enseguida. Los postbacks de SKAdNetwork los envía Apple al menos un día después de la ventana de conversión, y solo para instalaciones procedentes de campañas publicitarias reales.

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