Configurar um app cliente do Firebase Cloud Messaging em plataformas da Apple

Para apps cliente da Apple, é possível receber payloads de notificação e dados de até 4.000 bytes pela interface APNs do Firebase Cloud Messaging.

Para escrever o código cliente em Objective-C ou Swift, recomendamos usar a API FIRMessaging. O exemplo do guia de início rápido disponibiliza um código de amostra dessas duas linguagens.

Para ativar o envio de notificações push por meio de APNs, é necessário ter:

• uma chave de autenticação de notificação push da Apple para sua conta de desenvolvedor dessa empresa. O Firebase Cloud Messaging usa esse token para enviar notificações push para o aplicativo identificado pelo ID do app;

• um perfil de provisionamento para esse ID do app com notificações push ativadas. Além disso, para testar seu app ainda em desenvolvimento, você precisará de um perfil de provisionamento para que seus dispositivos sejam autorizados a executar um app ainda não publicado na App Store.

Ambos são criados no Apple Developer Member Center.

Swizzling de métodos no Firebase Cloud Messaging

O SDK do FCM executa o Swizzling de métodos em duas áreas importantes: mapeamento do token de APNs para o token de registro do FCM e captura de dados de análise durante o processamento de chamada de retorno de mensagens downstream. Os desenvolvedores que preferem não usar o Swizzling podem desativá-lo adicionando a sinalização FirebaseAppDelegateProxyEnabled no arquivo Info.plist do app e defini-lo como NO (valor booleano). As áreas relevantes dos guias exibem exemplos de código, seja com o método Swizzling ativado ou não.

Adicionar o Firebase ao projeto da Apple

Esta seção aborda tarefas que você talvez tenha realizado se já ativou outros elementos do Firebase para o app. Especificamente para o FCM, você precisa fazer upload da chave de autenticação dos APNs e inscrever-se para receber notificações remotas.

Pré-requisitos

• Instale o seguinte:

  • Xcode 12.5 ou posterior

• Verifique se o projeto atende a estes requisitos:

  • O projeto precisa segmentar estas versões da plataforma ou versões mais recentes:
    • iOS 10
    • macOS 10.12
    • tvOS 12
    • watchOS 6

• Configurar um dispositivo Apple físico para executar o app e concluir estas tarefas:

  • Consiga uma chave de autenticação de notificação push da Apple para sua conta do Apple Developer.
  • Ativar as notificações push no Xcode em App > Capabilities.

• Fazer login no Firebase usando a conta do Google.

Se você ainda não tem um projeto do Xcode e quiser testar um produto do Firebase, faça o download de uma das nossas amostras de início rápido.

Criar um projeto do Firebase

Antes de adicionar o Firebase ao seu app da Apple, crie um projeto do Firebase para conectá-lo ao app. Acesse Noções básicas sobre projetos do Firebase para saber mais.

Registrar o app no Firebase

Depois de criar um projeto do Firebase, adicione seu app da Apple a ele.

Consulte Noções básicas sobre projetos do Firebase para ver práticas recomendadas e informações sobre como adicionar apps a um projeto do Firebase, incluindo como lidar com diversas variantes de build.

1. Acesse o Console do Firebase.

2. No centro da página de visão geral do projeto, clique no ícone iOS+ para iniciar o fluxo de trabalho de configuração.

   Se você já adicionou um app ao seu projeto do Firebase, clique em Adicionar app para exibir as opções da plataforma.

3. Insira o ID do pacote do seu app no campo ID do pacote.

   O que é um ID do pacote e onde ele pode ser encontrado?

   • Um ID de pacote identifica exclusivamente um aplicativo no ecossistema da Apple.

   • Encontre o ID do pacote: abra o projeto no Xcode, selecione o app de nível superior no navegador do projeto e escolha a guia Geral.

     O valor do campo Identificador do pacote é o ID do pacote (por exemplo, com.yourcompany.yourproject).

   • Saiba que o valor do ID do pacote diferencia maiúsculas de minúsculas e não pode ser alterado no app Firebase depois de ser registrado no projeto.

4. (Opcional) Insira outras informações do aplicativo: apelido do aplicativo e ID da App Store.

   Como o apelido do app e o ID da App Store são usados no Firebase?

   • Apelido do app: um identificador interno de conveniência que só é visível para você no Console do Firebase

   • ID da App Store: usado pelo Firebase Dynamic Links a fim de redirecionar usuários para a página da App Store e pelo Google Analytics para importar eventos de conversão ao Google Ads. Caso seu app ainda não tenha um ID da App Store, adicione o ID posteriormente nas suas configurações do projeto.

5. Clique em Registrar app.

Adicionar um arquivo de configuração do Firebase

1. Clique em Fazer o download do GoogleService-Info.plist para solicitar o arquivo de configuração das plataformas Apple do Firebase (GoogleService-Info.plist).

   O que é preciso saber sobre esse arquivo de configuração?

   • O arquivo de configuração do Firebase contém identificadores exclusivos, mas não secretos, para seu projeto. Para saber mais sobre esse arquivo de configuração, acesse Noções básicas sobre projetos do Firebase.

   • É possível fazer o download do arquivo de configuração do Firebase novamente a qualquer momento.

   • Verifique se caracteres adicionais, como (2), não foram adicionados ao final do nome do arquivo de configuração.

2. Mova o arquivo de configuração para a raiz do seu projeto XCode. Se solicitado, selecione adicionar o arquivo de configuração a todos os destinos.

Se o projeto tiver vários IDs de pacotes, associe cada ID com um app registrado no Console do Firebase para que tenha o próprio arquivo GoogleService-Info.plist.

Adicionar SDKs do Firebase ao seu app

Use o Swift Package Manager para instalar e gerenciar as dependências do Firebase.

1. Com seu projeto do app aberto no Xcode, acesse File > Swift Packages > Add Package Dependency.
2. Quando solicitado, adicione o repositório do SDK do Firebase para as plataformas da Apple:

  https://github.com/firebase/firebase-ios-sdk
  

3. Escolha a biblioteca do Firebase Cloud Messaging.
4. Para uma experiência ideal com o Firebase Cloud Messaging, recomendamos ativar o Google Analytics no projeto do Firebase e adicionar o SDK do Firebase para Analytics ao seu app. Você pode selecionar a biblioteca com ou sem o recurso de coleta de IDFAs.
5. Quando terminar, o Xcode começará a resolver e fazer o download das dependências em segundo plano automaticamente.

Fazer upload da chave de autenticação de APNs

Faça upload da chave de autenticação de APNs para o Firebase. Se você ainda não tiver uma chave de autenticação de APNs, crie uma no Apple Developer Member Center.

1. No seu projeto do Console do Firebase, selecione o ícone de engrenagem, Configurações do projeto e a guia Cloud Messaging.

2. Acesse a Configuração do app para iOS. Em Chave de autenticação de APNs, clique no botão Fazer upload.

3. Navegue até o local onde você salvou a chave, selecione-a e clique em Abrir. Adicione o ID da chave, disponível na Apple Developer Member Center, e clique em Fazer upload.

Inicializar o Firebase no seu app

É necessário adicionar o código de inicialização do Firebase ao seu app. Importe o módulo do Firebase e configure uma instância compartilhada da seguinte maneira:

1. Importe o módulo do Firebase no UIApplicationDelegate:

   Swift

   import Firebase

   Objective-C

   @import Firebase;

2. Configure uma instância compartilhada do FirebaseApp, normalmente no método application:didFinishLaunchingWithOptions: do app.

   Swift

   // Use Firebase library to configure APIs
   FirebaseApp.configure()

   Objective-C

   // Use Firebase library to configure APIs
   [FIRApp configure];

Registrar o app para receber notificações remotas

if #available(iOS 10.0, *) {
  // For iOS 10 display notification (sent via APNS)
  UNUserNotificationCenter.current().delegate = self

  let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
  UNUserNotificationCenter.current().requestAuthorization(
    options: authOptions,
    completionHandler: { _, _ in }
  )
} else {
  let settings: UIUserNotificationSettings =
    UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
  application.registerUserNotificationSettings(settings)
}

application.registerForRemoteNotifications()
AppDelegate.swift

if ([UNUserNotificationCenter class] != nil) {
  // iOS 10 or later
  // For iOS 10 display notification (sent via APNS)
  [UNUserNotificationCenter currentNotificationCenter].delegate = self;
  UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert |
      UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
  [[UNUserNotificationCenter currentNotificationCenter]
      requestAuthorizationWithOptions:authOptions
      completionHandler:^(BOOL granted, NSError * _Nullable error) {
        // ...
      }];
} else {
  // iOS 10 notifications aren't available; fall back to iOS 8-9 notifications.
  UIUserNotificationType allNotificationTypes =
  (UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge);
  UIUserNotificationSettings *settings =
  [UIUserNotificationSettings settingsForTypes:allNotificationTypes categories:nil];
  [application registerUserNotificationSettings:settings];
}

[application registerForRemoteNotifications];
AppDelegate.m

Acessar o token de registro

Por padrão, o SDK do FCM gera um token de registro para a instância do app cliente na inicialização do seu app. Semelhante ao token do dispositivo de APNs, este token permite enviar notificações direcionadas a instâncias particulares do app.

Da mesma forma que as plataformas da Apple normalmente entregam um token de dispositivo de APNs do app ao iniciar o app, o FCM informa um token de registro usando o método messaging:didReceiveRegistrationToken: de FIRMessagingDelegate. O SDK do FCM recupera um token novo ou existente durante a inicialização do aplicativo e sempre que o token é atualizado ou invalidado. Em todos os casos, o SDK do FCM chama messaging:didReceiveRegistrationToken: com um token válido.

Esse token pode mudar quando:

• o app é restaurado em um novo dispositivo;
• o usuário desinstala/reinstala o app;
• o usuário limpa os dados do app.

Definir a delegação de mensagens

Para receber tokens de registro, implemente o protocolo de delegação de mensagens e defina a propriedade delegate do FIRMessaging depois de chamar [FIRApp configure]. Por exemplo, se o delegador do seu aplicativo estiver em conformidade com o protocolo de delegação de mensagens, você poderá configurá-lo como seu próprio delegador em application:didFinishLaunchingWithOptions:.

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

Como encontrar o token de registro atual

Os tokens de registro são enviados por meio do método messaging:didReceiveRegistrationToken:. Normalmente, esse método é chamado uma vez a cada inicialização do app com um token de registro. Depois dessa chamada é o momento ideal para:

• se o token de registro for novo, enviá-lo para o servidor de aplicativos;
• inscrever o token de registro em tópicos. Isso é necessário apenas para novas assinaturas ou em situações em que o usuário tenha reinstalado o app.

É possível recuperar o token diretamente usando token(completion:). Um erro não nulo será fornecido se a recuperação do token falhar.

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

[[FIRMessaging messaging] tokenWithCompletion:^(NSString *token, NSError *error) {
  if (error != nil) {
    NSLog(@"Error getting FCM registration token: %@", error);
  } else {
    NSLog(@"FCM registration token: %@", token);
    self.fcmRegTokenMessage.text = token;
  }
}];

Você pode usar esse método a qualquer momento para acessar o token em vez de armazená-lo.

Monitorar a atualização do token

Se você quiser receber notificações sempre que o token for atualizado, forneça um delegador em conformidade com o protocolo de delegação de mensagens. O exemplo a seguir registra o delegador e adiciona o método apropriado:

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
  print("Firebase registration token: \(String(describing: fcmToken))")

  let dataDict: [String: String] = ["token": fcmToken ?? ""]
  NotificationCenter.default.post(
    name: Notification.Name("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.
}
AppDelegate.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.
}
AppDelegate.m

Como alternativa, você pode detectar uma NSNotification denominada kFIRMessagingRegistrationTokenRefreshNotification em vez de fornecer um método delegado. A propriedade do token tem sempre o valor do token atual.

Swizzling desativado: como mapear o token de APNs e de registro

Se você desativou o Swizzling de métodos, precisará mapear explicitamente o token de APNs ao token de registro do FCM. Modifique os métodos didRegisterForRemoteNotificationsWithDeviceToken para recuperar o token de APNs e defina a propriedade de APNSToken do FIRMessaging:

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

Depois que o token de registro do FCM for gerado, você poderá acessá-lo e detectar eventos de atualização usando os mesmos métodos como se o Swizzling estivesse ativado.

Impedir a inicialização automática

Quando um token de registro do FCM é gerado, a biblioteca faz upload dos dados de configuração e do identificador para o Firebase. Se você quiser receber uma autorização explícita dos usuários antes disso, é possível impedir a geração de tokens no momento da configuração. Para isso, basta desativar o FCM. Para isso, adicione um valor de metadados a seu Info.plist (não seu GoogleService-Info.plist):

FirebaseMessagingAutoInitEnabled = NO

Para reativar o FCM, é possível fazer uma chamada de tempo de execução:

Messaging.messaging().autoInitEnabled = true

[FIRMessaging messaging].autoInitEnabled = YES;

Depois de definido, esse valor persiste às reinicializações do app.

Próximas etapas

Depois de configurar o cliente Apple, estará tudo pronto para adicionar o gerenciamento de mensagens e outros comportamentos mais avançados ao app. Veja estes guias para mais informações:

• Receber mensagens em um app da Apple
• Enviar mensagens de tópico
• Enviar a grupos de dispositivos