SDK per iOS

Swift, utilizzabile da Objective-C. Nessuna dipendenza. Include un privacy manifest. Dal piano Pro in su.

Requisiti

• iOS 13+.
• Swift o Objective-C.
• Una chiave SDK: nella dashboard, apri la tua app → Impostazioni → Chiavi SDK → Nuova chiave. Viene mostrata una sola volta, quindi copiala subito.

Installazione

In Xcode, scegli File → Add Package Dependencies…, incolla l’indirizzo del repository, scegli Up to Next Major Version da 0.3.3 e aggiungi la libreria Unolink al target della tua app.

https://github.com/unolink-dev/unolink-sdk

Unolink si installa con Swift Package Manager, non con CocoaPods. Se il tuo progetto usa anche CocoaPods per altre librerie e pod install fallisce con un errore di codifica (Ruby 4, o un locale che non è UTF-8), eseguilo in UTF-8:

LANG=en_US.UTF-8 pod install

Configurazione

Chiama configure una sola volta, il prima possibile: nell’init() della tua App @main, oppure in application(_:didFinishLaunchingWithOptions:).

import Unolink

@main
struct MyApp: App {
    init() {
        #if DEBUG
        Unolink.configure(apiKey: "ulk_…", options: UnolinkOptions(debug: true))
        #else
        Unolink.configure(apiKey: "ulk_…")
        #endif
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

Una libreria compilata non può vedere le tue impostazioni di build, quindi passa tu debug: true dalle build di debug, come sopra. Questo segna l’installazione come dispositivo di test.

Objective-C:

@import Unolink;

[Unolink configureWithApiKey:@"ulk_…" options:[UNLOptions new]];

Opzioni

Unolink.configure(apiKey: "ulk_…", options: UnolinkOptions(logLevel: .debug, debug: true))

La chiave è pubblica: viene distribuita dentro la tua app e può solo riportare dati per quell’unica app. Vedi Chiavi SDK.

Eventi del funnel

Aggiungi una riga in ogni momento importante. Diventano i passaggi in Funnel e Percorsi.

Unolink.onboardingCompleted()                       // the last onboarding screen is done
Unolink.paywallViewed(placement: "onboarding")      // a paywall appeared; placement says which one
Unolink.paywallSkipped(placement: "onboarding")     // closed without buying
Unolink.signUp(method: "apple")                     // an account was created
Unolink.signUpSkipped()                             // went on as a guest (0.3.2+)

Senza RevenueCat, riporta tu prove e acquisti. L’importo è un Decimal, così i prezzi non vengono mai arrotondati:

Unolink.trialStarted(productId: "pro_yearly")
Unolink.purchase(amount: product.price, currency: "USD", productId: product.id)
Unolink.purchaseCancelled(productId: product.id)    // closed the purchase sheet
Unolink.purchaseFailed(productId: product.id, reason: "payment_failed")

I tuoi eventi accettano un nome e fino a 20 proprietà:

Unolink.track("level_up", properties: ["level": 3])

Objective-C:

[Unolink paywallViewedWithPlacement:@"onboarding" properties:nil];
[Unolink purchaseWithAmount:[NSDecimalNumber decimalNumberWithString:@"49.99"] currency:@"USD" productId:nil properties:nil];

L’elenco completo, con i nomi che arrivano alla dashboard, è in Eventi.

ID utente e RevenueCat

Se usi RevenueCat, collegalo dalla tua app → Impostazioni → RevenueCat. Poi non chiamare purchase né trialStarted: RevenueCat invia da solo prove, acquisti, rinnovi, cancellazioni e rimborsi, e Unolink ignora le chiamate di acquisto dell’app, così nulla conta due volte.

Per collegare quegli acquisti all’installazione, riporta l’app user ID di RevenueCat. Con l’SDK 0.3.2 o successivo, una riga lo tiene aggiornato. Chiamala una volta all’avvio, prima o dopo configure:

Unolink.connectRevenueCat { Purchases.isConfigured ? Purchases.shared.appUserID : nil }

Unolink legge l’ID all’avvio, ogni volta che l’app diventa attiva e prima di ogni evento, e lo invia solo quando è cambiato. Dopo Purchases.logIn e Purchases.logOut, chiama Unolink.revenueCatUserChanged() per inviare subito il nuovo ID. Restituisci nil finché RevenueCat non è configurato: leggere Purchases.shared prima di allora blocca l’app.

Senza di esso (o prima della 0.3.2), chiama setUserId con l’ID di RevenueCat dopo Purchases.configure, dopo ogni Purchases.logIn e Purchases.logOut, e a ogni avvio. Usa l’uno o l’altro, non entrambi:

// after Purchases.configure, logIn and logOut, and on every launch
Unolink.setUserId(Purchases.shared.appUserID)

Per un ospite, è l’ID anonimo di RevenueCat, quindi un acquisto fatto prima della registrazione si collega subito all’installazione. Dopo logIn, è l’ID dell’account. Ogni ID riportato da un’installazione conta, così l’acquisto dell’ospite resta collegato. Vedi Ospiti e account.

Unolink non salva mai l’ID in sé, solo un hash unidirezionale diverso per ciascuna delle tue app.

Deep link su iPhone

I deep link differiti sono solo per Android. Apple non fornisce alle app un install referrer, quindi la tua app non può sapere quale link è stato toccato, e Unolink non usa mai il fingerprinting dei dispositivi per indovinarlo. Unolink.onDeferredDeepLink(_:) esiste perché il codice possa essere condiviso tra le piattaforme, ma oggi su iPhone non viene chiamato.

Nella dashboard, le installazioni su iPhone vengono abbinate al clic sul link da cui provengono, senza fingerprinting. L’abbinamento non viene inviato all’app. Puoi disattivarlo per ogni app nelle sue Impostazioni.

I tuoi link mandano comunque i visitatori iPhone direttamente all’App Store e ne contano i clic, e l’SDK continua a contare ogni installazione e ogni evento.

Altre chiamate

Come si comporta

• Primo avvio: crea un ID di installazione casuale in Application Support (escluso dal backup iCloud, mai nel Portachiavi), quindi una reinstallazione o un nuovo telefono sono una nuova installazione.
• Eventi automatici: first_open, session_start (all’avvio, o dopo 30 minuti in background) e app_background. Sono gratis.
• Gli eventi vengono salvati sul dispositivo (fino a 1.000) e inviati a gruppi ogni 15 secondi mentre l’app è attiva, e quando va in background. Offline, aspettano e riprovano.
• Non blocca mai il main thread e non lancia mai eccezioni.

Dispositivi di test

Configura con debug: true nelle build di debug, come sopra. I loro dati sono reali ma nascosti finché non attivi Includi dispositivi di test in Funnel e Percorsi. Altro in Test.

Privacy

• Nessun IDFA, nessuna richiesta di App Tracking Transparency, nessun fingerprinting.
• Il privacy manifest incluso dichiara interazione con il prodotto (i tuoi eventi) e cronologia degli acquisti (gli acquisti che riporti), usati per analytics, non collegati all’identità, e nessun tracciamento. Usa le stesse risposte nell’etichetta sulla privacy dell’App Store.
• Un ID di installazione casuale, versione dell’app, versione del sistema operativo, versione dell’SDK, telefono o tablet, lingua. Il paese deriva dall’edge di rete. Gli indirizzi IP non vengono mai salvati.
• Non mettere mai nomi, email o altri dati personali nelle proprietà degli eventi.

Risoluzione dei problemi

• Niente nella dashboard? Attiva Includi dispositivi di test: le build di debug con debug: true sono nascoste per impostazione predefinita.
• Ancora niente? Configura con UnolinkOptions(logLevel: .debug, debug: true) e cerca [Unolink] nella console di Xcode. Una chiave sbagliata o revocata viene registrata come errore.
• Alcune installazioni iPhone non mostrano alcun link? È normale: non tutte le installazioni iPhone possono essere abbinate a un clic, e queste sono mostrate in una riga a parte. Vedi Deep link su iPhone.

Altro in Risoluzione dei problemi.