Instala uma aplicação e, um dia depois, esquece-se dela. A retenção de utilizadores é um dos desafios mais prementes no desenvolvimento mobile: sem um gatilho externo, as pessoas simplesmente não se lembram de voltar a abrir a aplicação.

As notificações push resolvem este problema de forma direta. Um breve sinal no ecrã bloqueado e o utilizador regressa ao seu conteúdo ou ação. Desde junho de 2024, a Google descontinuou completamente a versão legada da API do FCM, juntamente com a autenticação por chave de servidor. Apenas a API HTTP v1 com OAuth 2.0 funciona atualmente.

Segue-se um guia passo a passo para configurar o Firebase Cloud Messaging e enviar notificações push multiplataforma via PHP: desde a criação de um projeto até à receção de notificações em Android e iOS.

O que é o FCM e por que razão a API antiga foi descontinuada

💡 Visão geral rápida:

• Criar um projeto Firebase e obter uma chave JSON
• Configurar o SDK do cliente e obter um token FCM
• Instalar o kreait/firebase-php via Composer
• Enviar uma notificação push para um tópico com uma única chamada
• Receber a notificação no dispositivo em 1 a 3 segundos

O Firebase Cloud Messaging (FCM) é o serviço multiplataforma da Google para envio de notificações para Android, iOS e web. É gratuito, não tem quotas rigorosas de número de mensagens e funciona através de uma única API de servidor.

O antecessor do FCM, o Google Cloud Messaging (GCM), usava um esquema com IDs de registo de dispositivo e uma chave de servidor. Os developers armazenavam os tokens na sua própria base de dados e enviavam notificações em ciclo. O FCM adicionou tópicos (canais temáticos): um dispositivo subscreve /topics/news e o servidor envia uma mensagem para todo o grupo de uma só vez, sem iterar pelos tokens.

Em junho de 2023, a Google anunciou a depreciação da API HTTP legada e, a partir de meados de 2024, foi completamente descontinuada. O antigo endpoint https://android.googleapis.com/gcm/send já não aceita pedidos. Em vez de uma chave de servidor, precisa agora de um token OAuth 2.0 obtido a partir do ficheiro JSON de uma conta de serviço Firebase. Os detalhes da migração estão disponíveis na documentação oficial do FCM.

Note que a API Instance ID (iid.googleapis.com) para gerir subscrições de tópicos também foi depreciada. A abordagem moderna é subscrever no cliente através do SDK Firebase ou gerir as subscrições através do Firebase Admin SDK no servidor.

Passo 1: Criar um projeto na Firebase Console

Aceda à Firebase Console com a sua conta Google. Clique em «Criar projeto», defina um nome e aguarde pela inicialização.

Após criar o projeto, vá a Definições do projeto → Contas de serviço. Clique em «Gerar nova chave privada» e será descarregado um ficheiro JSON com as credenciais. Guarde-o numa pasta protegida no seu servidor (fora da raiz do documento): é assim que o cliente PHP obterá o token OAuth 2.0 para a API HTTP v1.

Também em Definições do projeto → Cloud Messaging, adicione os certificados APNs do iOS se planear enviar notificações para dispositivos Apple. Sem este passo, as notificações push não funcionarão em iOS.

Passo 2: Configurar o SDK do cliente

Para que o servidor saiba para onde enviar as notificações, a aplicação cliente deve obter um token FCM e enviá-lo para o seu servidor. A configuração para ambas as plataformas está coberta na documentação do Firebase; aqui estão os pontos-chave.

IOS

Defina o URL de registo do dispositivo, o endpoint do seu script PHP que aceita o token:

Integração mínima do SDK Firebase numa aplicação iOS:

Em cada inicialização, a aplicação chama Messaging.messaging().token(), obtém o token FCM atual e envia-o para o seu URL de registo. O token pode mudar quando a aplicação é reinstalada, por isso não o guarde permanentemente; atualize-o em cada inicialização.

Android

A lógica é a mesma: defina o URL do endpoint do servidor para registo do token:

Integração do SDK Firebase no Android:

No Android, o token também é atualizado quando a aplicação é reinstalada ou os dados são limpos; tenha isto em mente ao projetar a tabela de dispositivos do seu servidor.

Passo 3: Instalar a biblioteca PHP e autenticação

Para trabalhar com a API HTTP v1 através de PHP, precisa de uma biblioteca que trate da obtenção do token OAuth 2.0 a partir do ficheiro JSON da conta de serviço. A opção mais madura em meados de 2026 é o kreait/firebase-php. Instalação via Composer:

1
composer require kreait/firebase-php

O ficheiro send_push.php com a inicialização do cliente:

1
<?php
2
require_once __DIR__ . '/vendor/autoload.php';
3
 
4
use Kreait\Firebase\Factory;
5
use Kreait\Firebase\Messaging\CloudMessage;
6
use Kreait\Firebase\Messaging\Notification;
7
 
8
$factory = (new Factory)
9
    ->withServiceAccount('/путь/к/serviceAccountKey.json');
10
 
11
$messaging = $factory->createMessaging();

Verifique se o caminho para a chave JSON é absoluto e se o ficheiro é legível pelo processo PHP. Nunca coloque a chave JSON numa pasta pública do website; se for acedida diretamente através de um navegador, um atacante obteria acesso total ao seu projeto Firebase.

Passo 4: Enviar uma notificação via API HTTP v1

Agora o mecanismo de envio propriamente dito. O código abaixo recebe o título e o texto da notificação de um formulário, constrói o payload e envia-o para o tópico especificado:

1
<?php
2
require_once __DIR__ . '/vendor/autoload.php';
3
 
4
use Kreait\Firebase\Factory;
5
use Kreait\Firebase\Messaging\CloudMessage;
6
use Kreait\Firebase\Messaging\Notification;
7
 
8
$factory = (new Factory)
9
    ->withServiceAccount('/путь/к/serviceAccountKey.json');
10
 
11
$messaging = $factory->createMessaging();
12
 
13
$topic = 'my-app';
14
 
15
$notification = Notification::create(
16
    $_POST['title'] ?? 'Новое уведомление',
17
    $_POST['summary'] ?? ''
18
);
19
 
20
$message = CloudMessage::withTarget('topic', $topic)
21
    ->withNotification($notification)
22
    ->withData([
23
        'action' => 'models',
24
        'model_id' => '2701',
25
    ])
26
    ->withHighestPossiblePriority();
27
 
28
try {
29
    $result = $messaging->send($message);
30
    echo "Уведомление отправлено. ID: " . json_encode($result);
31
} catch (\Kreait\Firebase\Exception\MessagingException $e) {
32
    echo "Ошибка отправки: " . $e->getMessage();
33
}

Pontos-chave explicados:

• CloudMessage::withTarget('topic', $topic) envia para um tópico; para enviar para um dispositivo específico, substitua por withTarget('token', 'DEVICE_TOKEN').
• ->withData([...]) contém dados personalizados para deep linking: ao tocar na notificação, a aplicação abre um ecrã específico (neste exemplo, uma página de modelo).
• ->withHighestPossiblePriority() define prioridade alta e a notificação é entregue imediatamente; para eventos silenciosos em segundo plano, use normal.
• MessagingException captura erros de validação, autenticação e rede; envolva sempre a chamada de envio em try/catch.

Este código substitui totalmente a combinação depreciada de curl + Authorization:key=SERVER_KEY + o endpoint gcm/send, que deixou de funcionar em 2024.

Formulário para envio manual

Para testes rápidos, aqui está uma interface HTML simples:

1
<form method="POST" action="send_push.php">
2
    <input type="text" name="title" placeholder="Заголовок уведомления" required>
3
    <textarea name="summary" placeholder="Текст уведомления" required></textarea>
4
    <button type="submit">Отправить push</button>
5
</form>

Na prática, este formulário é apenas uma ferramenta de depuração. Num projeto de produção, a chamada $messaging->send() é integrada na lógica de negócio: publicar uma notícia → notificar os subscritores do tópico /topics/news.

Passo 5: Verificar a receção da notificação

Após o envio, a notificação aparece no ecrã bloqueado em 1 a 3 segundos. O título e o corpo são os passados a Notification::create(). Tocar na notificação inicia a aplicação e, através do payload de dados, passa parâmetros para navegar para o ecrã apropriado.

Os tópicos proporcionam uma segmentação flexível da audiência. Quer separar os utilizadores por plataforma? Crie /topics/ios-news e /topics/android-news. Por geografia? /topics/users-europe. Por idioma? /topics/lang-ru. Combine como quiser: os tópicos são gratuitos e não têm limites de quantidade.

Vídeo: tutorial completo de configuração

Este tutorial de 20 minutos mostra a integração completa do Firebase Cloud Messaging com um backend PHP: desde a criação de um projeto na consola até ao envio e receção de uma notificação push num dispositivo real.

⁉️🤔 Perguntas frequentes

Tenho de pagar pelo Firebase Cloud Messaging?

O FCM é totalmente gratuito. A Google não cobra pelo envio de notificações push e não impõe quotas rigorosas ao número de mensagens. Em volumes muito elevados (milhões por hora), pode ocorrer limitação de tráfego, mas para uma aplicação típica com uma audiência até centenas de milhares de utilizadores, não há limitações.

É obrigatório usar a biblioteca kreait/firebase-php?

Não, mas é o pacote PHP mais bem mantido para Firebase em meados de 2026. A alternativa é trabalhar diretamente com a API HTTP v1 via Guzzle e google/auth para obter o token OAuth 2.0. No entanto, nesse caso, terá de gerir manualmente o tempo de vida do token, renová-lo e monitorizar erros de autenticação. O kreait/firebase-php trata disto automaticamente.

Como envio notificações para um dispositivo específico em vez de um tópico inteiro?

Substitua withTarget('topic', $topic) por withTarget('token', $deviceToken), onde $deviceToken é o token FCM recebido da aplicação cliente. O token é único para cada instalação da aplicação num dispositivo específico.

O que devo fazer se as notificações não chegarem ao iOS?

Verifique três coisas: (1) o certificado APNs está carregado nas definições do projeto Firebase (Cloud Messaging → Configuração da app Apple), (2) a chave FirebaseAppDelegateProxyEnabled com o valor YES foi adicionada ao Info.plist, (3) o dispositivo não está no modo Não Perturbar. Note também que o simulador iOS não recebe notificações push; teste apenas num dispositivo físico.

Posso enviar uma notificação silenciosa sem a mostrar ao utilizador?

Sim, use uma mensagem apenas de dados: passe apenas ->withData([...]) sem ->withNotification(...). Essa mensagem acorda a aplicação em segundo plano para sincronização de dados, mas não mostra uma notificação visual. No iOS, adicione o cabeçalho content-available com o valor 1 para processamento em segundo plano.

O que mudou e como evitar que as notificações falhem em 2026

A Google tem vindo a reforçar progressivamente os requisitos de segurança do FCM. A principal mudança é o encerramento da API HTTP legada com autenticação por chave de servidor. Se o seu código PHP ainda chama https://android.googleapis.com/gcm/send ou https://fcm.googleapis.com/fcm/send com um cabeçalho Authorization: key=..., as notificações deixaram de ser enviadas desde meados de 2024.

A mudança para a API HTTP v1 com OAuth 2.0 via conta de serviço resolve este problema por completo. A biblioteca kreait/firebase-php trata da obtenção e renovação do token, pelo que não precisa de escrever lógica de renovação manualmente. Guarde a chave JSON da conta de serviço fora da raiz do documento e exclua-a do seu repositório via .gitignore.

Com tópicos e payloads de dados, obtém um encaminhamento flexível: as notícias vão para os subscritores de /topics/news, as mensagens pessoais vão por token e a sincronização silenciosa acontece através de mensagens apenas de dados. Toda esta funcionalidade é gratuita e funciona em Android, iOS e web a partir de um único script PHP.

Verifique agora mesmo o código de envio de notificações atual no seu projeto. Se ainda usa Authorization: key=, atualize para a API HTTP v1. Coloque quaisquer questões e nuances de integração nos comentários.