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

Выберите платформу:

iOS+ Android Web Flutter Unity C++

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

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

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

Прежде всего добавьте Firebase в проект Apple.

Подмена метода в Firebase Cloud Messaging

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

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

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

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

1. В консоли Firebase выберите Settings (Настройки) > General (Общие). Затем откройте вкладку Cloud Messaging.
2. В разделе APNs authentication key (Ключ аутентификации APNs) в разделе iOS app configuration (Конфигурация приложения iOS) нажмите Upload (Загрузить), чтобы загрузить ключ аутентификации для разработки, ключ аутентификации для производства или оба ключа. Обязательно заполните как минимум одно из этих полей.
3. Найдите сохраненный ключ, выберите его и нажмите Открыть. Добавьте идентификатор ключа (его можно найти в Apple Developer Member Center) и нажмите Upload (Загрузить).

Регистрация удаленных уведомлений

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

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

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

Необходимо назначить свойство delegate UNUserNotificationCenter и свойство delegate FIRMessaging. Например, в приложении для iOS назначьте его в методе applicationWillFinishLaunchingWithOptions: или applicationDidFinishLaunchingWithOptions: делегата приложения.

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

Совет. Ознакомьтесь с рекомендациями по управлению регистрацией FCM.

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

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

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

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

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

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

FirebaseMessagingInstallationIdEnabled = YES

Как настроить делегирование сообщений

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

Реализуйте метод didReceiveRegistration

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

• Если вы не отправляли 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 при запуске приложения. При запуске приложения необходимо вызвать register, чтобы запустить регистрацию и доставку FID с помощью метода 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.");
}];
    

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

Если вы отключили подмену метода или создаете приложение 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 вы можете получить к нему доступ и прослушивать события обновления, используя те же методы, что и при включенной подмене методов.

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

Внимание! Эта функция больше не поддерживается. Используйте идентификаторы установок Firebase, так как этот метод будет удален в будущих версиях.

Совет. Ознакомьтесь с рекомендациями по управлению регистрацией FCM.

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

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

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

Токен регистрации может измениться в следующих случаях:

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

Как настроить делегирование сообщений

Чтобы получать токены регистрации, реализуйте протокол делегата обмена сообщениями и задайте свойство delegate объекта FIRMessaging после вызова [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.
}
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

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

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

Если вы отключили подмену метода или создаете приложение 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 вы можете получить к нему доступ и прослушивать события обновления, используя те же методы, что и при включенной подмене.

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

Когда создается регистрация 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. Нажмите Проверить.

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

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

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

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

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