Cómo enviar notificaciones push móviles con PHP y Firebase

Stock de McLittle / Shutterstock.com

El servicio Firebase Cloud Messaging (FCM) de Google es una forma gratuita y conveniente de distribuir notificaciones automáticas a dispositivos móviles. Funciona con objetivos iOS, Android y web, eliminando las diferencias entre plataformas. Envía su carga útil una vez a la API de Firebase y obtiene la entrega en tiempo real a todos sus usuarios.

En este artículo, le mostraremos cómo usar Firebase para enviar notificaciones automáticas desde su código PHP del lado del servidor. Estamos usando el tercero php-firebase-cloud-messaging (PHP-FCM) para simplificar aún más la integración de Firebase.

Índice de contenidos
  1. Delinear la arquitectura
  2. Creación de su proyecto de Firebase
  3. Preparando su aplicación PHP
  4. Registro de tokens de cliente
  5. Envío de notificaciones
  6. Manejo de datos de respuesta de FCM
  7. Adición de datos arbitrarios a las notificaciones
  8. Configuración de prioridades de mensajes
  9. Tiempo para vivir
  10. Insignias en iOS
  11. Conclusión

Delinear la arquitectura

El envío exitoso de una notificación automática requiere que varios componentes trabajen juntos. Primero, necesita una cuenta activa de Firebase con un proyecto que tenga FCM habilitado. Lo configuraremos en los siguientes pasos. Se le emitirá una clave de servidor que su backend de PHP debe incluir con sus solicitudes de Firebase.

También necesitará una aplicación que use el SDK de Firebase para producir un token de registro de cliente. Este token debe enviarse a su backend de PHP. Permanezca en su base de datos junto con la información que identifica al cliente, como su ID de usuario conectado dentro de su aplicación.

Dado que este artículo se centra en la integración de back-end, supondremos que ya tiene una aplicación cliente de Firebase que se suscribe a las notificaciones y recupera un token de registro. Puede seguir la documentación para crear una aplicación básica de Android si necesita un proyecto de muestra. Dentro de su código del lado del cliente, envíe el token de Firebase a un punto final de API que creará en su servicio de PHP.

Una vez que tenga algunos tokens de clientes disponibles en su servidor, puede enviar notificaciones automáticas realizando solicitudes HTTP a la API de FCM. Firebase mediará con las plataformas de entrega de notificaciones individuales y enviará su alerta a los dispositivos especificados. FCM asigna internamente cada token de cliente a la plataforma correcta, como Google Play Services para Android y Apple Push Notification Service (APNS) para iOS.

Creación de su proyecto de Firebase

imagen de la página de inicio de la consola de Firebase

Dirígete a Firebase Console, inicia sesión y haz clic en "Agregar proyecto" para comenzar a configurar tu integración. Asigne un nombre a su proyecto y haga clic en las indicaciones de configuración inicial. Haga clic en el engranaje de configuración en la esquina superior izquierda cuando llegue al tablero. Elija "Configuración del proyecto" en el menú que aparece.

imagen de la configuración de FCM en Firebase console

Dirígete a la pestaña "Mensajería en la nube" y anota tu clave de servidor. Su servicio PHP utilizará esta credencial para enviar notificaciones a la API de Firebase.

imagen de la página de inicio de la consola de Firebase

Debe registrar sus aplicaciones móviles en la consola de Firebase. De vuelta en la página de inicio, use los botones "Agregar una aplicación" para agregar sus componentes de iOS y Android. Siga el asistente de configuración para proporcionar los datos de su aplicación y descargar su archivo de configuración de Firebase. Se debe hacer referencia a esto cuando inicialice Firebase en su código del lado del cliente.

imagen de la configuración de FCM en Firebase console

Si está creando una aplicación para iOS, debe vincular manualmente su clave APNS a Firebase. Haga clic en el engranaje de configuración en la parte superior izquierda, elija "Configuración del proyecto" y navegue de regreso a "Cloud Messaging". Aparecerá una sección de "aplicaciones de Apple" cuando tenga un componente de iOS en su proyecto. Agregue una clave APNS o un certificado de su cuenta de desarrollador de Apple para completar la integración. Esto le permite a FCM enviar notificaciones a APNS en su nombre.

Preparando su aplicación PHP

Comience su proyecto PHP agregando la biblioteca PHP-FCM usando Composer:

composer require sngrl/php-firebase-cloud-messaging

Dentro de su código, cree una instancia de PHP-FCM Client clase:

use sngrlPhpFirebaseCloudMessagingClientClient;
 
$client = new Client();
$client -> setApiKey("FCM-SERVER-KEY");
$client -> injectGuzzleHttpClient(new GuzzleHttpClient());

Pasa el setApiKey() método la clave del servidor que copió de su consola API de Firebase. En una aplicación real, esto debe almacenarse de forma segura y tratarse como un secreto confidencial.

PHP-FCM se basa en una instancia de Guzzle inyectada para realizar sus solicitudes HTTP. Guzzle se incluye automáticamente como una dependencia, por lo que no necesita instalarlo manualmente. Estamos construyendo un nuevo cliente Guzzle en el ejemplo anterior; podría reutilizar una instancia existente si ya tiene Guzzle en su aplicación.

La FCM Client La instancia ahora está lista para enviar notificaciones a su cuenta de FCM.

Registro de tokens de cliente

Las notificaciones se distribuyen a tokens de clientes que representan los dispositivos de sus usuarios. Como se explicó anteriormente, deberá exponer un punto final de API en su aplicación que permita que sus aplicaciones cliente envíen su token de FCM después de que el usuario inicie sesión.

Aquí hay un ejemplo básico de cómo podría verse esto:

$token = $_POST["fcmToken"];
$userId = ((int) $_POST["userId"]);
 
/**
 * Call a function which persists a user/token 
 * association to your database
 */
saveUserFcmToken($userId, $token);

Para enviar una notificación automática a cada dispositivo registrado, seleccione todos los tokens en su almacén de datos. Puede enviar a un usuario específico recuperando los tokens asociados con su ID. Esto mostraría la notificación en todos los dispositivos en los que han iniciado sesión, que suele ser el comportamiento previsto.

Envío de notificaciones

PHP-FCM abstrae cada entrega de notificación en un Message objeto. Esto envuelve un Notification - que contiene el texto que se muestra al usuario - y cualquier opción de entrega que proporcione.

Prepara tu Notification primero:

use sngrlPhpFirebaseCloudMessagingClientNotification;
 
$notification = new Notification(
    "Notification Title",
    "The longer text of the notification, displayed below the title."
);

A continuación, cree un Message para representar la entrega de la notificación:

use sngrlPhpFirebaseCloudMessagingClientMessage;
 
$message = new Message();
$message -> setNotification($notification);

Antes de enviar su mensaje, agregue uno o más destinatarios. los addRecipient() método toma un Device instancia; esta clase necesita uno de sus tokens de cliente de FCM como su parámetro de constructor:

use sngrlPhpFirebaseCloudMessagingClientRecipientDevice;
 
$message -> addReceipient(new Device("FCM-CLIENT-TOKEN-USER-1"));
$message -> addReceipient(new Device("FCM-CLIENT-TOKEN-USER-2"));

Ahora está listo para enviar el mensaje usando el Client creado anteriormente:

$client -> send($message);

La notificación se enviará a los dispositivos que agregó como destinatarios.

Aquí hay un ejemplo completo que envuelve el código de manejo de notificaciones en una función conveniente:

use sngrlPhpFirebaseCloudMessagingClientClient;
use sngrlPhpFirebaseCloudMessagingClientMessage;
use sngrlPhpFirebaseCloudMessagingClientNotification;
use sngrlPhpFirebaseCloudMessagingClientRecipientDevice;
 
$client = new Client();
$client -> setApiKey("FCM-SERVER-KEY");
$client -> injectGuzzleHttpClient(new GuzzleHttpClient());
 
function sendNotification(
    Client $client,
    string $title,
    string $body,
    string ...$clientTokens) : void {
 
    $message = new Message();
 
    $message -> setNotification(
        new Notification(
            $title,
            $body
        )
    );
 
    foreach ($clientTokens as $clientToken) {
        $message -> addRecipient(new Device($clientToken));
    }
 
    $client -> send($message);
 
}
 
sendNotification($client, "Hello World", "Test Notification", "FCM-CLIENT-TOKEN-1");

Manejo de datos de respuesta de FCM

los Client::send() El método devuelve el objeto de respuesta HTTP para la solicitud de notificación. Puede inspeccionar los datos de respuesta codificados en JSON para determinar si sus notificaciones se entregaron correctamente.

$message = new Message();
$message -> setNotification(new Notification("Test", "Test"));
$message -> addReceipient(new Device("FCM-CLIENT-TOKEN-USER-1"));
$message -> addReceipient(new Device("FCM-CLIENT-TOKEN-USER-2"));
 
$response = $client -> send($message);
$responseData = $response -> json();

La matriz de datos de respuesta tiene una estructura similar a la siguiente:

{
    "success": 1,
    "failure": 1,
    "results": [
        {
            "message_id": 100
        },
        {
            "error": "InvalidRegistration"
        }
    ]
}

los results array contiene un objeto que representa el estado de entrega de cada uno de los dispositivos a los que intentó enviar. Esto coincidirá con el orden de los destinatarios agregados al Message mediante el addRecipient() método. El JSON de ejemplo anterior indica que solo el primer dispositivo recibió la notificación. La segunda entrega falló, por lo que debe eliminar el token del dispositivo de su base de datos.

$recipients = [
    "FCM-CLIENT-TOKEN-USER-1",
    "FCM-CLIENT-TOKEN-USER-2"
];
 
$message = new Message();
$message -> setNotification(new Notification("Test", "Test"));
 
foreach ($recipients as $recipient) {
    $message -> addReceipient(new Device($recipient));
}
 
$response = $client -> send($message);
$responseData = $response -> json();
 
foreach ($responseData["results"] as $i => $result) {
    if (isset($result["error"])) {
        deleteUserFcmToken($recipients[$i]);
    }
}

Adición de datos arbitrarios a las notificaciones

Los mensajes pueden incluir datos arbitrarios que deben comunicarse a la aplicación cliente:

$message = new Message();
$message -> setNotification(
    new Notification(
        "Breaking News!",
        "A breaking news story is available."
    )
);
$message -> setData([
    "uri" => "/news/latest-stories"
]);

El código del lado del cliente puede acceder a estos datos para realizar diferentes acciones cuando se recibe una notificación.

Configuración de prioridades de mensajes

FCM admite un sistema de prioridad de mensajes que le permite solicitar una entrega inmediata al dispositivo de destino. Cuando se usa el modo de prioridad alta, FCM intenta activar los dispositivos Android inactivos para manejar la notificación, incluso si se suprime la actividad en segundo plano.

// Indicate a high-priority message
$message -> setPriority("high");

Este atributo debe usarse con cuidado. Enviar demasiados mensajes prioritarios que no resulten en interacciones del usuario hará que sus entregas pierdan prioridad. El mecanismo está diseñado para cargas útiles realmente importantes que necesitan romper el ahorro de batería de un dispositivo, la limitación de la red y las restricciones de actividad en segundo plano.

iOS maneja las prioridades de manera diferente. Obtendrá un error si intenta enviar un high mensaje de prioridad a un dispositivo iOS. Puedes usar los valores normal o 5se prefiere este último que indica una entrega de alta prioridad.

Tiempo para vivir

A Message El tiempo de vida (TTL) de la instancia determina cuánto tiempo seguirá siendo relevante. FCM no siempre podrá enviar notificaciones de manera oportuna. El dispositivo de destino podría estar fuera de línea o en un estado de ahorro de batería. FCM seguirá intentando entregar la notificación, pero este no siempre es el comportamiento deseable. Algunas notificaciones, como los recordatorios de caducidad, pueden ser irrelevantes para el usuario en el momento en que las recibe.

Utilizar el setTimeToLive() para definir la vida útil de sus mensajes. FCM dejará de intentar entregarlos una vez que haya vencido el TTL.

$message = new Message();
$message -> setNotification(
    new Notification(
        "Server rotation scheduled for 12pm",
        "Cancel within the next 10 minutes."
    )
);
$message -> setTimeToLive(600);

Insignias en iOS

iOS usa insignias rojas en los íconos de la pantalla de inicio para indicar la cantidad de notificaciones no leídas disponibles dentro de la aplicación. Puede cambiar la insignia numérica de su aplicación con el setBadge() método en un Notification objeto:

$message = new Message();
$notification = new Notification(
    "Server rotation scheduled for 12pm",
    "Cancel within the next 10 minutes."
);
$notification -> setBadge(1);
$message -> setNotification($notification);
$message -> setTimeToLive(600);

los Notification La clase también tiene métodos para otros comportamientos específicos de la plataforma. Puede cambiar el icono de la notificación en dispositivos Android (setIcon()), asigne un sonido para reproducir (setSound()), y usar etiquetas (setTag()) para controlar si las notificaciones anteriores son reemplazadas por la nueva entrega. Estas propiedades y las peculiaridades de las implementaciones de su plataforma se describen en la documentación de la API de FCM.

Conclusión

FCM es una forma ideal de comenzar a enviar notificaciones automáticas a dispositivos móviles desde un backend de PHP. Maneja interacciones con implementaciones push específicas de la plataforma, como APNS y Google Play Services, lo que reduce la cantidad de código que necesita escribir.

La biblioteca PHP Firebase Cloud Messaging envuelve la API de FCM en prácticas clases y métodos de PHP. Para un control más avanzado, puede llamar a la API de FCM directamente a través de una biblioteca PHP HTTP como Guzzle. Es posible que deba adoptar este enfoque si necesita usar opciones de notificación que no están expuestas por PHP-FCM.

Descubre más contenido

Subir Change privacy settings