Erste Schritte mit Firebase Cloud Messaging in Apps für Apple-Plattformen

In diesem Leitfaden wird beschrieben, wie Sie Firebase Cloud Messaging in Ihren Client-Apps für Apple-Plattformen (z. B. iOS) einrichten, um Nachrichten zuverlässig zu senden.

Bei Apple-Client-Apps können Sie Benachrichtigungs- und Datennutzlasten von bis zu 4.096 Byte über die Firebase Cloud Messaging-APNs-Schnittstelle empfangen.

Wenn Sie Ihren Clientcode in Objective-C oder Swift schreiben möchten, empfehlen wir die Verwendung der FIRMessaging API. Das Kurzanleitungsbeispiel enthält Beispielcode für beide Sprachen.

Bevor Sie beginnen, fügen Sie Ihrem Apple-Projekt Firebase hinzu.

Method Swizzling in Firebase Cloud Messaging

Das FCM SDK führt Method Swizzling in zwei wichtigen Bereichen aus: Zuordnung Ihres APNs-Tokens zum Firebase-Installations-ID oder FCM-Registrierungstoken und Erfassung von Analysedaten während der Verarbeitung von Downstream-Nachrichten-Callbacks. Entwickler, die Swizzling nicht verwenden möchten, können es deaktivieren, indem sie das Flag FirebaseAppDelegateProxyEnabled in der Datei Info.plist der App hinzufügen und auf den booleschen Wert NO setzen. In den entsprechenden Abschnitten der Leitfäden finden Sie Codebeispiele mit und ohne aktiviertes Method Swizzling.

APNs-Authentifizierungsschlüssel hochladen

Laden Sie Ihren APNs-Authentifizierungsschlüssel in Firebase hoch. Wenn Sie noch keinen APNs-Authentifizierungsschlüssel haben, erstellen Sie einen im Apple Developer Member Center.

1. Rufen Sie in der Firebase Console die settings Einstellungen > Allgemein auf. Klicken Sie dann auf den Tab Cloud Messaging.
2. Klicken Sie unter iOS-App-Konfiguration bei APNs-Authentifizierungsschlüssel auf Hochladen, um den Entwicklungs-Authentifizierungsschlüssel, den Produktions-Authentifizierungsschlüssel oder beide hochzuladen. Mindestens eine Angabe ist erforderlich.
3. Suchen Sie den Speicherort, an dem Sie Ihren Schlüssel gespeichert haben, wählen Sie ihn aus und klicken Sie auf Öffnen. Fügen Sie die Schlüssel-ID für den Schlüssel hinzu (verfügbar im Apple Developer Member Center) und klicken Sie auf Hochladen.

Für Remote-Benachrichtigungen registrieren

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()
MigratedSnippets.swift

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

[application registerForRemoteNotifications];
ObjCMigratedSnippets.m

Auf die Firebase-Installations-ID zugreifen

Standardmäßig registriert das FCM SDK die App-Instanz bei FCM und gibt beim Start der App eine Firebase-Installations-ID (FID) für die Client-App-Instanz zurück. Ähnlich wie mit dem APNs-Gerätetoken können Sie mit dieser FID gezielte Benachrichtigungen an eine bestimmte Instanz Ihrer App senden.

Genauso wie Apple-Plattformen beim Start der App normalerweise ein APNs-Gerätetoken bereitstellen, stellt FCM eine FID für das Targeting von Benachrichtigungen bereit. Das FCM SDK liefert die FID mithilfe der messaging:didReceiveRegistration:-Methode des FIRMessagingDelegate, überwacht automatisch auf FID-Änderungen und ruft die Methode mit einer neuen FID auf, wenn eine Änderung erkannt wird. Wir empfehlen, die FID regelmäßig abzurufen und hochzuladen, da sie nach dem ersten Start rotieren kann.

Registrierung mit Firebase-Installations-ID aktivieren

Wenn Sie die Registrierung Ihrer App-Instanz bei FCM mit der Firebase-Installations-ID (FID) aktivieren möchten, fügen Sie der Datei Info.plist (nicht der Datei GoogleService-Info.plist) das folgende Metadaten-Flag hinzu:

FirebaseMessagingInstallationIdEnabled = YES

Messaging-Delegat festlegen

Wenn Sie FIDs erhalten möchten, implementieren Sie das Messaging-Delegatprotokoll und legen Sie nach dem Aufruf von [FIRApp configure] das Attribut delegate von FIRMessaging fest. Wenn Ihr Anwendungs-Delegate beispielsweise dem Messaging-Delegate-Protokoll entspricht, können Sie den Delegate für application:didFinishLaunchingWithOptions: auf sich selbst festlegen.

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

Methode didReceiveRegistration implementieren

App-Instanzen werden nach Abschluss der Registrierung über die FID angesprochen. Wenn Sie die FID bei der Registrierung erhalten möchten, implementieren Sie die Methode messaging:didReceiveRegistration:. Diese Methode wird normalerweise einmal pro App-Start mit der FID aufgerufen. Wenn diese Methode aufgerufen wird, können Sie die folgenden Aktionen ausführen:

• Wenn Sie die FID noch nicht an Ihren Server gesendet haben oder die FID vor Kurzem gesendet haben, senden Sie sie an Ihren Anwendungsserver.
• Wenn das Abo neu ist oder der Nutzer die App neu installiert hat, abonnieren Sie die Themen für die FID.

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)
  }
}
    

- (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];
  }
}
    

Manuell registrieren, wenn die automatische Initialisierung deaktiviert ist

Wenn Sie die automatische Initialisierung deaktiviert haben, registriert das FCM SDK die App-Instanz beim Start der App nicht automatisch bei FCM. Sie müssen beim Start der App register aufrufen, um die Registrierung und die FID-Bereitstellung über die Methode messaging:didReceiveRegistration: auszulösen:

// 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.")
}
    

// 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 deaktiviert: APNs-Token und FID zuordnen

Wenn Sie Method Swizzling deaktiviert haben oder eine SwiftUI-App erstellen, müssen Sie Ihr APNs-Token explizit den Firebase-Installations-IDs (FID) zuordnen. Implementieren Sie die Methode application(_:didRegisterForRemoteNotificationsWithDeviceToken:), um das APNs-Token abzurufen, und legen Sie dann das Attribut apnsToken von Messaging fest:

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

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

Sobald die FID registriert ist, können Sie darauf zugreifen und auf Aktualisierungsereignisse warten. Verwenden Sie dazu dieselben Methoden wie bei aktiviertem Swizzling.

Auf das Registrierungstoken zugreifen (verworfen)

Standardmäßig generiert das FCM SDK beim Start der App ein Registrierungstoken für die Client-App-Instanz. Ähnlich wie mit dem APNs-Gerätetoken können Sie mit diesem Token gezielte Benachrichtigungen an eine bestimmte Instanz Ihrer App senden.

Genauso wie Apple-Plattformen beim App-Start normalerweise ein APNs-Gerätetoken bereitstellen, stellt FCM ein Registrierungstoken über die Methode messaging:didReceiveRegistrationToken: von FIRMessagingDelegate bereit. Das FCM SDK ruft beim ersten Start der App und immer dann, wenn das Token aktualisiert oder ungültig wird, ein neues oder vorhandenes Token ab. In allen Fällen ruft das FCM SDK messaging:didReceiveRegistrationToken: mit einem gültigen Token auf.

Das Registrierungstoken kann sich in folgenden Fällen ändern:

• Die App wird auf einem neuen Gerät wiederhergestellt.
• Der Nutzer deinstalliert die App und installiert sie neu.
• Der Nutzer löscht App-Daten.

Messaging-Delegat festlegen

Wenn Sie Registrierungstokens erhalten möchten, implementieren Sie das Messaging-Delegatprotokoll und legen Sie nach dem Aufruf von [FIRApp configure] das Attribut delegate von FIRMessaging fest. Wenn Ihr Anwendungs-Delegate beispielsweise dem Messaging-Delegate-Protokoll entspricht, können Sie den Delegate für application:didFinishLaunchingWithOptions: auf sich selbst festlegen.

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

Aktuelles Registrierungstoken wird abgerufen

Registrierungstokens werden über die Methode messaging:didReceiveRegistrationToken: bereitgestellt. Diese Methode wird im Allgemeinen einmal pro App-Start mit dem Registrierungstoken aufgerufen. Wenn diese Methode aufgerufen wird, ist das der ideale Zeitpunkt, um:

• Wenn das Registrierungstoken neu ist, senden Sie es an Ihren Anwendungsserver.
• Abonnieren Sie mit dem Registrierungstoken Themen. Dies ist nur für neue Abos oder für Situationen erforderlich, in denen der Nutzer die App neu installiert hat.

Sie können das Token direkt mit token(completion:) abrufen. Wenn der Tokenabruf fehlgeschlagen ist, wird ein Fehler ungleich null zurückgegeben.

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)")
  }
}

[[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);
  }
}];

Sie können diese Methode jederzeit verwenden, um auf das Token zuzugreifen, anstatt es zu speichern.

Tokenaktualisierung überwachen

Wenn Sie benachrichtigt werden möchten, sobald das Token aktualisiert wird, geben Sie einen Bevollmächtigten an, der dem Messaging-Bevollmächtigtenprotokoll entspricht. Im folgenden Beispiel wird der Delegate registriert und die entsprechende Delegate-Methode hinzugefügt:

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

- (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

Alternativ können Sie auf ein NSNotification mit dem Namen kFIRMessagingRegistrationTokenRefreshNotification warten, anstatt eine Delegatmethode anzugeben. Das Attribut „token“ hat immer den aktuellen Tokenwert.

Swizzling deaktiviert: APNs-Token und Registrierungstoken zuordnen

Wenn Sie Method Swizzling deaktiviert haben oder eine SwiftUI-App erstellen, müssen Sie Ihr APNs-Token explizit dem FCM-Registrierungstoken zuordnen. Implementieren Sie die Methode application(_:didRegisterForRemoteNotificationsWithDeviceToken:), um das APNs-Token abzurufen, und legen Sie dann das Attribut apnsToken von Messaging fest:

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

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

Nachdem das FCM-Registrierungstoken generiert wurde, können Sie darauf zugreifen und Aktualisierungsereignisse mit denselben Methoden wie bei aktiviertem Swizzling überwachen.

Automatische Initialisierung verhindern

Wenn eine FCM-Registrierung generiert wird, lädt die Bibliothek die Kennung und die Konfigurationsdaten in Firebase hoch. Wenn Sie zuerst eine explizite Einwilligung von Nutzern einholen möchten, können Sie die automatische Registrierung bei der Konfiguration verhindern, indem Sie FCM deaktivieren. Fügen Sie dazu einen Metadatenwert zu Info.plist (nicht zu GoogleService-Info.plist) hinzu:

FirebaseMessagingAutoInitEnabled = NO

Wenn Sie FCM wieder aktivieren möchten, können Sie einen Laufzeitaufruf ausführen:

Messaging.messaging().autoInitEnabled = true

[FIRMessaging messaging].autoInitEnabled = YES;

Dieser Wert bleibt nach dem Festlegen auch bei einem Neustart der App erhalten.

Erweiterung für den Benachrichtigungsdienst einrichten

Wenn Sie Benachrichtigungen mit Bildern an Apple-Geräte senden möchten, müssen Sie eine Erweiterung für den Benachrichtigungsdienst hinzufügen. Mit dieser Erweiterung können Geräte Bilder anzeigen, die in der Benachrichtigungsnutzlast bereitgestellt werden. Wenn Sie keine Bilder in Benachrichtigungen senden möchten, können Sie diesen Schritt überspringen.

Wenn Sie eine Diensterweiterung hinzufügen möchten, führen Sie die erforderlichen Einrichtungsschritte zum Ändern und Präsentieren von Benachrichtigungen in APNs aus und fügen Sie dann die FCM-Erweiterungs-Hilfs-API in NotificationService.m hinzu. Konkret wird der Callback nicht mit self.contentHandler(self.bestAttemptContent);, sondern mit FIRMessaging extensionHelper abgeschlossen:

@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];

}
...

Benachrichtigung senden

1. Installieren Sie die App auf dem Zielgerät und führen Sie sie aus. Akzeptieren Sie auf Apple-Geräten die Anfrage zur Berechtigung, Remote-Benachrichtigungen zu erhalten.

2. Prüfe, ob die App auf dem Gerät im Hintergrund ausgeführt wird.

3. Rufen Sie in der Firebase-Konsole DevOps & Engagement > Messaging auf.

4. Kampagne erstellen

   • Wenn dies Ihre erste Mitteilung ist:

     1. Wählen Sie Erste Kampagne erstellen aus.

     2. Wählen Sie Firebase-Benachrichtigungen und dann Erstellen aus.

   • Wenn Sie bereits Kampagnen erstellt haben:

     1. Wählen Sie auf dem Tab Kampagnen die Option Neue Kampagne aus.

     2. Klicken Sie auf Benachrichtigungen.

5. Geben Sie den Nachrichtentext ein.

6. Wählen Sie im rechten Bereich Testnachricht senden aus.

7. Geben Sie im Feld Firebase-Installations-ID oder FCM-Registrierungstoken hinzufügen Ihr Registrierungstoken ein.

8. Wählen Sie Testen aus.

Nachdem Sie Test ausgewählt haben, sollte das Ziel-Clientgerät die Benachrichtigung erhalten, während die App im Hintergrund ausgeführt wird.

Informationen zur Nachrichtenzustellung an Ihre App finden Sie in der Firebase-Konsole unter DevOps & Engagement > Messaging > Berichte-Dashboard. In diesem Dashboard wird die Anzahl der Nachrichten erfasst, die auf Apple- und Android-Geräten gesendet und geöffnet wurden. Außerdem werden Daten zu „Impressionen“ (von Nutzern gesehene Benachrichtigungen) für Android-Apps angezeigt.

Nächste Schritte

Nachdem Sie die Einrichtungsschritte abgeschlossen haben, haben Sie folgende Möglichkeiten, um mit FCM für Apple-Plattformen fortzufahren:

• Nachrichten an Geräte senden
• Nachrichten in einer Apple-App empfangen
• Nachrichten an Themen senden