SDK iOS — Documentazione

1. Requisiti

Per le app mobile il server valida il Bundle ID (equivalente del dominio per il web) al posto dell'header Origin del browser. Questo impedisce che un'altra app possa usare le stesse credenziali.

2. Installazione

Installazione (XCFramework nello ZIP)

1. Scarica willy-push-ios-sdk.zip dal bottone in alto
2. Estrai lo ZIP: troverai WillyPush.xcframework e la documentazione
3. Trascina WillyPush.xcframework nel progetto Xcode
4. Assicurati che sia aggiunto a entrambi i target: la tua app e la Notification Service Extension
5. Scegli "Copy items if needed" e "Add to targets"

3. Inizializzazione

Inizializza il SDK in AppDelegate. Servono appId e appKey (li trovi nella dashboard → Impostazioni → API). Il server valida queste credenziali insieme al Bundle ID della tua app.

Swift — Starter / Pro

import WillyPush

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions:
            [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        WillyPush.configure(
            appId: "IL_TUO_APP_ID",       // Dashboard → Impostazioni → API
            appKey: "LA_TUA_APP_KEY",      // Dashboard → Impostazioni → API
            tags: ["app:ios", "role:customer"]
        )

        WillyPush.registerForPush()

        return true
    }
}

Swift — Enterprise (+ firma HMAC)

WillyPush.configure(
    appId: "IL_TUO_APP_ID",
    appKey: "LA_TUA_APP_KEY",
    hmacSecret: "LA_TUA_HMAC_SECRET",  // Enterprise: firma ogni richiesta API
    tags: ["app:ios", "role:customer"]
)

SwiftUI (App protocol)

import SwiftUI
import WillyPush

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Parametri di configurazione

4. Registrazione device

Con autoRegister: true (default), il SDK gestisce automaticamente tutto il flusso E2EE.

Flusso di registrazione (tutti i piani)

Gestione del token APNs in AppDelegate:

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    WillyPush.didRegisterForRemoteNotifications(deviceToken: deviceToken)
}

func application(
    _ application: UIApplication,
    didFailToRegisterForRemoteNotificationsWithError error: Error
) {
    WillyPush.didFailToRegisterForRemoteNotifications(error: error)
}

// Registra quando vuoi, ad esempio dopo il login
WillyPush.register { result in
    switch result {
    case .success(let deviceId):
        print("Registrato: \(deviceId)")
    case .failure(let error):
        print("Errore: \(error)")
    }
}

5. Ricezione e decrypt push

Il decrypt avviene nella Notification Service Extension (vedi sezione successiva). Per gestire il tap sulla notifica, implementa il delegate:

import WillyPush

extension AppDelegate: WillyPushDelegate {

    func willyPush(didReceiveDecrypted payload: WillyPayload) {
        // Notifica ricevuta con app in foreground
        // payload.title, payload.body, payload.data, payload.image
    }

    func willyPush(didTapNotificationWith payload: WillyPayload) {
        // L'utente ha toccato la notifica
        if let url = payload.data["url"] {
            // Naviga alla schermata giusta
        }
    }
}

Registra il delegate dopo l'inizializzazione:

WillyPush.delegate = self

6. Notification Service Extension

La Notification Service Extension è il componente Apple che intercetta la push prima di mostrarla e permette al SDK di decriptare il payload con la chiave privata del device.

Creare l'extension

1. In Xcode: File → New → Target
2. Scegli Notification Service Extension
3. Nome: NotificationServiceExtension (o come preferisci)
4. Assicurati che il package WillyPush sia aggiunto anche a questo target
5. Abilita la capability Keychain Sharing su entrambi i target (app + extension) con lo stesso gruppo

Codice dell'extension

import UserNotifications
import WillyPush

class NotificationService: WillyPushNotificationService {
    // Il SDK gestisce automaticamente:
    // 1. Intercetta la push cifrata
    // 2. Legge la chiave privata dal Keychain
    // 3. Decripta il payload
    // 4. Sostituisce il contenuto della notifica
    // 5. Mostra la notifica decriptata all'utente

    // Opzionale: override per personalizzare
    override func didDecrypt(
        _ payload: WillyPayload,
        content: UNMutableNotificationContent
    ) {
        // Personalizza il contenuto se necessario
        content.title = payload.title
        content.body = payload.body
        content.sound = .default
    }
}

7. Segmentazione e tag

I tag permettono di segmentare gli utenti per creare campagne mirate dalla dashboard Willy Push.

Aggiungere tag

// Aggiungi tag in qualsiasi momento
WillyPush.addTags(["categoria:pizza", "citta:roma", "piano:premium"])

// Utile dopo il login
WillyPush.addTags(["role:customer", "user_id:12345"])

Rimuovere tag

WillyPush.removeTags(["role:guest", "categoria:pizza"])

Sostituire tutti i tag

WillyPush.setTags(["role:admin", "app:ios"])

Leggere i tag attuali

let tags = WillyPush.getTags()
// ["role:customer", "citta:roma", "app:ios"]

Esempi di segmentazione

8. Eventi e-commerce

Se la tua app ha un e-commerce, puoi tracciare eventi per campagne automatiche:

Prodotto visualizzato

WillyPush.trackEvent("product_view", data: [
    "productId": "SKU-123",
    "productName": "Pizza Margherita",
    "price": "8.50",
    "category": "pizza"
])

Carrello abbandonato

WillyPush.trackEvent("cart_abandoned", data: [
    "cartValue": "32.00",
    "items": "3"
])

Acquisto completato

WillyPush.trackEvent("purchase_completed", data: [
    "orderId": "ORD-456",
    "total": "32.00",
    "items": "3"
])

9. Ciclo di vita

Il SDK gestisce automaticamente i seguenti scenari:

Logout / cancellazione

// Quando l'utente fa logout
WillyPush.removeTags(["role:customer", "user_id:12345"])
WillyPush.addTags(["role:guest"])

// Per cancellare completamente il device da Willy:
WillyPush.unregister()

10. Test e debug

Abilita la modalità debug

WillyPush.configure(
    appId: "IL_TUO_APP_ID",
    appKey: "LA_TUA_APP_KEY",
    debug: true   // log nella Console di Xcode
)

Filtra i log nella Console con il sottosistema it.willypush.

Verifica la registrazione

let isRegistered = WillyPush.isRegistered()
let deviceId = WillyPush.getDeviceId()
let tags = WillyPush.getTags()

Invia una push di test

1. Installa l'app su un device fisico (le push APNs non funzionano sul Simulator)
2. Accedi alla dashboard Willy Push
3. Crea una nuova campagna
4. Seleziona il segmento app:ios
5. Invia la campagna
6. La push arriverà cifrata, la Notification Service Extension la decripterà e la mostrerà all'utente

11. Riferimento API

12. FAQ

Funziona con SwiftUI?

Si. L'inizializzazione avviene in AppDelegate (usa @UIApplicationDelegateAdaptor con il protocol App). Il resto dell'app può usare qualsiasi architettura UI.

Qual è la differenza tra Starter/Pro e Enterprise nel SDK?

Su tutti i piani le push sono cifrate E2EE: il device genera le chiavi nel Keychain, Willy cifra, la Notification Service Extension decripta. Il codice è identico.
La differenza è che su Enterprise puoi aggiungere hmacSecret per firmare ogni richiesta API con HMAC-SHA256. Questo aggiunge un livello di sicurezza extra: impedisce registrazioni non autorizzate e garantisce che solo la tua app possa comunicare con il tuo account.

Perché serve la Notification Service Extension?

Poiché tutte le push sono cifrate, Apple non permetterebbe di mostrarle direttamente (il contenuto sarebbe illeggibile). La Notification Service Extension è l'unico punto dove il SDK può decriptare il payload prima che venga mostrato all'utente. È obbligatoria su tutti i piani.

Posso usare il SDK senza HMAC?

Si. Su Starter e Pro non serve. Le push sono comunque cifrate E2EE. L'HMAC è un livello aggiuntivo disponibile su Enterprise.

Il SDK supporta iPad?

Si. Il SDK funziona su iPhone e iPad con lo stesso codice. Le push arrivano su entrambi i device se registrati.

Posso usare il SDK con Objective-C?

Si. Le API pubbliche del SDK sono annotate con @objc e compatibili con Objective-C.

Quanto pesa il SDK?

Il framework pesa meno di 100 KB. Non ha dipendenze esterne oltre ai framework Apple standard.

Funziona con l'ambiente sandbox APNs?

Si. Il SDK rileva automaticamente se stai usando l'ambiente sandbox (development) o production. Willy Push gestisce entrambi.