Aggiungi un programma di affiliazione o referral alla tua app iOS.

Cosa ottieni

Il pacchetto dipende solo da Foundation, StoreKit 2 e CryptoKit, si distribuisce con Swift Package Manager (non esiste un pod CocoaPods) ed è con licenza MIT. Richiede iOS 16 e Swift 5.9 (Xcode 15) o successivi, e si compila anche per macOS 13, tvOS 16 e watchOS 9.

• Attribuzione senza tracciamento. Un codice digitato è una corrispondenza esatta; altrimenti il link-click matching collega l'installazione a un tocco recente sul link del creator, entro 72 ore. Nessun identificatore pubblicitario e nessuna caratteristica del dispositivo, quindi nessun prompt App Tracking Transparency.

• Un campo codice in SwiftUI. InfluToReferralCodeInput valida mentre l'utente digita e applica il codice con un tocco. In UIKit, inseriscilo in un UIHostingController.

• Cattura StoreKit 2 integrata. Nelle app store-direct l'SDK segnala da solo gli acquisti, e InfluTo verifica con Apple ogni transazione firmata.

Passo 1: aggiungi il pacchetto Swift

In Xcode, scegli File → Add Package Dependencies, incolla l'URL del repository e aggiungi la libreria InfluTo al target della tua app. Oppure dichiaralo in Package.swift:

// Xcode → File → Add Package Dependencies →
//   https://github.com/influto/influto-ios   (from 1.1.1)
// Or in Package.swift:
.package(url: "https://github.com/influto/influto-ios.git", from: "1.1.1")

Passo 2: inizializza all'avvio

Ogni metodo dell'SDK è async. Chiama initialize una sola volta all'avvio da un Task e attendilo. Se fallisce (chiave errata, assenza di rete) genera un errore: intercettalo, registralo e vai avanti; al prossimo avvio riprova. In UIKit, avvia il Task da application(_:didFinishLaunchingWithOptions:).

checkAttribution non genera mai errori. In caso di errore, o se initialize non è riuscito, restituisce attributed == false e non salva nulla. Una risposta positiva viene salvata sul dispositivo, quindi le chiamate successive la restituiscono senza fare una richiesta.

La chiave API (it_…, in Setup & SDK) vale sia per lo sviluppo sia per la produzione. Tienila fuori dal codice sotto controllo di versione, per esempio in un .xcconfig non committato, letto tramite Info.plist. Un tipico avvio SwiftUI in un'app con RevenueCat:

import SwiftUI
import InfluTo
import RevenueCat // only if you use RevenueCat

@main
struct MyApp: App {
    init() {
        Purchases.configure(withAPIKey: "appl_…") // RevenueCat apps: configure it first
        Task { await startInfluTo() }
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

func startInfluTo() async {
    var config = InfluToConfig(
        apiKey: Bundle.main.object(forInfoDictionaryKey: "INFLUTO_API_KEY") as? String ?? "",
        appVersion: Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String
    )
    config.revenueCatAttributeSetter = { attrs in
        Purchases.shared.attribution.setAttributes(attrs)
    }
    do {
        try await InfluTo.initialize(config)
    } catch {
        print("InfluTo initialize failed: \(error)") // retried on the next launch
        return
    }
    let attribution = await InfluTo.checkAttribution()
    await InfluTo.identifyUser(Purchases.shared.appUserID)
}

Passo 3: collega gli acquisti

InfluTo paga commissioni solo sugli acquisti verificati con lo store. Scegli una strada per iOS:

• RevenueCat: passa un revenueCatAttributeSetter, come in MyApp.swift qui sopra; senza, su iOS nessuno imposta l'attributo. L'SDK lo chiama una volta, quando trova il referral, quindi configura RevenueCat prima di checkAttribution. Poi collega il webhook in Setup & SDK.

• Store-direct (StoreKit 2): quando l'app è impostata su store-direct in Settings → Validation, initialize inizia a osservare Transaction.updates e recupera i diritti attuali e le transazioni non completate. Ogni transazione viene segnalata una sola volta, in base al suo ID di transazione originale. L'SDK non chiama mai finish(): le transazioni continua a completarle la tua app.

Un dettaglio di StoreKit conta: gli acquisti fatti dentro la tua app tornano a chi ha chiamato product.purchase(), non al listener in background. Quindi segnalali subito dopo un acquisto riuscito, come sotto. Le segnalazioni sono deduplicate, quindi un acquisto segnalato qui e dalla cattura automatica conta comunque una volta sola.

Per collegare le transazioni al tuo ID utente, passa l'account token di StoreKit: product.purchase(options: [.appAccountToken(InfluTo.appAccountToken(forUserID: userID))]), lo stesso UUID ogni volta per un dato ID utente. reportPurchase genera InfluToError.retryable su un 503 (riprova più tardi) e InfluToError.notConfigured su un 400 (iOS non è ancora store-direct).

// Store-direct only (no RevenueCat). Report right after a purchase — StoreKit
// doesn't send purchases made in your app to the background listener, and
// reports are de-duplicated, so this is safe alongside auto-capture:
if case .success(let verification) = try await product.purchase() {
  let r = try await InfluTo.reportPurchase(verification: verification)
}

Passo 4: aggiungi la tua chiave App Store Server API

Lo store-direct richiede l'accesso in lettura all'App Store Server API. InfluTo legge soltanto: non modifica mai nulla nel tuo account App Store Connect.

1. 1

   Crea la chiave. In App Store Connect, apri Users and Access → Integrations → In-App Purchase, crea una chiave e scarica il file .p8. Apple permette di scaricarlo una sola volta. Annota l'Issuer ID e il Key ID.

2. 2

   Caricala. In InfluTo, apri Settings → Validation, trascina il .p8 (il Key ID viene letto dal nome file predefinito di Apple) e inserisci l'Issuer ID, il Key ID e l'App Store ID numerico dell'app.

3. 3

   Scegli l'ambiente, poi attiva. Scegli Sandbox mentre provi con TestFlight o con i tester sandbox, Production prima del rilascio. Quando il controllo delle credenziali è verde, imposta iOS su Apple — direct. Fino ad allora le segnalazioni ricevono un 400, quindi puoi pubblicare l'SDK prima senza rischi.

Da quel momento InfluTo controlla ogni ora con Apple gli abbonamenti attribuiti, per rinnovi, cancellazioni e rimborsi, e annulla la commissione sui rimborsi. Non serve un tuo backend.

Passo 5: prova con TestFlight o un tester sandbox

Gli acquisti TestFlight e sandbox non muovono mai denaro e non alterano le tue statistiche:

1. 1

   Simula un acquisto. Simulate a purchase in Setup & SDK invia un acquisto di prova sandbox attraverso la vera pipeline di InfluTo. Controlla solo il lato InfluTo, mai le tue credenziali.

2. 2

   Installa da un link di referral. Unisciti alla tua campagna con un secondo account creator, apri il suo link su un dispositivo di prova, installa la build TestFlight e avviala. Digitare il codice è il test più affidabile.

3. 3

   Acquista con un account sandbox. Con l'ambiente Apple impostato su Sandbox, acquista con un tester TestFlight o sandbox. L'Integration log, passato a Sandbox, mostra l'acquisto attribuito al tuo codice.

Riporta l'ambiente su Production prima del rilascio: InfluTo verifica esattamente nell'ambiente che scegli. clearAttribution() reimposta il dispositivo per un'altra prova.

Note su iOS

Dettagli che contano per la revisione e per lo store-direct:

• Solo StoreKit 2. Lo store-direct richiede la transazione firmata (JWS): non inviare mai la rappresentazione JSON non firmata. L'SDK invia il JWS anche quando la verifica sul dispositivo fallisce, e InfluTo lo verifica sul server.

• Privacy manifest incluso. Il pacchetto include PrivacyInfo.xcprivacy: nessun tracciamento, nessun dominio di tracciamento, e i tipi di dati raccolti, non collegati all'identità. La documentazione sulla privacy li associa alle tue risposte App Privacy.

• Stato locale. L'SDK conserva il proprio stato nella suite UserDefaults com.influto.sdk. Sopravvive agli aggiornamenti dell'app; se elimini l'app, viene rimosso.

Oppure lascia fare al tuo agente di coding

Collega il server MCP di InfluTo a Claude Code, Codex o Cursor e chiedi l'integrazione: l'agente scrive il codice di avvio e di acquisto, ti dà un link per caricare tu stesso il .p8, esegue il controllo delle credenziali e conferma un acquisto sandbox attribuito.