📱 Google FCM + PHP: надсилання push-сповіщень через HTTP v1 API

Q: Як надсилати сповіщення конкретному пристрою, а не цілому топіку?

Замініть withTarget('topic', $topic) на withTarget('token', $deviceToken), де $deviceToken, FCM-токен, отриманий від клієнтського застосунку. Токен унікальний для кожної інсталяції застосунку на конкретному пристрої.

Q: Чи можна надіслати тихе сповіщення без показу користувачеві?

Так, використовуйте data-only message: передайте лише ->withData([...]) без ->withNotification(...). Таке повідомлення будить застосунок у фоні для синхронізації даних, але не показує візуальне сповіщення. На iOS для фонової обробки додайте заголовок content-available зі значенням 1.

Застосунок встановили, а через день про нього забули. Повернення користувача, одна з найгостріших проблем мобільної розробки: без зовнішнього тригера людина просто не згадає відкрити застосунок знову.

Push-сповіщення розв’язують цю задачу напряму. Один короткий сигнал на екрані блокування, і користувач повертається до вашого контенту або дії. З червня 2024 року Google повністю вимкнув legacy-версію FCM API разом з автентифікацією за серверним ключем. Працює лише HTTP v1 API з OAuth 2.0.

Нижче, покроковий посібник із налаштування Firebase Cloud Messaging та надсилання кросплатформних push-сповіщень через PHP: від створення проєкту до отримання сповіщення на Android та iOS.

Що таке FCM і чому старий API вимкнено

💡 Швидкий огляд:

Створюєте проєкт Firebase, отримуєте JSON-ключ
Налаштовуєте клієнтський SDK, отримуєте FCM-токен
Встановлюєте kreait/firebase-php через Composer
Надсилаєте push-сповіщення в топік одним викликом
Отримуєте сповіщення на пристрої за 1-3 секунди

Firebase Cloud Messaging (FCM) — це кросплатформний сервіс Google для надсилання сповіщень на Android, iOS і веб. Він безплатний, не має жорстких квот на кількість повідомлень і працює через єдиний серверний API.

Попередник FCM, Google Cloud Messaging (GCM), використовував схему з реєстраційними ID пристроїв і серверним ключем. Розробник зберігав токени у своїй базі та ганяв сповіщення в циклі. FCM додав топіки (тематичні канали): пристрій підписується на /topics/news, і сервер надсилає повідомлення одразу всій групі без перебору токенів.

У червні 2023 року Google оголосив про застарілість legacy HTTP API, а з середини 2024 року його повністю вимкнено. Старий ендпоінт https://android.googleapis.com/gcm/send більше не приймає запитів. Замість серверного ключа тепер потрібен OAuth 2.0-токен, який отримують із JSON-файлу сервісного акаунта Firebase. Подробиці міграції, в офіційній документації FCM.

Зверніть увагу: Instance ID API (iid.googleapis.com) для керування підписками на топіки також виведено з експлуатації. Сучасний спосіб, підписка на клієнті через Firebase SDK або керування через Firebase Admin SDK на сервері.

Крок 1: Створення проєкту в Firebase Console

Зайдіть у Firebase Console під своїм обліковим записом Google. Натисніть «Створити проєкт», задайте ім’я та дочекайтеся ініціалізації.

Налаштування проєкту Firebase з серверним ключем

Після створення проєкту перейдіть у Project Settings → Service Accounts. Натисніть «Generate new private key», завантажиться JSON-файл з обліковими даними. Збережіть його в захищену папку сервера (поза document root): саме через нього PHP-клієнт отримуватиме OAuth 2.0-токен для HTTP v1 API.

Там само, у Project Settings → Cloud Messaging, додайте iOS-сертифікати APNs, якщо плануєте надсилати сповіщення на пристрої Apple. Без цього кроку push на iOS не працюватиме.

Крок 2: Налаштування клієнтського SDK

Щоб сервер знав, куди надсилати сповіщення, клієнтський застосунок має отримати FCM-токен і передати його на ваш сервер. Налаштування для обох платформ, у документації Firebase, тут, опорні точки.

IOS

Визначте URL-адресу реєстрації пристрою, ендпоінт вашого PHP-скрипту, який приймає токен:

Мінімальна інтеграція Firebase SDK в iOS-застосунок:

Приклад налаштування Firebase SDK для iOS

Під час кожного запуску застосунок викликає Messaging.messaging().token(), отримує актуальний FCM-токен і надсилає його на вашу реєстраційну URL-адресу. Токен може змінитися під час перевстановлення застосунку, не зберігайте його назавжди, оновлюйте під час кожного запуску.

Android

Логіка та сама: задаєте URL серверного ендпоінту для реєстрації токена:

Інтеграція Firebase SDK на стороні Android:

Приклад налаштування Firebase SDK для Android

На Android токен також оновлюється під час перевстановлення застосунку та очищення даних, враховуйте це під час проєктування серверної таблиці пристроїв.

Крок 3: Встановлення PHP-бібліотеки та автентифікація

Для роботи з HTTP v1 API через PHP потрібна бібліотека, яка бере на себе отримання OAuth 2.0-токена з JSON-файлу сервісного акаунта. Найзріліший варіант на середину 2026 року, kreait/firebase-php. Встановлення через Composer:

1 composer require kreait/firebase-php

Файл send_push.php, ініціалізація клієнта:

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

Перевірте, що шлях до JSON-ключа абсолютний і файл читається процесом PHP. Ніколи не кладіть JSON-ключ у публічну папку сайту, у разі прямого доступу через браузер зловмисник отримає повний доступ до вашого проєкту Firebase.

Крок 4: Надсилання сповіщення через HTTP v1 API

Тепер сам механізм надсилання. Код нижче приймає заголовок і текст сповіщення з форми, формує payload і надсилає його в заданий топік:

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 }

Розбір ключових моментів:

CloudMessage::withTarget('topic', $topic), надсилання в топік; для надсилання конкретному пристрою замініть на withTarget('token', 'DEVICE_TOKEN').
->withData([...]), кастомні дані для deep linking: під час натискання на сповіщення застосунок відкриває конкретний екран (у прикладі, сторінку моделі).
->withHighestPossiblePriority(), пріоритет high, сповіщення доставляється негайно; для тихих фонових подій використовуйте normal.
MessagingException ловить помилки валідації, автентифікації та мережеві збої, завжди обгортайте надсилання в try/catch.

Цей код повністю замінює застарілу зв’язку curl + Authorization:key=SERVER_KEY + ендпоінт gcm/send, яка не працює з 2024 року.

Форма для ручного надсилання

Для швидкого тесту, простий 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>

На практиці така форма, лише інструмент для налагодження. У бойовому проєкті виклик $messaging->send() вбудовується в бізнес-логіку: публікація новини → сповіщення підписникам топіка /topics/news.

Форма надсилання push-сповіщення в адмінці

Крок 5: Перевірка отримання сповіщення

Після надсилання сповіщення приходить на екран блокування за 1-3 секунди. Заголовок і тіло, ті, що передані в Notification::create(). Натискання на сповіщення запускає застосунок, і через data-payload ви передаєте параметри для переходу на потрібний екран.

Топіки дають гнучку сегментацію аудиторії. Хочете розділити користувачів за платформами, створіть /topics/ios-news і /topics/android-news. За географією, /topics/users-europe. За мовою, /topics/lang-ru. Комбінуйте як завгодно: топіки безплатні й не мають обмежень за кількістю.

Результат доставки push-сповіщення через FCM

Відео: повний розбір налаштування

У цьому 20-хвилинному туторіалі показано наскрізну інтеграцію Firebase Cloud Messaging із PHP-бекендом: від створення проєкту в консолі до надсилання й отримання push-сповіщення на реальному пристрої.

⁉️🤔 Часті запитання

Чи потрібно платити за Firebase Cloud Messaging?

FCM повністю безплатний. Google не стягує плату за надсилання push-сповіщень і не встановлює жорстких квот на кількість повідомлень. За дуже високих обсягів (мільйони на годину) може вмикатися тротлінг, але для типового застосунку з аудиторією до сотень тисяч користувачів обмежень немає.

Чи обов’язково використовувати бібліотеку kreait/firebase-php?

Ні, але це найпідтримуваніший PHP-пакет для Firebase на середину 2026 року. Альтернатива, працювати з HTTP v1 API напряму через Guzzle і google/auth для отримання OAuth 2.0-токена. Однак у цьому разі вам доведеться вручну керувати терміном життя токена, рефрешити його та відстежувати помилки автентифікації. kreait/firebase-php робить це автоматично.

Як надсилати сповіщення конкретному пристрою, а не цілому топіку?

Замініть withTarget('topic', $topic) на withTarget('token', $deviceToken), де $deviceToken, FCM-токен, отриманий від клієнтського застосунку. Токен унікальний для кожної інсталяції застосунку на конкретному пристрої.

Що робити, якщо сповіщення не приходять на iOS?

Перевірте три пункти: (1) APNs-сертифікат завантажено в налаштуваннях проєкту Firebase (Cloud Messaging → Apple app configuration), (2) в Info.plist додано ключ FirebaseAppDelegateProxyEnabled зі значенням YES, (3) пристрій не перебуває в режимі «Не турбувати». Також врахуйте, що симулятор iOS не приймає push, тестуйте лише на фізичному пристрої.

Чи можна надіслати тихе сповіщення без показу користувачеві?

Так, використовуйте data-only message: передайте лише ->withData([...]) без ->withNotification(...). Таке повідомлення будить застосунок у фоні для синхронізації даних, але не показує візуальне сповіщення. На iOS для фонової обробки додайте заголовок content-available зі значенням 1.

Що змінилося і як не зламати надсилання у 2026 році

Google поетапно посилює вимоги до безпеки FCM. Головна зміна, вимкнення legacy HTTP API з автентифікацією за серверним ключем. Якщо ваш PHP-код досі звертається до https://android.googleapis.com/gcm/send або https://fcm.googleapis.com/fcm/send із заголовком Authorization: key=..., сповіщення не надсилаються із середини 2024 року.

Перехід на HTTP v1 API з OAuth 2.0 через сервісний акаунт розв’язує цю проблему повністю. Бібліотека kreait/firebase-php бере на себе отримання й оновлення токена, вам не потрібно писати логіку рефрешу вручну. JSON-ключ сервісного акаунта зберігайте поза document root і виключіть із репозиторію через .gitignore.

З топіками й data-payload ви отримуєте гнучку маршрутизацію: новини, підписникам /topics/news, персональні повідомлення, за токеном, тиху синхронізацію, через data-only message. Увесь цей функціонал безплатний і працює на Android, iOS та у вебі з одного PHP-скрипту.

Перевірте поточний код надсилання сповіщень у вашому проєкті прямо зараз. Якщо там досі Authorization: key=, оновіть на HTTP v1 API. Запитання й нюанси інтеграції пишіть у коментарях.