Configurar um app cliente do Firebase Cloud Messaging no iOS

Para aplicativos cliente iOS, é 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 (em inglês) 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 seu projeto para iOS

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

• Instalação dos programas a seguir:

  • Xcode 12.2 ou posterior
  • CocoaPods 1.10.0 ou posterior

• Verifique se o projeto atende a estes requisitos:

  • Seu projeto precisa ser desenvolvido para iOS 10 ou versões posteriores.

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

  • Conseguir uma chave de autenticação de notificação push da Apple para a 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 app para iOS, é preciso criar um projeto do Firebase para então conectá-lo ao app. Visite Noções básicas sobre projetos do Firebase para saber mais.

Registrar seu app no Firebase

Depois de criar um projeto do Firebase, é possível adicionar o app para iOS 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 (plat_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 do iOS.

   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 iOS no Xcode, selecione o app de nível superior no navegador do projeto e selecione a guia Geral.

     O valor do campo Identificador do pacote é o ID do pacote do iOS (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 do Firebase para iOS 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 código 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 do Firebase para iOS (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 app

Recomendamos o uso do CocoaPods (em inglês) para instalar as bibliotecas do Firebase. No entanto, se você prefere não usar o CocoaPods, é possível integrar os frameworks do SDK diretamente ou usar o Gerenciador de pacotes Swift.

Você está usando um dos exemplos do guia de início rápido? O projeto Xcode e o Podfile (com pods) já estão presentes, mas você ainda precisará adicionar o arquivo de configuração do Firebase e instalar os pods.

1. Crie um Podfile, se ainda não tiver um:

   cd your-project-directory

   pod init

2. No seu Podfile, adicione os pods do Firebase que você quer usar no app.

   É possível adicionar qualquer um dos produtos do Firebase compatíveis ao app para iOS.

   Para uma experiência ideal com o Firebase Cloud Messaging, recomendamos ativar o Google Analytics no projeto. Além disso, como parte da configuração do Google Analytics, você precisa adicionar o SDK do Firebase para Google Analytics ao seu aplicativo.

   Analytics ativado

   # Add the Firebase pod for Google Analytics
   pod 'Firebase/Analytics'
   
   # For Analytics without IDFA collection capability, use this pod instead
   # pod ‘Firebase/AnalyticsWithoutAdIdSupport’
   
   # Add the pod for Firebase Cloud Messaging
   pod 'Firebase/Messaging'

   Saiba mais sobre o IDFA, o identificador de publicidade no nível do dispositivo, na documentação da Apple Privacidade do usuário e uso de dados e Transparência no rastreamento de apps.

   Analytics não ativado

   # Add the pod for Firebase Cloud Messaging
   pod 'Firebase/Messaging'

3. Instale os pods e abra seu arquivo .xcworkspace para ver o projeto no Xcode:

   pod install

   open your-project.xcworkspace

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 seu app.

Da mesma forma que o iOS normalmente entrega um token do dispositivo de APNs na inicialização do aplicativo, o FCM envia um token de registro por meio do método messaging:didReceiveRegistrationToken: do 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 iOS, 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 para iOS
• Enviar mensagens de tópico
• Enviar a grupos de dispositivos