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) — жизненный цикл токенов, реактивная очистка и путь отправки