Push-сповіщення через FCM (Ring)

Ring Platform зберігає FCM-токени в основній базі даних (PostgreSQL або Firestore залежно від режиму бекенду) — по одному запису на користувача та пристрій. React-додатки реєструють токени через Server Action; інші клієнти використовують API з обмеженням частоти. Обидва шляхи викликають один і той самий серверний шар БД, тому поводження та безпека скрізь однакові.

Огляд: логіка FCM у Ring

«Ring-powered» FCM — це єдина, незалежна від бекенду схема:

• Сховище токенів як джерело істини — Таблиця (або колекція) fcm_tokens зберігає всі токени реєстрації. Корисне навантаження зберігається в колонці JSONB data де застосовно (PostgreSQL). Окремого кешу немає; реєстром слугує БД.
• Один рядок на пристрій і користувача — Складне унікальне обмеження по (user_id, device_fingerprint) дає один запис на пристрій. Значення токена не унікальне, тому при ротації FCM-токена оновлюється той самий рядок, а не створюється дублікат.
• React-додаток → Server Action — Основний шлях для браузера та React Native web — Server Action upsertFcmToken. Ідентифікатор користувача сервер бере лише з auth(); клієнт його не передає.
• Інші клієнти → API — Мобільні додатки або зовнішні сервіси викликають POST /api/notifications/fcm/register з тим самим тілом запиту. Цей endpoint обмежений по частоті на користувача (наприклад, 10 запитів на хвилину).
• Життєвий цикл у даних — У кожному рядку зберігаються status (active | stale | invalid) та invalidatedAt. Реактивне очищення спрацьовує при помилках FCM по токену; за розкладом позначаються застарілі токени та за потреби виконується жорстке видалення.
• Режим бекенду — Сховище токенів не прив’язане до конкретного бекенду. BackendSelector направляє запити по DB_BACKEND_MODE у PostgreSQL (наприклад k8s-postgres-fcm, supabase-fcm) або Firestore (firebase-full). Один код; розгалужень у Server Action чи API немає.

Push-сповіщення через FCM (Ring)

Ring Platform зберігає FCM-токени в основній базі даних (PostgreSQL або Firestore залежно від режиму бекенду) — по одному запису на користувача та пристрій. React-додатки реєструють токени через Server Action; інші клієнти використовують API з обмеженням частоти. Обидва шляхи викликають один і той самий серверний шар БД, тому поводження та безпека скрізь однакові.

Огляд: логіка FCM у Ring

«Ring-powered» FCM — це єдина, незалежна від бекенду схема:

• Сховище токенів як джерело істини — Таблиця (або колекція) fcm_tokens зберігає всі токени реєстрації. Корисне навантаження зберігається в колонці JSONB data де застосовно (PostgreSQL). Окремого кешу немає; реєстром слугує БД.
• Один рядок на пристрій і користувача — Складне унікальне обмеження по (user_id, device_fingerprint) дає один запис на пристрій. Значення токена не унікальне, тому при ротації FCM-токена оновлюється той самий рядок, а не створюється дублікат.
• React-додаток → Server Action — Основний шлях для браузера та React Native web — Server Action upsertFcmToken. Ідентифікатор користувача сервер бере лише з auth(); клієнт його не передає.
• Інші клієнти → API — Мобільні додатки або зовнішні сервіси викликають POST /api/notifications/fcm/register з тим самим тілом запиту. Цей endpoint обмежений по частоті на користувача (наприклад, 10 запитів на хвилину).
• Життєвий цикл у даних — У кожному рядку зберігаються status (active | stale | invalid) та invalidatedAt. Реактивне очищення спрацьовує при помилках FCM по токену; за розкладом позначаються застарілі токени та за потреби виконується жорстке видалення.
• Режим бекенду — Сховище токенів не прив’язане до конкретного бекенду. BackendSelector направляє запити по DB_BACKEND_MODE у PostgreSQL (наприклад k8s-postgres-fcm, supabase-fcm) або Firestore (firebase-full). Один код; розгалужень у Server Action чи API немає.

Push-сповіщення через FCM (Ring)

Ring Platform зберігає FCM-токени в основній базі даних (PostgreSQL або Firestore залежно від режиму бекенду) — по одному запису на користувача та пристрій. React-додатки реєструють токени через Server Action; інші клієнти використовують API з обмеженням частоти. Обидва шляхи викликають один і той самий серверний шар БД, тому поводження та безпека скрізь однакові.

Огляд: логіка FCM у Ring

«Ring-powered» FCM — це єдина, незалежна від бекенду схема:

• Сховище токенів як джерело істини — Таблиця (або колекція) fcm_tokens зберігає всі токени реєстрації. Корисне навантаження зберігається в колонці JSONB data де застосовно (PostgreSQL). Окремого кешу немає; реєстром слугує БД.
• Один рядок на пристрій і користувача — Складне унікальне обмеження по (user_id, device_fingerprint) дає один запис на пристрій. Значення токена не унікальне, тому при ротації FCM-токена оновлюється той самий рядок, а не створюється дублікат.
• React-додаток → Server Action — Основний шлях для браузера та React Native web — Server Action upsertFcmToken. Ідентифікатор користувача сервер бере лише з auth(); клієнт його не передає.
• Інші клієнти → API — Мобільні додатки або зовнішні сервіси викликають POST /api/notifications/fcm/register з тим самим тілом запиту. Цей endpoint обмежений по частоті на користувача (наприклад, 10 запитів на хвилину).
• Життєвий цикл у даних — У кожному рядку зберігаються status (active | stale | invalid) та invalidatedAt. Реактивне очищення спрацьовує при помилках FCM по токену; за розкладом позначаються застарілі токени та за потреби виконується жорстке видалення.
• Режим бекенду — Сховище токенів не прив’язане до конкретного бекенду. BackendSelector направляє запити по DB_BACKEND_MODE у PostgreSQL (наприклад k8s-postgres-fcm, supabase-fcm) або Firestore (firebase-full). Один код; розгалужень у Server Action чи API немає.

Передумови

• Аутентифікація — Виконано вхід (сесія Auth.js). Реєстрація токена завжди прив’язана до аутентифікованого користувача; сервер не довіряє ідентифікатору користувача від клієнта.
• Web Push (браузер) — HTTPS (або localhost під час розробки), підтримка Web Push у браузері, зареєстрований service worker та Firebase client SDK. Файл service worker зазвичай доступний за /firebase-messaging-sw.js.
• API-клієнти — Діюча сесія (cookie або Bearer) та той самий контракт тіла запиту (token, deviceFingerprint, deviceInfo).

React-додаток: шлях через Server Action

Використовуйте Server Action як основний спосіб реєстрації та оновлення FCM-токенів з будь-якого React- або Next.js-клієнта. Цей шлях не обмежений по частоті, на відміну від API, і ідентифікатор користувача лишається лише на сервері.

Передумови

• Аутентифікація — Виконано вхід (сесія Auth.js). Реєстрація токена завжди прив’язана до аутентифікованого користувача; сервер не довіряє ідентифікатору користувача від клієнта.
• Web Push (браузер) — HTTPS (або localhost під час розробки), підтримка Web Push у браузері, зареєстрований service worker та Firebase client SDK. Файл service worker зазвичай доступний за /firebase-messaging-sw.js.
• API-клієнти — Діюча сесія (cookie або Bearer) та той самий контракт тіла запиту (token, deviceFingerprint, deviceInfo).

React-додаток: шлях через Server Action

Використовуйте Server Action як основний спосіб реєстрації та оновлення FCM-токенів з будь-якого React- або Next.js-клієнта. Цей шлях не обмежений по частоті, на відміну від API, і ідентифікатор користувача лишається лише на сервері.

Передумови

• Аутентифікація — Виконано вхід (сесія Auth.js). Реєстрація токена завжди прив’язана до аутентифікованого користувача; сервер не довіряє ідентифікатору користувача від клієнта.
• Web Push (браузер) — HTTPS (або localhost під час розробки), підтримка Web Push у браузері, зареєстрований service worker та Firebase client SDK. Файл service worker зазвичай доступний за /firebase-messaging-sw.js.
• API-клієнти — Діюча сесія (cookie або Bearer) та той самий контракт тіла запиту (token, deviceFingerprint, deviceInfo).

React-додаток: шлях через Server Action

Використовуйте Server Action як основний спосіб реєстрації та оновлення FCM-токенів з будь-якого React- або Next.js-клієнта. Цей шлях не обмежений по частоті, на відміну від API, і ідентифікатор користувача лишається лише на сервері.

Приклад: реєстрація та оновлення токена в клієнтському компоненті.

Інші клієнти: API

Мобільні додатки та інші клієнти без React реєструють токени через той самий контракт по HTTP.

Endpoint: POST /api/notifications/fcm/register

Тіло запиту:

• token (string, обов’язково) — FCM registration token з клієнтського SDK.
• deviceFingerprint (string, обов’язково) — Стабільний ідентифікатор пристрою (наприклад UUID у local storage). Не більше 128 символів; лише літери, цифри, дефіс та підкреслення.
• deviceInfo (object, необов’язково) — Довільні метадані пристрою (наприклад platform, userAgent).

Аутентифікація: Обов’язкова (session cookie або Bearer). Сервер використовує ідентифікатор аутентифікованого користувача; не передавайте userId у тілі.

Відповіді:

• 200 — { "success": true }
• 400 — Помилка валідації (наприклад відсутній або невірний deviceFingerprint)
• 401 — Не аутентифіковано
• 429 — Перевищено ліміт запитів (заголовок Retry-After)
• 500 — Помилка сервера

Приклад: реєстрація та оновлення токена в клієнтському компоненті.

Інші клієнти: API

Мобільні додатки та інші клієнти без React реєструють токени через той самий контракт по HTTP.

Endpoint: POST /api/notifications/fcm/register

Тіло запиту:

• token (string, обов’язково) — FCM registration token з клієнтського SDK.
• deviceFingerprint (string, обов’язково) — Стабільний ідентифікатор пристрою (наприклад UUID у local storage). Не більше 128 символів; лише літери, цифри, дефіс та підкреслення.
• deviceInfo (object, необов’язково) — Довільні метадані пристрою (наприклад platform, userAgent).

Аутентифікація: Обов’язкова (session cookie або Bearer). Сервер використовує ідентифікатор аутентифікованого користувача; не передавайте userId у тілі.

Відповіді:

• 200 — { "success": true }
• 400 — Помилка валідації (наприклад відсутній або невірний deviceFingerprint)
• 401 — Не аутентифіковано
• 429 — Перевищено ліміт запитів (заголовок Retry-After)
• 500 — Помилка сервера

Приклад: реєстрація та оновлення токена в клієнтському компоненті.

Інші клієнти: API

Мобільні додатки та інші клієнти без React реєструють токени через той самий контракт по HTTP.

Endpoint: POST /api/notifications/fcm/register

Тіло запиту:

• token (string, обов’язково) — FCM registration token з клієнтського SDK.
• deviceFingerprint (string, обов’язково) — Стабільний ідентифікатор пристрою (наприклад UUID у local storage). Не більше 128 символів; лише літери, цифри, дефіс та підкреслення.
• deviceInfo (object, необов’язково) — Довільні метадані пристрою (наприклад platform, userAgent).

Аутентифікація: Обов’язкова (session cookie або Bearer). Сервер використовує ідентифікатор аутентифікованого користувача; не передавайте userId у тілі.

Відповіді:

• 200 — { "success": true }
• 400 — Помилка валідації (наприклад відсутній або невірний deviceFingerprint)
• 401 — Не аутентифіковано
• 429 — Перевищено ліміт запитів (заголовок Retry-After)
• 500 — Помилка сервера

Приклад з cURL (підставте cookie сесії або Bearer згідно з вашою налаштуванням auth):

Змінні середовища

Налаштування розділені так, щоб на клієнт потрапляли лише публічні та безпечні значення.

Приклад з cURL (підставте cookie сесії або Bearer згідно з вашою налаштуванням auth):

Змінні середовища

Налаштування розділені так, щоб на клієнт потрапляли лише публічні та безпечні значення.

Приклад з cURL (підставте cookie сесії або Bearer згідно з вашою налаштуванням auth):

Змінні середовища

Налаштування розділені так, щоб на клієнт потрапляли лише публічні та безпечні значення.

Зняття реєстрації та вихід

При виході або вимкненні push користувачем:

• Браузер / React — Викличте deleteToken(messaging) з Firebase client SDK, потім зніміть реєстрацію на сервері: DELETE /api/notifications/fcm/register з тілом { "deviceFingerprint": "same-uuid-as-register" }. Ідемпотентно; можна викликати навіть якщо запис уже видалено або інвалідовано.
• Інші клієнти — Той самий запит DELETE з тим самим deviceFingerprint, що й при реєстрації.

Сервер позначає рядок як status: 'invalid' і встановлює invalidatedAt; доставка на цей токен припиняється.

Усунення несправностей

Зняття реєстрації та вихід

При виході або вимкненні push користувачем:

• Браузер / React — Викличте deleteToken(messaging) з Firebase client SDK, потім зніміть реєстрацію на сервері: DELETE /api/notifications/fcm/register з тілом { "deviceFingerprint": "same-uuid-as-register" }. Ідемпотентно; можна викликати навіть якщо запис уже видалено або інвалідовано.
• Інші клієнти — Той самий запит DELETE з тим самим deviceFingerprint, що й при реєстрації.

Сервер позначає рядок як status: 'invalid' і встановлює invalidatedAt; доставка на цей токен припиняється.

Усунення несправностей

Зняття реєстрації та вихід

При виході або вимкненні push користувачем:

• Браузер / React — Викличте deleteToken(messaging) з Firebase client SDK, потім зніміть реєстрацію на сервері: DELETE /api/notifications/fcm/register з тілом { "deviceFingerprint": "same-uuid-as-register" }. Ідемпотентно; можна викликати навіть якщо запис уже видалено або інвалідовано.
• Інші клієнти — Той самий запит DELETE з тим самим deviceFingerprint, що й при реєстрації.

Сервер позначає рядок як status: 'invalid' і встановлює invalidatedAt; доставка на цей токен припиняється.

Усунення несправностей

Див. також

• Сповіщення — Типи сповіщень, канали та налаштування
• Схема та міграції для fcm_tokens (наприклад data/schema.sql, data/migrations/fcm_jsonb_schema.sql) у вашому клоні Ring
• Truth lens FCM-фахівця (AI-LEGIOX/legiox-truth-lens/fcm-specialist.json) — життєвий цикл токенів, реактивне очищення та шлях відправки

Див. також

• Сповіщення — Типи сповіщень, канали та налаштування
• Схема та міграції для fcm_tokens (наприклад data/schema.sql, data/migrations/fcm_jsonb_schema.sql) у вашому клоні Ring
• Truth lens FCM-фахівця (AI-LEGIOX/legiox-truth-lens/fcm-specialist.json) — життєвий цикл токенів, реактивне очищення та шлях відправки

Див. також

• Сповіщення — Типи сповіщень, канали та налаштування
• Схема та міграції для fcm_tokens (наприклад data/schema.sql, data/migrations/fcm_jsonb_schema.sql) у вашому клоні Ring
• Truth lens FCM-фахівця (AI-LEGIOX/legiox-truth-lens/fcm-specialist.json) — життєвий цикл токенів, реактивне очищення та шлях відправки