Documentazione

Notifiche push

Consegna le risposte degli operatori e le campagne mentre l’app è chiusa, con un deep link diretto nella conversazione giusta. La tua app possiede il sottosistema push; l’SDK registra i token e apre le conversazioni.

Cosa invia Respondo#

  • Push di messaggio — la risposta di un operatore o dell’IA in una conversazione di cui il visitatore fa parte.
  • Push di campagna — le campagne push in uscita, che riportano anche un beacon di apertura.

Le push di messaggio trasportano sempre un deep link nella forma respondo://conversation/<id>. Le push di campagna trasportano il deep link configurato sulla campagna — è facoltativo, e quando non è impostato la push non contiene alcun deep link.

Apple (APNs)#

Le push iOS viaggiano direttamente su APNs — nessuna dipendenza da Firebase. Dal tuo account Apple Developer, ottieni:

  • Una APNs Auth Key (token key .p8).
  • Il Key ID di quella chiave.
  • Il tuo Team ID.
  • Il bundle id dell’app.

Google (FCM)#

Le push Android passano attraverso Firebase Cloud Messaging. Dal tuo progetto Firebase, ottieni:

  • Un JSON dell’account di servizio con il ruolo Cloud Messaging.
  • Il project ID di Firebase (console Firebase → Impostazioni progetto) — da inserire come campo a sé nel modulo push della dashboard accanto al JSON dell’account di servizio.
  • Il package name dell’app Android, e collega l’app allo stesso progetto Firebase (google-services.json).

Configurazione in Respondo#

Aggiungi la chiave APNs e l’account di servizio FCM con il suo project ID al canale del tuo widget nella dashboard. È tutto ciò di cui Respondo ha bisogno per inviare a entrambe le piattaforme.

L’impostazione delle credenziali tramite API e il riferimento completo dei campi sono trattati nella guida di configurazione delle push fornita con l’accesso al tuo SDK.

Formato del payload#

Il payload risiede sempre sotto una chiave radice respondo — la sua presenza è ciò con cui l’SDK distingue le proprie push dalle altre (su iOS in userInfo, su Android come stringa JSON in data["respondo"]).

payload respondojson
{
  "respondo": {
    "type": "message",
    "conversation_id": "a1c4e7b2-5d38-4f6a-9e10-3b7c2d5f8a90",
    "message_id": "e9a3c1f6-4b8d-4e0a-b5f3-1d7b2a4e9c63",
    "deep_link": "respondo://conversation/a1c4e7b2-5d38-4f6a-9e10-3b7c2d5f8a90"
  }
}

Tutti i valori sono stringhe piatte. Il titolo e il corpo della notifica vengono consegnati dal trasporto della piattaforma — aps.alert su APNs e message.notification su FCM — non dentro l’oggetto respondo.

Le push di campagna includono anche un delivery_id usato per riportare il beacon di apertura, e possono trasportare chiavi stringa piatte aggiuntive dai dati push della campagna.

Gestione di tap & primo piano#

Al tap su una notifica, passa il payload grezzo all’SDK. Esso analizza il payload e apre la conversazione giusta, restituendo false se la push non è una push Respondo (in quel caso gestiscila tu).

Gestione di un tap (per piattaforma)text
Android:  RespondoPushPayload.from(data)?.let { Respondo.handlePush(it) }
iOS:      Respondo.handlePush(userInfo: userInfo)
Flutter:  Respondo.handlePushData(message.data)

I duplicati vengono ridotti per message_id, e mentre la stessa conversazione è aperta in primo piano la notifica di sistema viene soppressa — l’SDK gestisce entrambi automaticamente.

Registrazione dei token del dispositivo#

La tua app ottiene il token del dispositivo dal proprio sottosistema push e lo passa a setPushToken. Chiama clearPushToken al logout.

Quale token passare. Il backend instrada ogni consegna per piattaforma — iOS va direttamente ad APNs, Android va a FCM — quindi devi registrare il token del trasporto nativo della piattaforma, non quello che la tua libreria push restituisce:
  • Android — il token di registrazione FCM da FirebaseMessaging.getToken().
  • iOS (nativo) — il token del dispositivo APNs (esadecimale) da didRegisterForRemoteNotificationsWithDeviceToken.
  • iOS via Flutter (firebase_messaging) — usa getAPNSToken(), non getToken(). Passare il token FCM su iOS lo invia ad APNs, dove non è un token di dispositivo valido e le push non arrivano mai. getAPNSToken() può essere null nei primi istanti dopo l’avvio — se accade, riprova dopo un breve ritardo.
Android — FirebaseMessagingServicekotlin
override fun onNewToken(token: String) {
    Respondo.setPushToken(token)
}
iOS — AppDelegateswift
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
    Respondo.setPushToken(token)
}
Flutter — firebase_messagingdart
// iOS ha bisogno del token APNs; Android ha bisogno del token FCM.
final token = Platform.isIOS
    ? await FirebaseMessaging.instance.getAPNSToken()
    : await FirebaseMessaging.instance.getToken();
if (token != null) Respondo.setPushToken(token);

// FCM ruota il suo token di registrazione; mantieni Android sincronizzato.
if (!Platform.isIOS) {
  FirebaseMessaging.instance.onTokenRefresh.listen(Respondo.setPushToken);
}