Inizia a utilizzare Firebase Cloud Messaging nelle app per piattaforme Apple

Seleziona la piattaforma:

iOS+ Android Web Flutter Unity C++

Questa guida descrive come iniziare a utilizzare Firebase Cloud Messaging nelle app client della tua piattaforma Apple (come iOS) in modo da poter inviare messaggi in modo affidabile.

Per le app client Apple, puoi ricevere payload di notifiche e dati fino a 4096 byte tramite l'interfaccia APN Firebase Cloud Messaging.

Per scrivere il codice client in Objective-C o Swift, ti consigliamo di utilizzare l'API FIRMessaging. L'esempio di guida rapida fornisce un codice campione per entrambi i linguaggi.

Prima di iniziare, aggiungi Firebase al tuo progetto Apple.

Swizzling del metodo in Firebase Cloud Messaging

L'SDK FCM esegue lo swizzling del metodo in due aree chiave: la mappatura del token APN all'ID installazione di Firebase o al token di registrazione FCM e l'acquisizione dei dati di analisi durante la gestione dei callback dei messaggi downstream. Gli sviluppatori che preferiscono non utilizzare lo swizzling possono disattivarlo aggiungendo il flag FirebaseAppDelegateProxyEnabled nel file Info.plist dell'app e impostandolo sul valore booleano NO. Le sezioni pertinenti delle guide forniscono esempi di codice, sia con che senza lo swizzling del metodo attivato.

Importante: con l'SDK Firebase Unity su iOS, non disattivare lo swizzling del metodo. Lo swizzling è richiesto dall'SDK e, senza di esso, le funzionalità chiave di Firebase, come la gestione della registrazione di FCM, non funzionano correttamente.

Carica la chiave di autenticazione del servizio APN

Carica la chiave di autenticazione del servizio APN su Firebase. Se non hai ancora una chiave di autenticazione APN, assicurati di crearne una nell'Apple Developer Member Center.

1. Nella console Firebase, vai a Impostazioni > Generali. Poi, fai clic sulla scheda Cloud Messaging.
2. In Chiave di autenticazione APN in Configurazione app per iOS, fai clic su Carica per caricare la chiave di autenticazione di sviluppo o la chiave di autenticazione di produzione o entrambe. È obbligatorio indicarne almeno uno.
3. Vai alla posizione in cui hai salvato la chiave, selezionala e fai clic su Apri. Aggiungi l'ID chiave per la chiave (disponibile nel Member Center di Apple Developer) e fai clic su Carica.

Registrati per le notifiche remote

All'avvio o nel punto desiderato del flusso dell'applicazione, registra la tua app per le notifiche remote. Chiama registerForRemoteNotifications come mostrato:

Nota: le app SwiftUI devono utilizzare i wrapper delle proprietà UIApplicationDelegateAdaptor o NSApplicationDelegateAdaptor per fornire un tipo corrispondente al protocollo del delegato dell'app appropriato.

Swift

UNUserNotificationCenter.current().delegate = self

let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
UNUserNotificationCenter.current().requestAuthorization(
  options: authOptions,
  completionHandler: { _, _ in }
)

application.registerForRemoteNotifications()
MigratedSnippets.swift

Objective-C

[UNUserNotificationCenter currentNotificationCenter].delegate = self;
UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert |
    UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
[[UNUserNotificationCenter currentNotificationCenter]
    requestAuthorizationWithOptions:authOptions
    completionHandler:^(BOOL granted, NSError * _Nullable error) {
      // ...
    }];

[application registerForRemoteNotifications];
ObjCMigratedSnippets.m

Devi assegnare la proprietà delegate di UNUserNotificationCenter e la proprietà delegate di FIRMessaging. Ad esempio, in un'app per iOS, assegnalo nel metodo applicationWillFinishLaunchingWithOptions: o applicationDidFinishLaunchingWithOptions: del delegato dell'app.

Accedi all'ID di installazione Firebase

Suggerimento: consulta le best practice per la gestione delle registrazioni FCM per suggerimenti sulla gestione delle registrazioni.

Le app che utilizzano ancora le API Instance ID ritirate per la gestione della registrazione devono aggiornare tutta la logica di registrazione per utilizzare le API FCM descritte qui.

Per impostazione predefinita, l'SDK FCM registra l'istanza dell'app con FCM e restituisce un ID installazione di Firebase (FID) per l'istanza dell'app client all'avvio dell'app. Analogamente al token del dispositivo APN, questo FID ti consente di inviare notifiche mirate a qualsiasi istanza specifica della tua app.

Nello stesso modo in cui le piattaforme Apple in genere forniscono un token del dispositivo APN all'avvio dell'app, FCM fornisce un FID per il targeting delle notifiche. L'SDK FCM fornisce l'ID istanza Firebase utilizzando il metodo messaging:didReceiveRegistration: di FIRMessagingDelegate, monitora automaticamente le modifiche all'ID istanza Firebase e richiama il metodo con un nuovo ID istanza Firebase quando viene rilevata una modifica. Ti consigliamo di recuperare e caricare regolarmente l'ID istanza Firebase perché l'ID istanza Firebase può ruotare dopo l'avvio iniziale.

Per informazioni dettagliate su quando vengono riemessi i FID e su come monitorarli manualmente, consulta Monitora il ciclo di vita dell'ID di installazione Firebase.

Abilita la registrazione utilizzando l'ID di installazione Firebase

Per attivare la registrazione dell'istanza dell'app con FCM utilizzando l' ID di installazione Firebase (FID), aggiungi il seguente flag dei metadati al file Info.plist, non al file GoogleService-Info.plist:

FirebaseMessagingInstallationIdEnabled = YES

Imposta il delegato per i messaggi

Per ricevere gli ID istanza Firebase, implementa il protocollo del delegato di messaggistica e imposta la proprietà delegate di FIRMessaging dopo aver chiamato [FIRApp configure]. Ad esempio, se il delegato dell'applicazione è conforme al protocollo del delegato di messaggistica, puoi impostare il delegato su application:didFinishLaunchingWithOptions: su se stesso.

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

Implementa il metodo didReceiveRegistration

Le istanze dell'app vengono scelte come target utilizzando l'ID istanza Firebase una volta completata la registrazione. Per ricevere l'ID istanza Firebase al momento della registrazione, implementa il metodo messaging:didReceiveRegistration:. Questo metodo viene in genere richiamato una volta per ogni avvio dell'app con l'ID istanza Firebase. Quando viene chiamato questo metodo, puoi eseguire le seguenti azioni:

• Se non hai inviato il FID al tuo server o lo hai inviato di recente, invialo al server dell'applicazione.
• Se l'abbonamento è nuovo o l'utente ha reinstallato l'app, iscrivi l'ID istanza Firebase agli argomenti.

Swift

func messaging(_ messaging: Messaging, didReceiveRegistration installationId: String?) {
  print("Firebase Installation ID: \(String(describing: installationId))")
  // Note: This callback is fired at each app startup.

  if let installationId = installationId {
    // Send the Firebase Installation ID to your app server.
    sendRegistrationToServer(installationId)
  }
}
    

Objective-C

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistration:(nullable NSString *)installationId {
  NSLog(@"Firebase Installation ID: %@", installationId);
  // Note: This callback is fired at each app startup.

  if (installationId != nil) {
    // Send the Firebase Installation ID to your app server.
    [self sendRegistrationToServer:installationId];
  }
}
    

Registra manualmente quando l'inizializzazione automatica è disattivata

Se hai disattivato l'inizializzazione automatica, l'SDK FCM non registrerà automaticamente l'istanza dell'app con FCM all'avvio dell'app. Devi chiamare register all'avvio dell'app per attivare la registrazione e l'invio del FID tramite il metodo messaging:didReceiveRegistration::

Swift

// Trigger manual registration if auto-initialization is turned off.
Messaging.messaging().register { error in
    if let error = error {
        // Handle the error
        print("Failed registering: \(error)")
        return
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    print("Successfully registered.")
}
    

Objective-C

// Trigger manual registration if auto-initialization is turned off.
[[FIRMessaging messaging] registerWithCompletion:^(NSError * _Nullable error) {
    if (error) {
        // Handle the error
        NSLog(@"Failed registering: %@", error);
        return;
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    NSLog(@"Successfully registered.");
}];
    

Swizzling disattivato: mappatura del token APN e del FID

Se hai disattivato lo swizzling del metodo o stai creando un'app SwiftUI, devi mappare esplicitamente il token APN agli ID installazione di Firebase (FID). Implementa il metodo application(_:didRegisterForRemoteNotificationsWithDeviceToken:) per recuperare il token APN, quindi imposta la proprietà apnsToken di Messaging:

Swift

func application(application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Messaging.messaging().apnsToken = deviceToken
}

Objective-C

// With "FirebaseAppDelegateProxyEnabled": NO
- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [FIRMessaging messaging].APNSToken = deviceToken;
}

Una volta registrato l'ID istanza Firebase, puoi accedervi e ascoltare gli eventi di aggiornamento utilizzando gli stessi metodi di quando lo swizzling è attivo.

Accedi al token di registrazione (deprecato)

Attenzione: questa funzionalità è deprecata. Utilizza gli ID installazione di Firebase, poiché questo metodo verrà rimosso in una release futura.

Suggerimento: consulta le best practice per la gestione della registrazione FCM per suggerimenti sulla gestione delle registrazioni.

Per impostazione predefinita, l'SDK FCM genera un token di registrazione per l'istanza dell'app client all'avvio dell'app. Analogamente al token del dispositivo APN, questo token ti consente di inviare notifiche mirate a qualsiasi istanza specifica della tua app.

Allo stesso modo in cui le piattaforme Apple in genere forniscono un token del dispositivo APN all'avvio dell'app, FCM fornisce un token di registrazione tramite il metodo messaging:didReceiveRegistrationToken: di FIRMessagingDelegate. L'SDK FCM recupera un token nuovo o esistente durante l'avvio iniziale dell'app e ogni volta che il token viene aggiornato o invalidato. In tutti i casi, l'SDK FCM chiama messaging:didReceiveRegistrationToken: con un token valido.

Le app che utilizzano ancora le API Instance ID ritirate per la gestione della registrazione devono aggiornare tutta la logica di registrazione per utilizzare le API FCM descritte qui.

Il token di registrazione potrebbe cambiare quando:

• L'app viene ripristinata su un nuovo dispositivo
• L'utente disinstalla/reinstalla l'app
• L'utente cancella i dati dell'app.

Imposta il delegato per i messaggi

Per ricevere i token di registrazione, implementa il protocollo del delegato di messaggistica e imposta la proprietà delegate di FIRMessaging dopo aver chiamato [FIRApp configure]. Ad esempio, se il delegato dell'applicazione è conforme al protocollo del delegato di messaggistica, puoi impostare il delegato su application:didFinishLaunchingWithOptions: su se stesso.

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

Recupero del token di registrazione corrente

I token di registrazione vengono inviati tramite il metodo messaging:didReceiveRegistrationToken:. Questo metodo viene chiamato in genere una volta per ogni avvio dell'app con il token di registrazione. Quando viene chiamato questo metodo, è il momento ideale per:

• Se il token di registrazione è nuovo, invialo al server dell'applicazione.
• Iscrivi il token di registrazione agli argomenti. Questo è necessario solo per i nuovi abbonamenti o per le situazioni in cui l'utente ha reinstallato l'app.

Puoi recuperare il token direttamente utilizzando token(completion:). Se il recupero del token non va a buon fine, viene fornito un errore non nullo.

Swift

Messaging.messaging().token { token, error in
  if let error = error {
    print("Error fetching remote FCM registration token: \(error)")
  } else if let token = token {
    print("Remote instance ID token: \(token)")
  }
}

Objective-C

[[FIRMessaging messaging] tokenWithCompletion:^(NSString * _Nullable token, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error fetching the remote FCM registration token: %@", error);
  } else {
    NSLog(@"Remote FCM registration token: %@", token);
    NSString* message =
      [NSString stringWithFormat:@"FCM registration token: %@", token];
    // display message
    NSLog(@"%@", message);
  }
}];

Puoi utilizzare questo metodo in qualsiasi momento per accedere al token anziché archiviarlo.

Monitora l'aggiornamento dei token

Per ricevere una notifica ogni volta che il token viene aggiornato, fornisci un delegato conforme al protocollo del delegato di messaggistica. L'esempio seguente registra il delegato e aggiunge il metodo delegato appropriato:

Swift

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
  print("Firebase registration token: \(String(describing: fcmToken))")
  // TODO: If necessary send token to application server.
  // Note: This callback is fired at each app startup and whenever a new token is generated.
}
MigratedSnippets.swift

Objective-C

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistrationToken:(NSString *)fcmToken {
    NSLog(@"FCM registration token: %@", fcmToken);
    // Notify about received token.
    NSDictionary *dataDict = [NSDictionary dictionaryWithObject:fcmToken forKey:@"token"];
    [[NSNotificationCenter defaultCenter] postNotificationName:
     @"FCMToken" object:nil userInfo:dataDict];
    // TODO: If necessary send token to application server.
    // Note: This callback is fired at each app startup and whenever a new token is generated.
}
ObjCMigratedSnippets.m

In alternativa, puoi ascoltare un NSNotification denominato kFIRMessagingRegistrationTokenRefreshNotification anziché fornire un metodo delegato. La proprietà token ha sempre il valore del token corrente.

Swizzling disattivato: mappatura del token APN e del token di registrazione

Se hai disattivato lo swizzling del metodo o stai creando un'app SwiftUI, devi mappare esplicitamente il token APN al token di registrazione FCM. Implementa il metodo application(_:didRegisterForRemoteNotificationsWithDeviceToken:) per recuperare il token APN, quindi imposta la proprietà apnsToken di Messaging:

Swift

func application(application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Messaging.messaging().apnsToken = deviceToken
}

Objective-C

// With "FirebaseAppDelegateProxyEnabled": NO
- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [FIRMessaging messaging].APNSToken = deviceToken;
}

Dopo aver generato il token di registrazione FCM, puoi accedervi e ascoltare gli eventi di aggiornamento utilizzando gli stessi metodi dello swizzling abilitato.

Impedisci l'inizializzazione automatica

Quando viene generata una registrazione FCM, la libreria carica l'identificatore e i dati di configurazione su Firebase. Se vuoi prima ottenere un'attivazione esplicita dagli utenti, puoi impedire la registrazione automatica al momento della configurazione disattivando FCM. Per farlo, aggiungi un valore dei metadati a Info.plist (non a GoogleService-Info.plist):

FirebaseMessagingAutoInitEnabled = NO

Per riattivare FCM, puoi effettuare una chiamata di runtime:

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[FIRMessaging messaging].autoInitEnabled = YES;

Una volta impostato, questo valore viene mantenuto anche dopo il riavvio dell'app.

Configura l'estensione del servizio di notifica

Per inviare notifiche che includono immagini ai dispositivi Apple, devi aggiungere un'estensione del servizio di notifica. Questa estensione consente ai dispositivi di visualizzare le immagini pubblicate nel payload della notifica. Se non prevedi di inviare immagini nelle notifiche, puoi saltare questo passaggio.

Per aggiungere un'estensione di servizio, esegui le attività di configurazione richieste per modificare e presentare le notifiche in APN, quindi aggiungi l'API helper dell'estensione FCM in NotificationService.m. In particolare, anziché completare il callback con self.contentHandler(self.bestAttemptContent);, completalo con FIRMessaging extensionHelper come mostrato:

@interface NotificationService () <NSURLSessionDelegate>
@property(nonatomic) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property(nonatomic) UNMutableNotificationContent *bestAttemptContent;
@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
self.bestAttemptContent = [request.content mutableCopy];

    // Modify the notification content here as you want
self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]",
self.bestAttemptContent.title];

  // Call FIRMessaging extension helper API.
  [[FIRMessaging extensionHelper] populateNotificationContent:self.bestAttemptContent
withContentHandler:contentHandler];

}
...

Invia un messaggio di notifica

1. Installa ed esegui l'app sul dispositivo di destinazione. Sui dispositivi Apple, accetta la richiesta di autorizzazione per ricevere notifiche remote.

2. Verifica che l'app sia in esecuzione in background sul dispositivo.

3. Nella console Firebase, vai a DevOps e coinvolgimento > Messaggistica

4. Creare una campagna.

   • Se è il tuo primo messaggio:

     1. Seleziona Crea la tua prima campagna.

     2. Seleziona Messaggi di notifica Firebase e poi Crea.

   • Se hai già creato campagne:

     1. Nella scheda Campagne, seleziona Nuova campagna.

     2. Fai clic su Notifiche.

5. Inserisci il testo del messaggio.

6. Seleziona Invia messaggio di prova nel riquadro a destra.

7. Nel campo Aggiungi un ID di installazione Firebase o un token di registrazione FCM, inserisci il token di registrazione.

8. Seleziona Test.

Dopo aver selezionato Test, il dispositivo client scelto come target, con l'app in background, dovrebbe ricevere la notifica.

Per informazioni sulla distribuzione dei messaggi alla tua app, vai alla dashboard DevOps e coinvolgimento > Messaggistica > Report nella console Firebase. Questa dashboard registra il numero di messaggi inviati e aperti su dispositivi Apple e Android, insieme ai dati relativi alle "impressioni" (notifiche visualizzate dagli utenti) per le app per Android.

Passaggi successivi

Dopo aver completato i passaggi di configurazione, ecco alcune opzioni per procedere con FCM per le piattaforme Apple:

• Invia messaggi ai dispositivi
• Ricevi messaggi in un'app Apple
• Invia messaggi agli argomenti