Inviare messaggi a gruppi di dispositivi su piattaforme Apple

La messaggistica di gruppo dei dispositivi ti consente di aggiungere più dispositivi a un unico gruppo. È simile alla messaggistica argomento, ma include l'autenticazione per garantire che l'appartenenza al gruppo sia gestita solo dai tuoi server. Ad esempio, se vuoi inviare messaggi diversi a modelli di telefoni diversi, i tuoi server possono aggiungere/rimuovere registrazioni ai gruppi appropriati e inviare il messaggio appropriato a ciascun gruppo. I messaggi di gruppo di dispositivi sono diversi dai messaggi di gruppo di argomenti in quanto richiedono la gestione dei gruppi di dispositivi dai server anziché direttamente all'interno dell'applicazione.

Il numero massimo di membri consentito per una chiave di notifica è 20.

Gestione dei gruppi di dispositivi

Prima di inviare messaggi a un gruppo di dispositivi, devi:

1. Ottieni i token di registrazione per ogni dispositivo che vuoi aggiungere al gruppo.

2. Crea il notification_key, che identifica il gruppo di dispositivi mappando un determinato gruppo (in genere un utente) a tutti i token di registrazione associati al gruppo. Puoi creare chiavi di notifica sul server dell'app.

La gestione di base dei gruppi di dispositivi, ovvero la creazione e la rimozione di gruppi, nonché l'aggiunta o la rimozione di dispositivi, viene eseguita tramite l'API HTTP v1, utilizzando token di breve durata per autorizzare l'invio di richieste. Per un elenco delle chiavi supportate, consulta Chiavi di gestione dei gruppi di dispositivi.

Gestione dei gruppi di dispositivi sul server app

Creazione di un gruppo di dispositivi

Per creare un gruppo di dispositivi, invia una richiesta POST che fornisca un nome per il gruppo e un elenco di token di registrazione per i dispositivi. FCM restituisce un nuovo notification_key che rappresenta il gruppo di dispositivi.

Richiesta POST HTTP

Invia una richiesta come la seguente a https://fcm.googleapis.com/fcm/notification:

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
                        "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
                        ... ]

notification_key_name è un nome o un identificatore (ad es. un nome utente) univoco per un determinato gruppo. notification_key_name e notification_key sono univoci per un gruppo di token di registrazione. È importante che notification_key_name sia univoco per ogni app client se hai più app client per lo stesso ID mittente. In questo modo, i messaggi vengono inviati solo all'app di destinazione prevista.

Formato della risposta

Una richiesta riuscita restituisce un notification_key simile al seguente:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Salva notification_key e il corrispondente notification_key_name da utilizzare nelle operazioni successive.

I token di registrazione non validi vengono eliminati quando viene creato correttamente un gruppo di dispositivi.

Recupero di una chiave di notifica

Se devi recuperare una chiave di notifica esistente, utilizza notification_key_name in una richiesta GET come mostrato di seguito:

https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID
{}

Per ogni richiesta GET per un determinato nome della chiave di notifica, il server restituisce una stringa codificata univoca. Sebbene ogni stringa possa sembrare una chiave diversa, in realtà è un valore "notification_key" valido.

Aggiungere e rimuovere dispositivi da un gruppo di dispositivi

Per aggiungere o rimuovere dispositivi da un gruppo esistente, invia una richiesta POST con il parametro operation impostato su add o remove e fornisci i token di registrazione per l'aggiunta o la rimozione.

Se rimuovi tutti i token di registrazione esistenti da un gruppo di dispositivi, FCM elimina il gruppo di dispositivi.

Richiesta POST HTTP

Ad esempio, per aggiungere un dispositivo con il token di registrazione bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1... a appUser-Chris, invia questa richiesta:

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}

Formato della risposta

Una richiesta di aggiunta o rimozione di un dispositivo andata a buon fine restituisce un notification_key come il seguente:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

Nota: notification_key_name non è obbligatorio per aggiungere/rimuovere i token di registrazione, ma se lo includi ti protegge dall'utilizzo accidentale del valore notification_key errato.

Chiavi di gestione dei gruppi di dispositivi

La tabella seguente elenca le chiavi per creare gruppi di dispositivi e aggiungere e rimuovere membri.

Tabella 10. Chiavi di gestione dei gruppi di dispositivi.

Parametro	Utilizzo	Descrizione
operation	Obbligatorio, stringa	L'operazione da eseguire.I valori validi sono create, add e remove.
notification_key_name	Obbligatorio, stringa	Il nome definito dall'utente del gruppo di dispositivi da creare o modificare.
notification_key	Obbligatorio (tranne per l'operazione create, stringa	Identificatore univoco del gruppo di dispositivi. Questo valore viene restituito nella risposta di un'operazione create riuscita ed è obbligatorio per tutte le operazioni successive sul gruppo di dispositivi.
registration_ids	Obbligatorio, array di stringhe	I token dispositivo da aggiungere o rimuovere. Se rimuovi tutti i token di registrazione esistenti da un gruppo di dispositivi, FCM elimina il gruppo di dispositivi.

Invio di messaggi ai gruppi di dispositivi

L'invio di messaggi a un gruppo di dispositivi è molto simile all'invio di messaggi a un singolo dispositivo, poiché viene utilizzato lo stesso metodo per autorizzare le richieste di invio. Imposta il campo token sulla chiave di notifica del gruppo:

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
      "data":{
        "hello": "This is a Firebase Cloud Messaging device group message!"
      }
   }
}

Comando cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "data":{
     "hello": "This is a Firebase Cloud Messaging device group message!"
   },
   "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Nota: a differenza dei metodi di invio dei gruppi di dispositivi nelle API precedenti ritirate, la risposta HTTP v1 non contiene conteggi di successo e fallimento. Un invio corretto restituisce una risposta vuota.

Invio di messaggi upstream ai gruppi di dispositivi

Per inviare messaggi in upstream ai gruppi di dispositivi sulle app Apple, l'app client Apple deve implementare FIRMessaging.sendMessage:

(void)sendMessage:(nonnull NSDictionary *)message
     to:(nonnull NSString *)receiver
withMessageID:(nonnull NSString *)messageID
timeToLive:(int64_t)ttl;