SDK Android — Documentazione

1. Requisiti

Per le app mobile il server valida il package name (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 (AAR nello ZIP)

1. Scarica willy-push-android-sdk.zip dal bottone in alto
2. Estrai lo ZIP: troverai willy-push-sdk-2.0.0.aar e la documentazione
3. Copia willy-push-sdk-2.0.0.aar nella cartella app/libs/ del tuo progetto
4. Aggiungi nel build.gradle (module app):

dependencies {
    implementation files('libs/willy-push-sdk-2.0.0.aar')
    implementation 'com.google.firebase:firebase-messaging:23.4.0'
}

5. Sincronizza il progetto Gradle

3. Inizializzazione

Inizializza il SDK nella tua classe Application o nella MainActivity. Servono appId e appKey (li trovi nella dashboard → Impostazioni → API). Il server valida queste credenziali insieme al package name della tua app.

Kotlin — Starter / Pro

import it.willypush.sdk.WillyPush
import it.willypush.sdk.WillyConfig

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        WillyPush.init(this, WillyConfig.Builder()
            .appId("IL_TUO_APP_ID")        // Dashboard → Impostazioni → API
            .appKey("LA_TUA_APP_KEY")      // Dashboard → Impostazioni → API
            .tags("app:android", "role:customer")
            .promptDelay(3)
            .build()
        )
    }
}

Kotlin — Enterprise (+ firma HMAC)

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        WillyPush.init(this, WillyConfig.Builder()
            .appId("IL_TUO_APP_ID")
            .appKey("LA_TUA_APP_KEY")
            .hmacSecret("LA_TUA_HMAC_SECRET")  // Enterprise: firma ogni richiesta API
            .tags("app:android", "role:customer")
            .promptDelay(3)
            .build()
        )
    }
}

Java — Esempio base (tutti i piani)

import it.willypush.sdk.WillyPush;
import it.willypush.sdk.WillyConfig;

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        WillyPush.init(this, new WillyConfig.Builder()
            .appId("IL_TUO_APP_ID")
            .appKey("LA_TUA_APP_KEY")
            // .hmacSecret("...")  ← solo Enterprise
            .tags("app:android", "role:customer")
            .promptDelay(3)
            .build()
        );
    }
}

Parametri WillyConfig

4. Registrazione device

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

Flusso di registrazione (tutti i piani)

// Registra quando vuoi, ad esempio dopo il login
WillyPush.register(object : WillyCallback {
    override fun onSuccess(deviceId: String) {
        // Device registrato con successo
    }
    override fun onError(error: WillyError) {
        // Gestisci l'errore
    }
})

5. Ricezione e decrypt push

Crea un service che estende WillyPushService. Il SDK riceve la push cifrata, la decripta con la chiave privata del device e chiama onDecryptedMessage con il contenuto in chiaro.

Kotlin

import it.willypush.sdk.WillyPushService
import it.willypush.sdk.WillyPayload

class MyPushService : WillyPushService() {

    override fun onDecryptedMessage(payload: WillyPayload) {
        // Il contenuto è già decriptato dal SDK.
        // payload.title   → titolo della notifica
        // payload.body    → corpo del messaggio
        // payload.data    → Map<String, String> dati extra
        // payload.image   → URL immagine (opzionale)

        showNotification(payload)  // metodo helper del SDK
    }

    override fun onNotificationClicked(payload: WillyPayload) {
        // L'utente ha toccato la notifica.
        // Naviga alla schermata giusta.
        val deepLink = payload.data["url"]
        // startActivity(...)
    }
}

Java

import it.willypush.sdk.WillyPushService;
import it.willypush.sdk.WillyPayload;

public class MyPushService extends WillyPushService {

    @Override
    public void onDecryptedMessage(WillyPayload payload) {
        showNotification(payload);
    }

    @Override
    public void onNotificationClicked(WillyPayload payload) {
        String deepLink = payload.getData().get("url");
    }
}

6. Configurazione manifest

Aggiungi il tuo service nel AndroidManifest.xml:

<!-- AndroidManifest.xml -->
<application>

    <!-- Il tuo push service -->
    <service
        android:name=".MyPushService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>

    <!-- Application class (se usi classe custom) -->
    <!-- android:name=".MyApp" -->

</application>

<!-- Android 13+: permesso notifiche runtime -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

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

// Rimuove tutti i tag precedenti e imposta solo questi
WillyPush.setTags("role:admin", "app:android")

Leggere i tag attuali

val tags: List<String> = WillyPush.getTags()
// ["role:customer", "citta:roma", "app:android"]

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", mapOf(
    "productId" to "SKU-123",
    "productName" to "Pizza Margherita",
    "price" to "8.50",
    "category" to "pizza"
))

Carrello abbandonato

WillyPush.trackEvent("cart_abandoned", mapOf(
    "cartValue" to "32.00",
    "items" to "3"
))

Acquisto completato

WillyPush.trackEvent("purchase_completed", mapOf(
    "orderId" to "ORD-456",
    "total" to "32.00",
    "items" to "3"
))

9. Ciclo di vita

Il SDK gestisce automaticamente i seguenti scenari:

Logout / cancellazione

// Quando l'utente fa logout: rimuovi i tag personali
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

WillyConfig.Builder()
    .appId("IL_TUO_APP_ID")
    .appKey("LA_TUA_APP_KEY")
    .debug(true)   // log dettagliati in Logcat
    .build()

Filtra i log in Logcat con il tag WillyPush:

adb logcat -s WillyPush

Verifica la registrazione

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

Invia una push di test

1. Installa l'app sul device o emulatore (con Google Play Services)
2. Accedi alla dashboard Willy Push
3. Crea una nuova campagna
4. Seleziona il segmento app:android
5. Invia la campagna
6. La push arriverà cifrata al device e il SDK la decripterà automaticamente

11. Riferimento API

12. FAQ

Il SDK funziona con Jetpack Compose?

Si. Il SDK non ha dipendenze da View o XML. L'inizializzazione avviene in Application, la ricezione nel service. Puoi 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, Willy cifra, il device 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.

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 aumenta la dimensione dell'APK?

Il SDK pesa meno di 120 KB dopo ProGuard/R8. Non include dipendenze pesanti oltre a Firebase Messaging (che probabilmente hai già).

Funziona con Firebase Cloud Messaging v2?

Si. Il SDK è compatibile con FCM API v1 e v2. Non serve configurazione aggiuntiva.

Posso usare il SDK su Kotlin Multiplatform (KMP)?

Il SDK Android è nativo. Per un progetto KMP, aggiungilo nel modulo Android come dipendenza specifica della piattaforma.

Come gestisco gli utenti che hanno già l'app senza Willy Push?

Al primo avvio dopo l'aggiornamento, il SDK si registra automaticamente. Gli utenti esistenti inizieranno a ricevere push senza fare nulla. Puoi distinguerli con tag migration:v2.