Começar a usar o Firebase Cloud Messaging

iOS+ Android Web Flutter Unity C++

Este guia de início rápido descreve como configurar o Firebase Cloud Messaging nos seus apps cliente da Web e para dispositivos móveis para que você possa enviar mensagens de forma confiável. Para ambientes de servidor, consulte O ambiente de servidor e o FCM.

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

Para apps cliente da Apple, você pode receber notificações e payloads de dados de até 4.096 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 exemplo de código dessas duas linguagens.

Antes de começar, adicione o Firebase ao seu projeto da Apple.

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 swizzling de métodos ativado ou não.

Importante: se estiver usando o SDK do Firebase para Unity do iOS, não desative o swizzling de métodos. Ele é exigido pelo SDK e necessário para o funcionamento correto dos principais recursos do Firebase, como o processamento de tokens do FCM.

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 no console do Firebase, selecione o ícone de engrenagem, clique em Configurações do projeto e selecione a guia Cloud Messaging.

2. Em Chave de autenticação de APNs, na seção Configuração do app iOS, clique no botão Fazer upload para enviar a chave de autenticação de desenvolvimento, a de produção ou ambas. Pelo menos uma dessas opções é obrigatória.

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

Registrar o app para receber notificações remotas

Na inicialização ou no ponto desejado do fluxo do seu aplicativo, registre-o para receber notificações remotas. Chame registerForRemoteNotifications conforme mostrado:

Observação: os apps da SwiftUI precisam usar os wrappers de propriedades UIApplicationDelegateAdaptor ou NSApplicationDelegateAdaptor para fornecer um tipo correspondente ao protocolo de delegação do app apropriado.

Swift

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()
AppDelegate.swift

Objective-C

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

[application registerForRemoteNotifications];
AppDelegate.m

É necessário atribuir a propriedade delegate do UNUserNotificationCenter e a propriedade delegate do FIRMessaging. Por exemplo, em um app iOS, atribua-a nos métodos applicationWillFinishLaunchingWithOptions: ou applicationDidFinishLaunchingWithOptions: do delegado do app.

Acessar o token de registro

Dica: consulte Práticas recomendadas de gerenciamento do token de registro do FCM para dicas sobre como gerenciar tokens.

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

Da mesma forma que as plataformas da Apple normalmente entregam um token de dispositivo de APNs ao iniciar o app, o FCM fornece um token de registro usando o método messaging:didReceiveRegistrationToken: de FIRMessagingDelegate. O SDK do FCM recupera um token novo ou atual 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.

Os apps que ainda usam APIs com IDs de instâncias descontinuadas para o gerenciamento de tokens precisam atualizar toda a lógica de tokens para usar as APIs do FCM descritas aqui.

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 delegado do aplicativo estiver em conformidade com o protocolo de delegação de mensagens, você vai poder configurá-lo como seu próprio delegado em application:didFinishLaunchingWithOptions:.

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

Como encontrar o token de registro atual

Os tokens de registro são enviados usando o 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.

Swift

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)"
  }
}

Objective-C

[[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 delegado em conformidade com o protocolo de delegação de mensagens. O exemplo a seguir registra o delegado e adiciona o método apropriado:

Swift

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

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.
}
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 ou está criando um app do SwiftUI, associe explicitamente o token de APNs ao token de registro do FCM. Implemente o método application(_:didRegisterForRemoteNotificationsWithDeviceToken:) para recuperar o token de APNs e defina a propriedade apnsToken do 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;
}

Depois que o token de registro do FCM for gerado, é possível 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, faça uma chamada de tempo de execução:

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[FIRMessaging messaging].autoInitEnabled = YES;

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

Configurar a extensão de serviço de notificação

Para enviar notificações com imagens a dispositivos Apple, adicione uma extensão de serviço de notificação. Com essa extensão, os dispositivos podem mostrar imagens enviadas no payload da notificação. Se você não planeja enviar imagens em notificações, pule esta etapa.

Para adicionar uma extensão de serviço, realize as etapas de configuração necessárias para modificar e apresentar notificações em APNs e, em seguida, adicione a API assistente de extensão do FCM em NotificationService.m. Em vez de concluir o callback com self.contentHandler(self.bestAttemptContent);, conclua-o especificamente com FIRMessaging extensionHelper, como mostrado abaixo:

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

}
...

Enviar uma mensagem de notificação

1. Instale e execute o app no dispositivo de destino. Em dispositivos Apple, aceite a solicitação de permissão para receber notificações remotas.
2. Verifique se o app está em segundo plano no dispositivo.
3. No console do Firebase, abra a página Mensagens.
4. Se esta for sua primeira mensagem, selecione Criar primeira campanha.
   1. Selecione Mensagens do Firebase Notificações e clique em Criar.
5. Se não for sua primeira mensagem, selecione Nova campanha e depois Notificações na guia Campanhas.
6. Digite o texto da mensagem.
7. Selecione Enviar mensagem de teste no painel à direita.
8. No campo Adicionar um token de registro do FCM, insira seu token de registro.
9. Selecione Testar.

Depois de selecionar Testar, o dispositivo cliente de destino com o app em segundo plano receberá a notificação.

Para saber mais sobre a entrega de mensagens ao seu app, consulte o painel de relatórios do FCM, que registra o número de mensagens enviadas e abertas em dispositivos Apple e Android.

Próximas etapas

Depois de configurar o cliente Apple, você pode começar a receber e enviar mensagens para os usuários:

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