SDK iOS — Documentazione

1. Requisiti

2. Installazione

Opzione A — Swift Package Manager (consigliata)

In Xcode:

1. File → Add Package Dependencies
2. Incolla l'URL del repository:

https://github.com/willypush/ios-sdk

3. Seleziona versione 2.0.0 (Up to Next Major)
4. Aggiungi il package a entrambi i target: la tua app e la Notification Service Extension

Opzione B — CocoaPods

# Podfile
target 'MyApp' do
  pod 'WillyPush', '~> 2.0'
end

target 'NotificationServiceExtension' do
  pod 'WillyPush', '~> 2.0'
end

Poi esegui pod install.

Opzione C — File framework manuale

1. Scarica il file willy-push-ios-sdk.zip dal bottone in alto
2. Estrai WillyPush.xcframework
3. Trascina il framework nel progetto Xcode
4. Assicurati che sia aggiunto a entrambi i target (app + extension)

3. Inizializzazione

Inizializza il SDK in AppDelegate. Su tutti i piani le push sono cifrate E2EE. Per Enterprise aggiungi hmacSecret per firmare le richieste.

Swift — Starter / Pro (E2EE)

import WillyPush

class AppDelegate: UIResponder, UIApplicationDelegate {

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

        WillyPush.configure(
            domain: "TUO_DOMINIO",
            tags: ["app:ios", "role:customer"]
        )

        WillyPush.registerForPush()

        return true
    }
}

Swift — Piano Enterprise (E2EE a doppia chiave)

WillyPush.configure(
    domain: "TUO_DOMINIO",
    enableE2EE: true,           // Enterprise: chiavi nel Keychain, decrypt locale
    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 il flusso. Il flusso cambia in base al piano.

Flusso Basic / Pro (enableE2EE: false)

Flusso Enterprise E2EE (enableE2EE: true)

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 (solo Enterprise E2EE)

La Notification Service Extension è il componente Apple che permette di modificare il contenuto della push prima di mostrarla. Il SDK la usa per decriptare il payload cifrato con la chiave pubblica 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(
    domain: "TUO_DOMINIO",
    enableE2EE: true,
    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à al device. In modalità Enterprise E2EE verrà decriptata dalla Notification Service Extension; in Basic/Pro arriverà direttamente leggibile

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 Basic/Pro e Enterprise nel SDK?

Basic/Pro (enableE2EE: false): il device si registra con token APNs + tag. Le push arrivano protette dai server Willy in UE, leggibili direttamente via APNs. Nessuna chiave locale, nessun decrypt, non serve la Notification Service Extension.
Enterprise (enableE2EE: true): il device genera una coppia di chiavi nel Keychain. Willy cifra ogni push con la chiave pubblica del device. Solo il telefono può decriptare tramite la Notification Service Extension. Vera E2EE a doppia chiave.
Il codice dei tuoi delegate resta identico in entrambi i casi.

Perché serve la Notification Service Extension in Enterprise?

Apple non permette all'app di intercettare le push in background. La Notification Service Extension è l'unico punto dove puoi modificare (decriptare) il contenuto prima che venga mostrato. Senza, vedresti il payload cifrato. In Basic/Pro non serve perché il contenuto arriva già leggibile.

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.