Installate un'app e il giorno dopo ve ne dimenticate. La retention degli utenti è una delle sfide più pressanti nello sviluppo mobile: senza un trigger esterno, le persone semplicemente non si ricorderanno di riaprire l'app.

Le notifiche push risolvono questo problema alla radice. Un breve segnale sulla schermata di blocco e l'utente torna ai vostri contenuti o alla vostra azione. Da giugno 2024, Google ha dismesso completamente la versione legacy dell'API FCM insieme all'autenticazione tramite chiave server. Ora funziona solo l'API HTTP v1 con OAuth 2.0.

Ecco una guida passo passo per configurare Firebase Cloud Messaging e inviare notifiche push multipiattaforma tramite PHP: dalla creazione del progetto alla ricezione delle notifiche su Android e iOS.

Cos'è FCM e perché la vecchia API è stata dismessa

💡 Panoramica rapida:

• Create un progetto Firebase e ottenete una chiave JSON
• Configurate l'SDK client e ottenete un token FCM
• Installate kreait/firebase-php via Composer
• Inviate una notifica push a un topic con una singola chiamata
• Ricevete la notifica sul dispositivo in 1-3 secondi

Firebase Cloud Messaging (FCM) è il servizio multipiattaforma di Google per l'invio di notifiche ad Android, iOS e web. È gratuito, non ha quote rigide sul numero di messaggi e funziona tramite un'unica API lato server.

Il predecessore di FCM, Google Cloud Messaging (GCM), utilizzava uno schema con ID di registrazione del dispositivo e una chiave server. Gli sviluppatori memorizzavano i token nel proprio database e inviavano le notifiche in un ciclo. FCM ha aggiunto i topic (canali tematici): un dispositivo si iscrive a /topics/news e il server invia un messaggio all'intero gruppo in una volta sola, senza iterare sui token.

A giugno 2023, Google ha annunciato la deprecazione dell'API HTTP legacy e, da metà 2024, è stata completamente dismessa. Il vecchio endpoint https://android.googleapis.com/gcm/send non accetta più richieste. Al posto della chiave server, ora serve un token OAuth 2.0 ottenuto dal file JSON di un account di servizio Firebase. I dettagli sulla migrazione sono disponibili nella documentazione ufficiale di FCM.

Si noti che anche l'API Instance ID (iid.googleapis.com) per la gestione delle iscrizioni ai topic è stata deprecata. L'approccio moderno prevede l'iscrizione lato client tramite l'SDK Firebase o la gestione delle iscrizioni tramite l'SDK Admin Firebase sul server.

Passo 1: Creazione di un progetto nella Firebase Console

Andate alla Firebase Console con il vostro account Google. Cliccate su "Crea progetto", assegnate un nome e attendete l'inizializzazione.

Dopo aver creato il progetto, andate su Impostazioni progetto → Account di servizio. Cliccate su "Genera nuova chiave privata" e verrà scaricato un file JSON con le credenziali. Salvatelo in una cartella protetta sul vostro server (al di fuori della document root): è così che il client PHP otterrà il token OAuth 2.0 per l'API HTTP v1.

Sempre in Impostazioni progetto → Cloud Messaging, aggiungete i certificati APNs iOS se prevedete di inviare notifiche ai dispositivi Apple. Senza questo passaggio, le notifiche push non funzioneranno su iOS.

Passo 2: Configurazione dell'SDK client

Affinché il server sappia dove inviare le notifiche, l'app client deve ottenere un token FCM e inviarlo al vostro server. La configurazione per entrambe le piattaforme è trattata nella documentazione di Firebase; ecco i punti chiave.

IOS

Definite l'URL di registrazione del dispositivo, l'endpoint del vostro script PHP che accetta il token:

Integrazione minima dell'SDK Firebase in un'app iOS:

A ogni avvio, l'app chiama Messaging.messaging().token(), ottiene il token FCM corrente e lo invia al vostro URL di registrazione. Il token può cambiare quando l'app viene reinstallata, quindi non salvatelo in modo permanente; aggiornatelo a ogni avvio.

Android

La logica è la stessa: impostate l'URL dell'endpoint server per la registrazione del token:

Integrazione dell'SDK Firebase su Android:

Anche su Android, il token si aggiorna quando l'app viene reinstallata o i dati vengono cancellati; tenetelo presente quando progettate la tabella dei dispositivi del vostro server.

Passo 3: Installazione della libreria PHP e autenticazione

Per lavorare con l'API HTTP v1 tramite PHP, avete bisogno di una libreria che gestisca l'ottenimento del token OAuth 2.0 dal file JSON dell'account di servizio. L'opzione più matura a metà 2026 è kreait/firebase-php. Installazione via Composer:

1
composer require kreait/firebase-php

Il file send_push.php con l'inizializzazione del client:

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();

Verificate che il percorso della chiave JSON sia assoluto e che il file sia leggibile dal processo PHP. Non collocate mai la chiave JSON in una cartella pubblica del sito web; se vi si accedesse direttamente tramite browser, un malintenzionato otterrebbe pieno accesso al vostro progetto Firebase.

Passo 4: Invio di una notifica tramite API HTTP v1

Ora il meccanismo di invio vero e proprio. Il codice seguente prende il titolo e il testo della notifica da un form, costruisce il payload e lo invia al topic specificato:

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
}

Punti chiave spiegati:

• CloudMessage::withTarget('topic', $topic) invia a un topic; per inviare a un dispositivo specifico, sostituitelo con withTarget('token', 'DEVICE_TOKEN').
• ->withData([...]) contiene dati personalizzati per il deep linking: quando si tocca la notifica, l'app apre una schermata specifica (in questo esempio, una pagina di modello).
• ->withHighestPossiblePriority() imposta la priorità alta e la notifica viene consegnata immediatamente; per eventi silenziosi in background, usate normal.
• MessagingException cattura errori di validazione, autenticazione e rete; racchiudete sempre la chiamata di invio in un try/catch.

Questo codice sostituisce completamente la combinazione deprecata di curl + Authorization:key=SERVER_KEY + l'endpoint gcm/send, che ha smesso di funzionare nel 2024.

Form per l'invio manuale

Per un test rapido, ecco una semplice interfaccia HTML:

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>

In pratica, un form del genere è solo uno strumento di debug. In un progetto in produzione, la chiamata $messaging->send() è integrata nella logica di business: pubblica una notizia → notifica gli iscritti al topic /topics/news.

Passo 5: Verifica della ricezione della notifica

Dopo l'invio, la notifica appare sulla schermata di blocco entro 1-3 secondi. Il titolo e il corpo sono quelli passati a Notification::create(). Toccando la notifica si avvia l'app e, tramite il payload dati, si passano i parametri per navigare alla schermata appropriata.

I topic offrono una segmentazione flessibile del pubblico. Volete separare gli utenti per piattaforma? Create /topics/ios-news e /topics/android-news. Per area geografica? /topics/users-europe. Per lingua? /topics/lang-ru. Combinateli come preferite: i topic sono gratuiti e non hanno limiti di quantità.

Video: guida completa alla configurazione

Questo tutorial di 20 minuti mostra l'integrazione end-to-end di Firebase Cloud Messaging con un backend PHP: dalla creazione di un progetto nella console all'invio e alla ricezione di una notifica push su un dispositivo reale.

⁉️🤔 Domande frequenti

Devo pagare per Firebase Cloud Messaging?

FCM è completamente gratuito. Google non addebita costi per l'invio di notifiche push e non impone quote rigide sul numero di messaggi. A volumi molto elevati (milioni all'ora), potrebbe attivarsi la limitazione, ma per un'app tipica con un pubblico fino a centinaia di migliaia di utenti, non ci sono limitazioni.

È obbligatorio usare la libreria kreait/firebase-php?

No, ma è il pacchetto PHP per Firebase più curato a metà 2026. L'alternativa è lavorare direttamente con l'API HTTP v1 tramite Guzzle e google/auth per ottenere il token OAuth 2.0. Tuttavia, in quel caso, dovrete gestire manualmente la durata del token, il suo rinnovo e tracciare gli errori di autenticazione. kreait/firebase-php lo fa automaticamente.

Come invio notifiche a un dispositivo specifico anziché a un intero topic?

Sostituite withTarget('topic', $topic) con withTarget('token', $deviceToken), dove $deviceToken è il token FCM ricevuto dall'app client. Il token è unico per ogni installazione dell'app su un dispositivo specifico.

Cosa devo fare se le notifiche non arrivano su iOS?

Verificate tre cose: (1) il certificato APNs è caricato nelle impostazioni del progetto Firebase (Cloud Messaging → Configurazione app Apple), (2) la chiave FirebaseAppDelegateProxyEnabled con valore YES è aggiunta a Info.plist, (3) il dispositivo non è in modalità Non disturbare. Inoltre, tenete presente che il simulatore iOS non riceve notifiche push; testate solo su un dispositivo fisico.

Posso inviare una notifica silenziosa senza mostrarla all'utente?

Sì, usate un messaggio di soli dati: passate solo ->withData([...]) senza ->withNotification(...). Un messaggio del genere risveglia l'app in background per la sincronizzazione dei dati, ma non mostra una notifica visiva. Su iOS, aggiungete l'header content-available con valore 1 per l'elaborazione in background.

Cosa è cambiato e come evitare che le notifiche si interrompano nel 2026

Google ha progressivamente inasprito i requisiti di sicurezza di FCM. Il cambiamento principale è la dismissione dell'API HTTP legacy con autenticazione tramite chiave server. Se il vostro codice PHP chiama ancora https://android.googleapis.com/gcm/send o https://fcm.googleapis.com/fcm/send con un header Authorization: key=..., le notifiche non vengono più inviate da metà 2024.

Il passaggio all'API HTTP v1 con OAuth 2.0 tramite un account di servizio risolve completamente questo problema. La libreria kreait/firebase-php gestisce l'ottenimento e il rinnovo del token, quindi non dovete scrivere manualmente la logica di refresh. Conservate la chiave JSON dell'account di servizio al di fuori della document root ed escludetela dal vostro repository tramite .gitignore.

Con i topic e i payload dati, ottenete un routing flessibile: le notizie vanno agli iscritti di /topics/news, i messaggi personali vanno per token e la sincronizzazione silenziosa avviene tramite messaggi di soli dati. Tutta questa funzionalità è gratuita e funziona su Android, iOS e web da un singolo script PHP.

Verificate subito il codice di invio delle notifiche attuale nel vostro progetto. Se usa ancora Authorization: key=, aggiornatelo all'API HTTP v1. Postate domande e sfumature di integrazione nei commenti.