Usted instala una aplicación y al día siguiente se olvida de ella. La retención de usuarios es uno de los desafíos más acuciantes del desarrollo móvil: sin un disparador externo, la gente simplemente no recuerda volver a abrir la app.

Las notificaciones push resuelven este problema de forma directa. Una breve señal en la pantalla de bloqueo y el usuario regresa a su contenido o acción. Desde junio de 2024, Google ha cerrado por completo la versión heredada de la API de FCM junto con la autenticación por clave de servidor. Ahora solo funciona la API HTTP v1 con OAuth 2.0.

A continuación encontrará una guía paso a paso para configurar Firebase Cloud Messaging y enviar notificaciones push multiplataforma mediante PHP: desde la creación de un proyecto hasta la recepción de notificaciones en Android e iOS.

Qué es FCM y por qué se cerró la API antigua

💡 Resumen rápido:

• Cree un proyecto de Firebase y obtenga una clave JSON
• Configure el SDK del cliente y obtenga un token FCM
• Instale kreait/firebase-php mediante Composer
• Envíe una notificación push a un tema con una sola llamada
• Reciba la notificación en el dispositivo en 1 a 3 segundos

Firebase Cloud Messaging (FCM) es el servicio multiplataforma de Google para enviar notificaciones a Android, iOS y la web. Es gratuito, no tiene cuotas estrictas en la cantidad de mensajes y funciona a través de una única API de servidor.

El predecesor de FCM, Google Cloud Messaging (GCM), utilizaba un esquema con IDs de registro de dispositivo y una clave de servidor. Los desarrolladores almacenaban los tokens en su propia base de datos y enviaban las notificaciones en un bucle. FCM añadió los temas (canales temáticos): un dispositivo se suscribe a /topics/news y el servidor envía un mensaje a todo el grupo de una vez, sin iterar sobre los tokens.

En junio de 2023, Google anunció la descontinuación de la API HTTP heredada y, a mediados de 2024, se ha cerrado por completo. El antiguo endpoint https://android.googleapis.com/gcm/send ya no acepta solicitudes. En lugar de una clave de servidor, ahora necesita un token OAuth 2.0 obtenido a partir del archivo JSON de una cuenta de servicio de Firebase. Los detalles de la migración están disponibles en la documentación oficial de FCM.

Tenga en cuenta que la API de Instance ID (iid.googleapis.com) para gestionar las suscripciones a temas también ha quedado obsoleta. El enfoque moderno consiste en suscribirse en el cliente mediante el SDK de Firebase o gestionar las suscripciones a través del SDK de Firebase Admin en el servidor.

Paso 1: Crear un proyecto en Firebase Console

Vaya a Firebase Console con su cuenta de Google. Haga clic en «Crear proyecto», asigne un nombre y espere la inicialización.

Tras crear el proyecto, vaya a Configuración del proyecto → Cuentas de servicio. Haga clic en «Generar nueva clave privada» y se descargará un archivo JSON con las credenciales. Guárdelo en una carpeta protegida de su servidor (fuera del document root): así es como el cliente PHP obtendrá el token OAuth 2.0 para la API HTTP v1.

También en Configuración del proyecto → Cloud Messaging, añada los certificados APNs de iOS si tiene previsto enviar notificaciones a dispositivos Apple. Sin este paso, las notificaciones push no funcionarán en iOS.

Paso 2: Configurar el SDK del cliente

Para que el servidor sepa a dónde enviar las notificaciones, la app cliente debe obtener un token FCM y enviarlo a su servidor. La configuración para ambas plataformas está cubierta en la documentación de Firebase; estos son los puntos clave.

IOS

Defina la URL de registro del dispositivo, el endpoint de su script PHP que acepta el token:

Integración mínima del SDK de Firebase en una app iOS:

En cada inicio, la app llama a Messaging.messaging().token(), obtiene el token FCM actual y lo envía a su URL de registro. El token puede cambiar cuando la app se reinstala, así que no lo guarde de forma permanente; actualícelo en cada inicio.

Android

La lógica es la misma: establezca la URL del endpoint del servidor para el registro del token:

Integración del SDK de Firebase en Android:

En Android, el token también se actualiza cuando la app se reinstala o se borran los datos; téngalo en cuenta al diseñar la tabla de dispositivos de su servidor.

Paso 3: Instalar la librería PHP y la autenticación

Para trabajar con la API HTTP v1 a través de PHP, necesita una librería que gestione la obtención del token OAuth 2.0 a partir del archivo JSON de la cuenta de servicio. La opción más consolidada a mediados de 2026 es kreait/firebase-php. Instalación mediante Composer:

1
composer require kreait/firebase-php

El archivo send_push.php con la inicialización del 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 que la ruta a la clave JSON sea absoluta y que el proceso PHP pueda leer el archivo. Nunca coloque la clave JSON en una carpeta pública del sitio web; si se accede a ella directamente a través del navegador, un atacante obtendría acceso completo a su proyecto de Firebase.

Paso 4: Enviar una notificación mediante la API HTTP v1

Ahora el mecanismo de envío en sí. El siguiente código toma el título y el texto de la notificación de un formulario, construye la carga útil y la envía al tema 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
}

Puntos clave explicados:

• CloudMessage::withTarget('topic', $topic) envía a un tema; para enviar a un dispositivo específico, sustitúyalo por withTarget('token', 'DEVICE_TOKEN').
• ->withData([...]) contiene datos personalizados para el enlace profundo: al tocar la notificación, la app abre una pantalla específica (en este ejemplo, una página de modelo).
• ->withHighestPossiblePriority() establece prioridad alta y la notificación se entrega de inmediato; para eventos silenciosos en segundo plano, use normal.
• MessagingException captura errores de validación, autenticación y red; envuelva siempre la llamada de envío en un try/catch.

Este código reemplaza por completo la combinación obsoleta de curl + Authorization:key=SERVER_KEY + el endpoint gcm/send, que dejó de funcionar en 2024.

Formulario para envío manual

Para pruebas rápidas, aquí tiene una interfaz HTML sencilla:

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>

En la práctica, un formulario así es solo una herramienta de depuración. En un proyecto en producción, la llamada $messaging->send() se integra en la lógica de negocio: publicar una noticia → notificar a los suscriptores del tema /topics/news.

Paso 5: Verificar la recepción de la notificación

Tras el envío, la notificación aparece en la pantalla de bloqueo en 1 a 3 segundos. El título y el cuerpo son los que se pasaron a Notification::create(). Al tocar la notificación se inicia la app y, a través de la carga útil de datos, se pasan parámetros para navegar a la pantalla correspondiente.

Los temas ofrecen una segmentación flexible de la audiencia. ¿Quiere separar a los usuarios por plataforma? Cree /topics/ios-news y /topics/android-news. ¿Por geografía? /topics/users-europe. ¿Por idioma? /topics/lang-ru. Combínelos como desee: los temas son gratuitos y no tienen límites de cantidad.

Vídeo: tutorial completo de configuración

Este tutorial de 20 minutos muestra la integración completa de Firebase Cloud Messaging con un backend PHP: desde la creación de un proyecto en la consola hasta el envío y la recepción de una notificación push en un dispositivo real.

⁉️🤔 Preguntas frecuentes

¿Tengo que pagar por Firebase Cloud Messaging?

FCM es completamente gratuito. Google no cobra por enviar notificaciones push y no impone cuotas estrictas en la cantidad de mensajes. Con volúmenes muy altos (millones por hora), puede activarse una limitación, pero para una app típica con una audiencia de hasta cientos de miles de usuarios, no hay restricciones.

¿Es obligatorio usar la librería kreait/firebase-php?

No, pero es el paquete PHP para Firebase mejor mantenido a mediados de 2026. La alternativa es trabajar con la API HTTP v1 directamente mediante Guzzle y google/auth para obtener el token OAuth 2.0. Sin embargo, en ese caso, tendrá que gestionar manualmente la vigencia del token, renovarlo y controlar los errores de autenticación. kreait/firebase-php se encarga de esto automáticamente.

¿Cómo envío notificaciones a un dispositivo específico en lugar de a todo un tema?

Sustituya withTarget('topic', $topic) por withTarget('token', $deviceToken), donde $deviceToken es el token FCM recibido de la app cliente. El token es único para cada instalación de la app en un dispositivo concreto.

¿Qué debo hacer si las notificaciones no llegan a iOS?

Compruebe tres cosas: (1) el certificado APNs está cargado en la configuración del proyecto de Firebase (Cloud Messaging → Configuración de la app de Apple), (2) la clave FirebaseAppDelegateProxyEnabled con el valor YES está añadida en Info.plist, (3) el dispositivo no está en modo No molestar. Tenga en cuenta también que el simulador de iOS no recibe notificaciones push; pruebe solo en un dispositivo físico.

¿Puedo enviar una notificación silenciosa sin mostrársela al usuario?

Sí, use un mensaje solo de datos: pase únicamente ->withData([...]) sin ->withNotification(...). Dicho mensaje despierta la app en segundo plano para la sincronización de datos, pero no muestra una notificación visual. En iOS, añada la cabecera content-available con el valor 1 para el procesamiento en segundo plano.

Qué ha cambiado y cómo evitar que las notificaciones fallen en 2026

Google ha ido endureciendo progresivamente los requisitos de seguridad de FCM. El principal cambio es el cierre de la API HTTP heredada con autenticación por clave de servidor. Si su código PHP todavía llama a https://android.googleapis.com/gcm/send o https://fcm.googleapis.com/fcm/send con una cabecera Authorization: key=..., las notificaciones no se han estado enviando desde mediados de 2024.

El cambio a la API HTTP v1 con OAuth 2.0 mediante una cuenta de servicio resuelve este problema por completo. La librería kreait/firebase-php gestiona la obtención y renovación del token, por lo que no necesita escribir la lógica de renovación manualmente. Almacene la clave JSON de la cuenta de servicio fuera del document root y exclúyala de su repositorio mediante .gitignore.

Con los temas y las cargas útiles de datos, obtiene un enrutamiento flexible: las noticias van a los suscriptores de /topics/news, los mensajes personales van por token y la sincronización silenciosa se realiza mediante mensajes solo de datos. Toda esta funcionalidad es gratuita y funciona en Android, iOS y la web desde un único script PHP.

Revise ahora mismo el código de envío de notificaciones actual en su proyecto. Si todavía usa Authorization: key=, actualícelo a la API HTTP v1. Publique cualquier pregunta y los matices de la integración en los comentarios.