Esegui la migrazione dalle API FCM precedenti a HTTP v1

Le app che utilizzano le API FCM legacy deprecate per HTTP e XMPP devono eseguire la migrazione all'API HTTP v1 non appena possibile. L'invio di messaggi (inclusi i messaggi upstream) con queste API è stato ritirato il 20 giugno 2023 e la chiusura inizierà il 22 luglio 2024.

Scopri di più sulle funzionalità specifiche interessate.

Oltre al supporto continuo e alle nuove funzionalità, l'API HTTP v1 offre i seguenti vantaggi rispetto alle API precedenti:

• Maggiore sicurezza tramite token di accesso L'API HTTP v1 utilizza token di accesso di breve durata in base al modello di sicurezza OAuth2. Nel caso in cui un token di accesso diventi pubblico, può essere utilizzato in modo dannoso per circa un'ora prima della scadenza. I token di aggiornamento non vengono trasmessi con la stessa frequenza delle chiavi di sicurezza utilizzate nell'API precedente, quindi è molto meno probabile che vengano acquisiti.

• Personalizzazione più efficiente dei messaggi su più piattaforme Per il corpo del messaggio, l'API HTTP v1 ha chiavi comuni che vanno a tutte le istanze di destinazione, oltre a chiavi specifiche della piattaforma che consentono di personalizzare il messaggio su più piattaforme. In questo modo puoi creare "override" che inviano payload leggermente diversi a piattaforme client diverse in un unico messaggio.

• Più estendibile e a prova di futuro per le nuove versioni della piattaforma client L'API HTTP v1 supporta completamente le opzioni di messaggistica disponibili su piattaforme Apple, Android e web. Poiché ogni piattaforma ha il proprio blocco definito nel payload JSON, FCM può estendere l'API a nuove versioni e nuove piattaforme in base alle esigenze.

Aggiorna l'endpoint del server

L'URL dell'endpoint per l'API HTTP v1 differisce dall'endpoint legacy nei seguenti modi:

• È sottoposto al controllo delle versioni, con /v1 nel percorso.
• Il percorso contiene l'ID progetto del progetto Firebase per la tua app, nel formato /projects/myproject-ID/. Questo ID è disponibile nella scheda Impostazioni generali del progetto della console Firebase.
• Specifica esplicitamente il metodo send come :send.

Per aggiornare l'endpoint del server per HTTP v1, aggiungi questi elementi all'endpoint nell'intestazione delle richieste di invio.

Richieste HTTP prima

POST https://fcm.googleapis.com/fcm/send

Richieste XMPP prima del giorno

I messaggi XMPP legacy vengono inviati tramite una connessione al seguente endpoint:

fcm-xmpp.googleapis.com:5235

Dopo

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

Aggiorna l'autorizzazione delle richieste di invio

Al posto della stringa della chiave del server utilizzata nelle richieste precedenti, le richieste di invio HTTP v1 richiedono un token di accesso OAuth 2.0. Se utilizzi l'SDK Admin per inviare messaggi, la libreria gestisce il token per te. Se utilizzi il protocollo non elaborato, ottieni il token come descritto in questa sezione e aggiungilo all'intestazione come Authorization: Bearer <valid Oauth 2.0 token>.

Prima

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Dopo

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

A seconda dei dettagli dell'ambiente server, utilizza una combinazione di queste strategie per autorizzare le richieste del server ai servizi Firebase:

• Credenziali predefinite dell'applicazione Google (ADC)
• Un file JSON del service account
• Un token di accesso OAuth 2.0 di breve durata derivato da un service account

Se la tua applicazione viene eseguita su Compute Engine, Google Kubernetes Engine, App Engine o Cloud Functions (incluso Cloud Functions for Firebase), utilizza le credenziali predefinite dell'applicazione (ADC). ADC utilizza il service account predefinito esistente per ottenere le credenziali per autorizzare le richieste e consente test locali flessibili tramite la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS. Per l'automazione più completa del flusso di autorizzazione, utilizza ADC insieme alle librerie server dell'SDK Admin.

Se la tua applicazione viene eseguita in un ambiente server non Google, devi scaricare un file JSON dell'account di servizio dal tuo progetto Firebase. Se hai accesso a un file system contenente il file della chiave privata, puoi utilizzare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS per autorizzare le richieste con queste credenziali ottenute manualmente. Se non disponi di questo accesso ai file, devi fare riferimento al file dell'account di servizio nel codice, operazione da eseguire con estrema attenzione a causa del rischio di esporre le tue credenziali.

Fornire le credenziali utilizzando ADC

Le Credenziali predefinite dell'applicazione Google (ADC) cercano le tue credenziali nel seguente ordine:

1. ADC controlla se la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS è impostata. Se la variabile è impostata, ADC utilizza il file del service account a cui punta la variabile.

2. Se la variabile di ambiente non è impostata, ADC utilizza l'account di servizio predefinito che Compute Engine, Google Kubernetes Engine, App Engine e Cloud Functions forniscono per le applicazioni eseguite su questi servizi.

3. Se ADC non può utilizzare nessuna delle credenziali sopra indicate, il sistema genera un errore.

Il seguente esempio di codice dell'SDK Admin illustra questa strategia. L'esempio non specifica esplicitamente le credenziali dell'applicazione. Tuttavia, ADC è in grado di trovare implicitamente le credenziali purché la variabile di ambiente sia impostata o purché l'applicazione sia in esecuzione su Compute Engine, Google Kubernetes Engine, App Engine o Cloud Functions.

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

default_app = firebase_admin.initialize_app()

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}
init.go

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

Fornire le credenziali manualmente

I progetti Firebase supportano gli account di servizio Google, che puoi utilizzare per chiamare le API server Firebase dal server delle app o dall'ambiente attendibile. Se stai sviluppando codice localmente o eseguendo il deployment della tua applicazione on-premise, puoi utilizzare le credenziali ottenute tramite questo service account per autorizzare le richieste del server.

Per autenticare un service account e autorizzarlo ad accedere ai servizi Firebase, devi generare un file della chiave privata in formato JSON.

Per generare un file della chiave privata per il tuo service account:

1. Nella console Firebase, apri Impostazioni > Service account.

2. Fai clic su Genera nuova chiave privata, poi conferma facendo clic su Genera chiave.

3. Archivia in modo sicuro il file JSON contenente la chiave.

Quando autorizzi tramite un service account, hai due opzioni per fornire le credenziali alla tua applicazione. Puoi impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS oppure passare esplicitamente il percorso della chiave del service account nel codice. La prima opzione è più sicura ed è vivamente consigliata.

Per impostare la variabile di ambiente:

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave dell'account di servizio. Questa variabile si applica solo alla sessione di shell corrente, quindi se apri una nuova sessione, imposta di nuovo la variabile.

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Dopo aver completato i passaggi precedenti, le credenziali predefinite dell'applicazione (ADC) sono in grado di determinare implicitamente le tue credenziali, consentendoti di utilizzare le credenziali dell'account di servizio durante i test o l'esecuzione in ambienti non Google.

Utilizzare le credenziali per generare token di accesso

Utilizza le tue credenziali Firebase insieme alla libreria di autenticazione Google per la lingua che preferisci per recuperare un token di accesso OAuth 2.0 di breve durata:

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}
index.js

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token
messaging.py

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refresh();
  return googleCredentials.getAccessToken().getTokenValue();
}
Messaging.java

Una volta scaduto il token di accesso, il metodo di aggiornamento del token viene chiamato automaticamente per recuperare un token di accesso aggiornato.

Per autorizzare l'accesso a FCM, richiedi l'ambito https://www.googleapis.com/auth/firebase.messaging.

Per aggiungere il token di accesso a un'intestazione della richiesta HTTP:

Aggiungi il token come valore dell'intestazione Authorization nel formato Authorization: Bearer <access_token>:

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}
messaging.py

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;
FirebaseMessagingSnippets.java

Aggiornare il payload delle richieste di invio

FCM HTTP v1 introduce una modifica significativa nella strutturazione del payload del messaggio JSON. Queste modifiche garantiscono principalmente la corretta gestione dei messaggi quando vengono ricevuti su piattaforme client diverse. Inoltre, ti offrono maggiore flessibilità per personalizzare o "ignorare" i campi dei messaggi per piattaforma.

Oltre a esaminare gli esempi in questa sezione, consulta Personalizzare un messaggio su più piattaforme ed esamina il riferimento API per acquisire familiarità con HTTP v1.

Esempio: messaggio di notifica semplice

Ecco un confronto di un payload di notifica molto semplice, contenente solo i campi title, body e data, che mostra le differenze fondamentali tra i payload legacy e HTTP v1.

Prima

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

Dopo

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

Esempio: dati JSON nidificati

A differenza dell'API di messaggistica legacy, l'API HTTP v1 non supporta i valori JSON nidificati nel campo data. È necessaria una conversione da JSON a stringa.

Prima

{
  ...
  "data": {
    "keysandvalues": {"key1": "value1", "key2": 123}
  }
}

Dopo

{
  "message": {
   ...
    "data": {
      "keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
    }
  }
}

Esempio: targeting di più piattaforme

Per attivare il targeting su più piattaforme, l'API precedente eseguiva override nel backend. Al contrario, HTTP v1 fornisce blocchi di chiavi specifici per la piattaforma che rendono esplicite e visibili allo sviluppatore eventuali differenze tra le piattaforme. Ciò ti consente di scegliere come target più piattaforme sempre con una sola richiesta, come mostrato nell'esempio seguente.

Prima

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

Dopo

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Esempio: personalizzazione con override della piattaforma

Oltre a semplificare il targeting multipiattaforma dei messaggi, l'API HTTP v1 offre la flessibilità di personalizzare i messaggi per piattaforma.

Prima

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

Dopo

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Esempio: targeting di dispositivi specifici

Per scegliere come target dispositivi specifici con l'API HTTP v1, fornisci il token di registrazione attuale del dispositivo nella chiave token anziché nella chiave to.

Prima

  { "notification": {
      "body": "This is an FCM notification message!",
      "title": "FCM Message"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }

Dopo

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

Per ulteriori esempi e informazioni sull'API HTTP v1 di FCM, consulta quanto segue:

• Indicazioni su come creare richieste di invio del server delle app con l'API HTTP v1. Tutti gli snippet "REST" utilizzano l'API v1, se non diversamente specificato.

• Il blog di Firebase.