Начало работы с Firebase Cloud Messaging в приложениях для платформы Apple

В этом руководстве рассказывается, как начать работу с Firebase Cloud Messaging в клиентских приложениях для платформы Apple (например, iOS), чтобы надежно отправлять сообщения.

Для клиентских приложений Apple вы можете получать полезную нагрузку уведомлений и данных размером до 4096 байт через интерфейс Firebase Cloud Messaging APNs.

Чтобы написать код клиента на Objective-C или Swift, рекомендуем использовать API FIRMessaging. В примере для быстрого начала работы приведены образцы кода на обоих языках.

Прежде чем начать, добавьте Firebase в проект для Apple.

Метод swizzling в Firebase Cloud Messaging

SDK FCM выполняет подмену метода в двух основных областях: сопоставление токена APNs с идентификатором установки Firebase или токеном регистрации FCM и сбор аналитических данных во время обработки обратного вызова нисходящего сообщения. Разработчики, которые не хотят использовать подмену, могут отключить ее, добавив флаг FirebaseAppDelegateProxyEnabled в файл Info.plist приложения и задав для него логическое значение NO. В соответствующих разделах руководств приведены примеры кода как с включенной подменой метода, так и без нее.

Загрузите ключ аутентификации APNs

Загрузите ключ аутентификации APNs в Firebase. Если у вас ещё нет ключа аутентификации APNs, создайте его в Apple Developer Member Center.

1. В консоли Firebase выберите settings Настройки > Общие. Затем нажмите на вкладку Обмен сообщениями в облаке.
2. В разделе Конфигурация приложения для iOS в поле Ключ аутентификации APNs нажмите Загрузить, чтобы загрузить ключ аутентификации для разработки, ключ аутентификации для производства или оба ключа. Обязательно заполните как минимум одно из этих полей.
3. Перейдите к месту, где сохранен ключ, выберите его и нажмите Открыть. Добавьте идентификатор ключа (его можно найти в Центре участников Apple Developer) и нажмите Загрузить.

Как зарегистрировать удаленные уведомления

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

Как получить доступ к идентификатору установки Firebase

По умолчанию SDK FCM регистрирует экземпляр приложения в FCM и возвращает идентификатор установки Firebase (FID) для экземпляра клиентского приложения при его запуске. Как и токен устройства APNs, этот идентификатор позволяет отправлять целевые уведомления в определенный экземпляр приложения.

Подобно тому, как платформы Apple обычно предоставляют токен устройства APNs при запуске приложения, FCM предоставляет FID для таргетинга уведомлений. SDK FCM передает FID с помощью метода messaging:didReceiveRegistration: класса FIRMessagingDelegate, автоматически отслеживает изменения FID и вызывает метод с новым FID при обнаружении изменений. Мы рекомендуем регулярно получать и загружать FID, поскольку он может меняться после первоначального запуска.

Включить регистрацию с помощью идентификатора установки Firebase

Чтобы включить регистрацию экземпляра приложения в FCM с помощью идентификатора установки Firebase (FID), добавьте следующий флаг метаданных в файл Info.plist, а не в файл GoogleService-Info.plist:

FirebaseMessagingInstallationIdEnabled = YES

Как назначить представителя для обмена сообщениями

Чтобы получать идентификаторы установки Firebase, реализуйте протокол делегата обмена сообщениями и задайте свойство delegate объекта FIRMessaging после вызова [FIRApp configure]. Например, если делегат вашего приложения соответствует протоколу делегата для обмена сообщениями, вы можете задать делегата для application:didFinishLaunchingWithOptions: самому себе.

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

Как реализовать метод didReceiveRegistration

После завершения регистрации таргетинг на экземпляры приложения выполняется с помощью FID. Чтобы получить FID при регистрации, реализуйте метод messaging:didReceiveRegistration:. Обычно этот метод вызывается один раз при запуске приложения с FID. При вызове этого метода вы можете выполнить следующие действия:

• Если вы ещё не отправили идентификатор экземпляра установки на сервер или отправили его недавно, сделайте это.
• Если подписка новая или пользователь переустановил приложение, подпишите 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];
  }
}
    

Как зарегистрироваться вручную, если автоинициализация отключена

Если вы отключили автоматическую инициализацию, SDK FCM не будет автоматически регистрировать экземпляр приложения в FCM при запуске приложения. При запуске приложения необходимо вызвать register, чтобы запустить регистрацию и доставку FID с помощью метода messaging:didReceiveRegistration::

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

Подмена отключена: сопоставление токена APNs и FID

Если вы отключили подмену метода или создаете приложение SwiftUI, вам нужно явно сопоставить токен APNs с идентификаторами установки Firebase (FID). Реализуйте метод application(_:didRegisterForRemoteNotificationsWithDeviceToken:), чтобы получить токен APNs, а затем задайте свойство apnsToken объекта Messaging:

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

После регистрации FID вы можете получить к нему доступ и отслеживать события обновления с помощью тех же методов, что и при включенном перехвате.

Как получить доступ к токену регистрации (устарело)

По умолчанию при запуске приложения SDK FCM генерирует токен регистрации для экземпляра клиентского приложения. Как и токен устройства APNs, этот токен позволяет отправлять таргетированные уведомления в любой экземпляр приложения.

Подобно тому, как платформы Apple обычно доставляют токен устройства APNs при запуске приложения, FCM предоставляет токен регистрации через метод messaging:didReceiveRegistrationToken: класса FIRMessagingDelegate. SDK FCM получает новый или существующий токен при первом запуске приложения, а также при обновлении или аннулировании токена. Во всех случаях FCM SDK вызывает messaging:didReceiveRegistrationToken: с действительным токеном.

Токен регистрации может измениться, если:

• Приложение восстановлено на новом устройстве.
• Пользователь удаляет и снова устанавливает приложение.
• Пользователь удаляет данные приложения.

Как назначить представителя для обмена сообщениями

Чтобы получать токены регистрации, реализуйте протокол делегирования сообщений и задайте свойство FIRMessaging delegate после вызова [FIRApp configure]. Например, если делегат вашего приложения соответствует протоколу делегата для обмена сообщениями, вы можете задать делегата для application:didFinishLaunchingWithOptions: самому себе.

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

Получение текущего токена регистрации

Токены регистрации передаются с помощью метода messaging:didReceiveRegistrationToken:. Обычно этот метод вызывается один раз при запуске приложения с токеном регистрации. При вызове этого метода рекомендуется:

• Если токен регистрации новый, отправьте его на сервер приложения.
• Подпишите токен регистрации на темы. Это необходимо только для новых подписок или в ситуациях, когда пользователь переустановил приложение.

Вы можете получить токен напрямую, используя метод token(completion:). Если получить токен не удалось, возвращается ненулевая ошибка.

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

Этот метод можно использовать в любое время, чтобы получить доступ к токену, а не хранить его.

Отслеживание обновления токенов

Чтобы получать уведомления об обновлении токена, предоставьте делегата, соответствующего протоколу делегата обмена сообщениями. В следующем примере регистрируется делегат и добавляется подходящий метод делегата:

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

Вместо метода делегата можно прослушивать объект NSNotification с именем kFIRMessagingRegistrationTokenRefreshNotification. Свойство token всегда содержит текущее значение токена.

Отключенная подмена: сопоставление токена APNs и токена регистрации

Если вы отключили подмену метода или создаете приложение SwiftUI, вам нужно явным образом сопоставить токен APNs с токеном регистрации FCM. Реализуйте метод application(_:didRegisterForRemoteNotificationsWithDeviceToken:), чтобы получить токен APNs, а затем задайте свойство apnsToken объекта Messaging:

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

После создания токена регистрации FCM вы можете получить к нему доступ и прослушивать события обновления, используя те же методы, что и при включенной подмене.

Как отключить автоматическую инициализацию

Когда создается регистрация FCM, библиотека загружает идентификатор и данные конфигурации в Firebase. Если вы хотите сначала получить явное согласие пользователей, то можете запретить автоматическую регистрацию во время настройки, отключив FCM. Для этого добавьте значение метаданных в Info.plist (не в GoogleService-Info.plist):

FirebaseMessagingAutoInitEnabled = NO

Чтобы снова включить FCM, можно выполнить вызов во время выполнения:

Messaging.messaging().autoInitEnabled = true

[FIRMessaging messaging].autoInitEnabled = YES;

После установки это значение сохраняется при перезапуске приложения.

Как настроить расширение службы уведомлений

Чтобы отправлять уведомления с изображениями на устройства Apple, необходимо добавить расширение службы уведомлений. Это расширение позволяет устройствам показывать изображения, которые передаются в полезной нагрузке уведомления. Если вы не планируете отправлять изображения в уведомлениях, этот шаг можно пропустить.

Чтобы добавить расширение сервиса, выполните необходимые настройки для изменения и показа уведомлений в APNs, а затем добавьте вспомогательный API расширения FCM в NotificationService.m. В частности, вместо завершения обратного вызова с помощью self.contentHandler(self.bestAttemptContent); завершите его с помощью FIRMessaging extensionHelper, как показано ниже.

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

}
...

Как отправить уведомление

1. Установите и запустите приложение на целевом устройстве. На устройствах Apple примите запрос на разрешение получать удаленные уведомления.

2. Убедитесь, что приложение работает в фоновом режиме.

3. В консоли Firebase перейдите в раздел DevOps & Engagement (DevOps и взаимодействие) > Messaging (Обмен сообщениями).

4. Создать кампанию

   • Если это ваше первое сообщение:

     1. Выберите Создать первую кампанию.

     2. Выберите Уведомления Firebase и нажмите Создать.

   • Если у вас уже есть кампании:

     1. На вкладке Кампании выберите Новая кампания.

     2. Нажмите Уведомления.

5. Введите текст сообщения.

6. На панели справа выберите Отправить тестовое сообщение.

7. В поле Добавьте идентификатор установки Firebase или токен регистрации FCM введите токен регистрации.

8. Нажмите Проверить.

После того как вы нажмете Тестировать, целевое клиентское устройство с приложением, работающим в фоновом режиме, должно получить уведомление.

Чтобы узнать, как сообщения доставляются в ваше приложение, перейдите в раздел DevOps & Engagement (DevOps и вовлечение) > Messaging (Обмен сообщениями) > Reports (Отчеты) в консоли Firebase. На этой панели управления регистрируется количество сообщений, отправленных и открытых на устройствах Apple и Android, а также данные о показах (уведомлениях, увиденных пользователями) для приложений Android.

Дальнейшие действия

После того как вы выполните все действия по настройке, вы можете продолжить работу с FCM для платформ Apple. Вот несколько вариантов:

• Как отправлять сообщения на устройства
• Как получать сообщения в приложении Apple
• Как отправлять сообщения в темы