Aplikację zainstalowano, a po jednym dniu o niej zapomniano. Powrót użytkownika to jeden z najpoważniejszych problemów w tworzeniu aplikacji mobilnych: bez zewnętrznego wyzwalacza człowiek po prostu nie przypomni sobie, aby ponownie otworzyć aplikację.

Powiadomienia push rozwiązują ten problem bezpośrednio. Jeden krótki sygnał na ekranie blokady i użytkownik wraca do Pana treści lub akcji. Od czerwca 2024 roku Google całkowicie wyłączył starszą wersję API FCM wraz z uwierzytelnianiem za pomocą klucza serwera. Działa wyłącznie HTTP v1 API z OAuth 2.0.

Poniżej znajduje się szczegółowy przewodnik po konfiguracji Firebase Cloud Messaging i wysyłaniu wieloplatformowych powiadomień push przez PHP: od utworzenia projektu po otrzymanie powiadomienia na Androidzie i iOS.

Czym jest FCM i dlaczego stare API zostało wyłączone

💡 Szybki przegląd:

• Tworzy Pan projekt Firebase, otrzymuje klucz JSON
• Konfiguruje Pan SDK klienta, otrzymuje token FCM
• Instaluje Pan kreait/firebase-php przez Composer
• Wysyła Pan powiadomienie push do tematu jednym wywołaniem
• Otrzymuje Pan powiadomienie na urządzeniu w ciągu 1-3 sekund

Firebase Cloud Messaging (FCM) to wieloplatformowa usługa Google do wysyłania powiadomień na Androida, iOS i do przeglądarek internetowych. Jest bezpłatna, nie ma sztywnych limitów na liczbę wiadomości i działa przez jedno API serwerowe.

Poprzednik FCM, Google Cloud Messaging (GCM), używał schematu z identyfikatorami rejestracyjnymi urządzeń i kluczem serwera. Deweloper przechowywał tokeny w swojej bazie danych i wysyłał powiadomienia w pętli. FCM dodał tematy (kanały tematyczne): urządzenie subskrybuje /topics/news, a serwer wysyła wiadomość od razu do całej grupy bez iterowania po tokenach.

W czerwcu 2023 roku Google ogłosił wycofanie starszego HTTP API, a od połowy 2024 roku zostało ono całkowicie wyłączone. Stary endpoint https://android.googleapis.com/gcm/send nie przyjmuje już żądań. Zamiast klucza serwera wymagany jest teraz token OAuth 2.0, który uzyskuje się z pliku JSON konta usługi Firebase. Szczegóły migracji znajdują się w oficjalnej dokumentacji FCM.

Proszę zwrócić uwagę: Instance ID API (iid.googleapis.com) do zarządzania subskrypcjami tematów również zostało wycofane. Współczesny sposób to subskrypcja po stronie klienta przez Firebase SDK lub zarządzanie przez Firebase Admin SDK na serwerze.

Krok 1: Tworzenie projektu w Firebase Console

Proszę wejść do Firebase Console na swoim koncie Google. Proszę kliknąć „Utwórz projekt", nadać nazwę i poczekać na inicjalizację.

Po utworzeniu projektu proszę przejść do Project Settings → Service Accounts. Proszę kliknąć „Generate new private key", zostanie pobrany plik JSON z danymi uwierzytelniającymi. Proszę zapisać go w bezpiecznym folderze serwera (poza document root): to za jego pośrednictwem klient PHP będzie uzyskiwał token OAuth 2.0 dla HTTP v1 API.

W tym samym miejscu, w Project Settings → Cloud Messaging, proszę dodać certyfikaty iOS APNs, jeśli planuje Pan wysyłać powiadomienia na urządzenia Apple. Bez tego kroku powiadomienia push na iOS nie będą działać.

Krok 2: Konfiguracja SDK klienta

Aby serwer wiedział, gdzie wysyłać powiadomienia, aplikacja kliencka musi uzyskać token FCM i przekazać go na Pana serwer. Konfiguracja dla obu platform znajduje się w dokumentacji Firebase, tutaj podano kluczowe punkty.

IOS

Proszę zdefiniować adres URL rejestracji urządzenia, endpoint Pana skryptu PHP, który przyjmuje token:

Minimalna integracja Firebase SDK w aplikacji iOS:

Podczas każdego uruchomienia aplikacja wywołuje Messaging.messaging().token(), uzyskuje aktualny token FCM i wysyła go na Pana adres URL rejestracji. Token może ulec zmianie podczas ponownej instalacji aplikacji, proszę nie przechowywać go na stałe, aktualizować przy każdym uruchomieniu.

Android

Logika jest taka sama: definiuje Pan URL endpointu serwera do rejestracji tokena:

Integracja Firebase SDK po stronie Androida:

Na Androidzie token jest również aktualizowany podczas ponownej instalacji aplikacji i czyszczenia danych, proszę uwzględnić to przy projektowaniu tabeli urządzeń na serwerze.

Krok 3: Instalacja biblioteki PHP i uwierzytelnianie

Do pracy z HTTP v1 API przez PHP potrzebna jest biblioteka, która przejmuje na siebie uzyskiwanie tokena OAuth 2.0 z pliku JSON konta usługi. Najbardziej dojrzałą opcją na połowę 2026 roku jest kreait/firebase-php. Instalacja przez Composer:

1
composer require kreait/firebase-php

Plik send_push.php, inicjalizacja klienta:

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

Proszę sprawdzić, czy ścieżka do klucza JSON jest bezwzględna i plik jest czytelny dla procesu PHP. Nigdy nie należy umieszczać klucza JSON w publicznym folderze witryny, w przypadku bezpośredniego dostępu przez przeglądarkę atakujący uzyska pełny dostęp do Pana projektu Firebase.

Krok 4: Wysyłanie powiadomienia przez HTTP v1 API

Teraz sam mechanizm wysyłania. Poniższy kod przyjmuje tytuł i treść powiadomienia z formularza, tworzy ładunek i wysyła go do określonego tematu:

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
}

Omówienie kluczowych punktów:

• CloudMessage::withTarget('topic', $topic), wysyłanie do tematu; aby wysłać do konkretnego urządzenia, proszę zastąpić przez withTarget('token', 'DEVICE_TOKEN').
• ->withData([...]), niestandardowe dane do deep linkingu: po kliknięciu powiadomienia aplikacja otwiera konkretny ekran (w przykładzie stronę modelu).
• ->withHighestPossiblePriority(), priorytet wysoki, powiadomienie jest dostarczane natychmiast; dla cichych zdarzeń w tle proszę użyć normal.
• MessagingException przechwytuje błędy walidacji, uwierzytelniania i awarie sieci, zawsze należy opakowywać wysyłanie w try/catch.

Ten kod całkowicie zastępuje przestarzałe połączenie curl + Authorization:key=SERVER_KEY + endpoint gcm/send, które nie działa od 2024 roku.

Formularz do ręcznego wysyłania

Do szybkiego testu, prosty interfejs 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>

W praktyce taki formularz jest jedynie narzędziem do debugowania. W projekcie produkcyjnym wywołanie $messaging->send() jest osadzane w logice biznesowej: publikacja newsa → powiadomienie dla subskrybentów tematu /topics/news.

Krok 5: Weryfikacja otrzymania powiadomienia

Po wysłaniu powiadomienie pojawia się na ekranie blokady w ciągu 1-3 sekund. Tytuł i treść są tymi przekazanymi w Notification::create(). Kliknięcie powiadomienia uruchamia aplikację, a poprzez ładunek danych przekazuje Pan parametry do przejścia na żądany ekran.

Tematy dają elastyczną segmentację odbiorców. Jeśli chce Pan podzielić użytkowników według platform, proszę utworzyć /topics/ios-news i /topics/android-news. Według geografii, /topics/users-europe. Według języka, /topics/lang-ru. Proszę łączyć dowolnie: tematy są bezpłatne i nie mają ograniczeń co do liczby.

Wideo: pełne omówienie konfiguracji

W tym 20-minutowym samouczku pokazano kompleksową integrację Firebase Cloud Messaging z backendem PHP: od utworzenia projektu w konsoli po wysłanie i otrzymanie powiadomienia push na rzeczywistym urządzeniu.

⁉️🤔 Często zadawane pytania

Czy za Firebase Cloud Messaging trzeba płacić?

FCM jest całkowicie bezpłatny. Google nie pobiera opłat za wysyłanie powiadomień push i nie ustanawia sztywnych limitów na liczbę wiadomości. Przy bardzo dużych wolumenach (miliony na godzinę) może zostać włączone ograniczanie przepustowości, ale dla typowej aplikacji z liczbą odbiorców do setek tysięcy użytkowników nie ma ograniczeń.

Czy korzystanie z biblioteki kreait/firebase-php jest obowiązkowe?

Nie, ale jest to najlepiej utrzymywany pakiet PHP dla Firebase na połowę 2026 roku. Alternatywą jest praca z HTTP v1 API bezpośrednio przez Guzzle i google/auth w celu uzyskania tokena OAuth 2.0. Jednak w takim przypadku będzie Pan musiał ręcznie zarządzać czasem życia tokena, odświeżać go i śledzić błędy uwierzytelniania. kreait/firebase-php robi to automatycznie.

Jak wysyłać powiadomienia do konkretnego urządzenia, a nie do całego tematu?

Proszę zastąpić withTarget('topic', $topic) przez withTarget('token', $deviceToken), gdzie $deviceToken to token FCM uzyskany z aplikacji klienckiej. Token jest unikalny dla każdej instalacji aplikacji na konkretnym urządzeniu.

Co zrobić, jeśli powiadomienia nie przychodzą na iOS?

Proszę sprawdzić trzy punkty: (1) certyfikat APNs został przesłany w ustawieniach projektu Firebase (Cloud Messaging → Apple app configuration), (2) w Info.plist dodano klucz FirebaseAppDelegateProxyEnabled z wartością YES, (3) urządzenie nie jest w trybie „Nie przeszkadzać". Proszę również wziąć pod uwagę, że symulator iOS nie odbiera powiadomień push, testować należy wyłącznie na fizycznym urządzeniu.

Czy można wysłać ciche powiadomienie bez pokazywania go użytkownikowi?

Tak, proszę użyć wiadomości wyłącznie z danymi (data-only message): proszę przekazać tylko ->withData([...]) bez ->withNotification(...). Taka wiadomość wybudza aplikację w tle w celu synchronizacji danych, ale nie pokazuje wizualnego powiadomienia. Na iOS do przetwarzania w tle proszę dodać nagłówek content-available z wartością 1.

Co się zmieniło i jak nie zepsuć wysyłania w 2026 roku

Google stopniowo zaostrza wymagania bezpieczeństwa FCM. Główną zmianą jest wyłączenie starszego HTTP API z uwierzytelnianiem za pomocą klucza serwera. Jeśli Pana kod PHP nadal odwołuje się do https://android.googleapis.com/gcm/send lub https://fcm.googleapis.com/fcm/send z nagłówkiem Authorization: key=..., powiadomienia nie są wysyłane od połowy 2024 roku.

Przejście na HTTP v1 API z OAuth 2.0 przez konto usługi całkowicie rozwiązuje ten problem. Biblioteka kreait/firebase-php przejmuje uzyskiwanie i odświeżanie tokena, nie musi Pan pisać logiki odświeżania ręcznie. Klucz JSON konta usługi proszę przechowywać poza document root i wykluczyć z repozytorium przez .gitignore.

Dzięki tematom i ładunkowi danych uzyskuje Pan elastyczny routing: newsy dla subskrybentów /topics/news, wiadomości osobiste według tokena, cichą synchronizację przez wiadomość wyłącznie z danymi. Cała ta funkcjonalność jest bezpłatna i działa na Androidzie, iOS oraz w przeglądarkach internetowych z jednego skryptu PHP.

Proszę sprawdzić obecny kod wysyłania powiadomień w Pana projekcie już teraz. Jeśli nadal jest tam Authorization: key=, proszę zaktualizować go do HTTP v1 API. Pytania i niuanse integracji proszę pisać w komentarzach.