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

Выберите платформу: iOS+ Android Веб Flutter Unity C++


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

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

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

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

Метод swizzling в Firebase Cloud Messaging

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

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

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

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

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

Зарегистрируйте приложение для получения удаленных уведомлений при запуске или в нужный момент его работы. Вызовите registerForRemoteNotifications, как показано ниже:

Swift

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()

Objective-C

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

[application registerForRemoteNotifications];

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

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

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

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

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

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

FirebaseMessagingInstallationIdEnabled = YES

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

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

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

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

  • Если вы ещё не отправили идентификатор экземпляра установки на сервер или отправили его недавно, сделайте это.
  • Если подписка новая или пользователь переустановил приложение, подпишите FID на темы.

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

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

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

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

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

Если вы отключили метод swizzling или создаете приложение SwiftUI, вам нужно явно сопоставить токен APNs с идентификаторами установки Firebase (FID). Реализуйте метод application(_:didRegisterForRemoteNotificationsWithDeviceToken:), чтобы получить токен APNs, а затем задайте свойство apnsToken объекта 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;
}

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

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

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

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

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

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

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

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

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

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

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

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

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

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

Как отслеживать обновление токена

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

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

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

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

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

Если вы отключили метод swizzling или создаете приложение SwiftUI, вам нужно будет явно сопоставить токен APNs с токеном регистрации FCM. Реализуйте метод application(_:didRegisterForRemoteNotificationsWithDeviceToken:), чтобы получить токен APNs, а затем задайте свойство apnsToken объекта 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;
}

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

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

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

FirebaseMessagingAutoInitEnabled = NO

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

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[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 и вовлеченность > Обмен сообщениями > Отчеты на панели управления Firebase. На этой панели управления регистрируется количество сообщений, отправленных и открытых на устройствах Apple и Android, а также данные о показах (уведомлениях, которые видели пользователи) для приложений Android.

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

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