FCM за Android — стъпка по стъпка
YS Board ver15 · 14.11.2026. Това ръководство е за готовото APK с пакет bg.ysboard и за таба Администраторски достъп → FCM известия. Имената на Google менютата са дадени на английски; преводът и разположението може да се променят.
1. Какво е необходимо
Използвайте фирмен Google акаунт с достъп до избрания Firebase/Google Cloud проект. На Android телефона са нужни Google Play services, интернет, инсталиран YS Board APK и разрешени известия. Raspberry Pi също трябва да има изходящ HTTPS достъп до Google. Самият чат може да остане достъпен само през локалната мрежа; телефонът трябва да достига адреса му, когато отваря съобщенията.
FCM е транспортът за Android APK. iPhone и браузърите използват отделния web push. Не създавайте Apple приложение, APNs сертификат или web push VAPID ключ във Firebase за тази настройка. YS Board вече има свой web push ключ. Телефони без Google услуги могат да използват съществуващите UnifiedPush/FETCH опции.
Съобщението за push включва заглавие и кратък откъс от текста. При FCM тази информация преминава през Google. Чатовете и качените файлове продължават да се пазят в PostgreSQL и файловата директория на вашия YS Board сървър; тук не настройваме Firestore или Realtime Database.
2. Отваряне на конзолата и създаване на проект
- Отворете Firebase Console и влезте с избрания Google акаунт. Проверете профилната икона горе вдясно, за да не работите случайно с личен акаунт.
- Ако вече имате правилния фирмен проект, отворете него. Иначе изберете Create a project / Add project и задайте разбираемо име, например
YS Board. - Вижте предложения Project ID, например
ys-board-company. Това е техническият идентификатор, различен от името за показване. Запишете го. Ако включвате Firebase към съществуващ Google Cloud проект, изберете именно него. - Google Analytics не е необходим за изпращането от YS Board; можете да пропуснете тази незадължителна стъпка. Завършете създаването и отворете проекта.
- Зъбното колело до Project Overview → Project settings → General показва Project ID и Project number. Последното е число, използвано като Sender ID. Проверявайте проекта в горната лента и при всяко преминаване към Google Cloud Console.
Официална справка: създаване на Firebase проект и незадължителен Analytics. Следващите стъпки са за Android приложението.
3. Регистриране на готовото Android приложение
- В Project settings → General → Your apps натиснете Android иконата или Add app → Android.
- В Android package name въведете точно
bg.ysboard. Не въвеждайте адреса на сайта, името на APK файла или произволно фирмено име. Пакетът вече е зададен в готовото APK. - За App nickname можете да напишете
YS Board Android. Това е етикет в конзолата. - SHA-1 не е нужен за основната FCM настройка. Ако по-късно ограничавате API ключа до подпис на APK, използвайте сертификата, с който е подписано действително инсталираното приложение. Тестовият пакет ver5 е със същия тестов подпис като предишните версии.
- Натиснете Register app, след което Download google-services.json. Отворете файла с текстов редактор. Той съдържа клиентските настройки, а не частния сървърен ключ.
- Конзолата може да покаже инструкции за Android Studio, Gradle plugin и поставяне на файла в
app/. Готовото YS Board APK чете настройките при вход от сървъра, затова за него попълвате полетата в админ таба. Не е нужно да компилирате собствен APK само заради тези стойности.
Източник: официална регистрация на Android приложение.
4. Четирите клиентски полета
В google-services.json намерете блока от масива client, в който client_info.android_client_info.package_name е bg.ysboard. Ако файлът съдържа няколко приложения, вземете данните именно от този блок.
| Поле в YS Board | Стойност в google-services.json |
|---|---|
| Project ID | project_info.project_id |
| Sender ID / Project number | project_info.project_number |
| Android App ID | client[…].client_info.mobilesdk_app_id |
| Firebase API key (клиентски) | client[…].api_key[0].current_key |
App ID изглежда като 1:1234567890:android:abcdef012345; числото след 1: трябва да е същото като Sender ID. Копирайте стойностите без обгръщащите JSON кавички и без запетаята след тях. Ако няма api_key, проверете настройките за API credentials на проекта и изтеглете актуалния файл; не измисляйте стойност.
Firebase API key идентифицира клиентския проект и се предоставя на APK при вход. Той не замества частния Service account ключ. Оставете подходящите ограничения до Firebase API услуги; не използвайте за това ключ за друга платена Google услуга. При допълнителни Android ограничения трябва да съвпадат пакетът и подписващият сертификат. Вижте официалните указания за Firebase API ключове и ограничения.
5. Включване на правилния FCM API
- В Firebase отворете Project settings → Cloud Messaging. Проверете секцията Firebase Cloud Messaging API (V1).
- Ако API не е включен, използвайте връзката за управление в Google Cloud. Можете и директно да отворите Google Cloud Console, да изберете същия проект и да потърсите Firebase Cloud Messaging API в APIs & Services → Library.
- Отворете резултата за
fcm.googleapis.comи натиснете Enable. При вече активен API ще виждате управление/статистика вместо Enable.
YS Board използва HTTP v1 с краткоживеещ OAuth access token, получен от сървърния Service account ключ. Полето за стар Legacy Server Key не е нужно. Не въвеждайте ключа на браузърния web push сертификат в Android полетата. Справка: изпращане и сървърно удостоверяване по FCM HTTP v1.
6. Service account — частният сървърен ключ
Това е чувствителният файл, който разрешава на Raspberry Pi да изпраща известия от проекта. В YS Board той се поставя целият в Нов Service account JSON. Не се поставя в APK и не се раздава на служителите.
Вариант A: от Firebase Console
- Отворете Project settings → Service accounts, секцията Firebase Admin SDK.
- Натиснете Generate new private key и потвърдете Generate key.
- Запазете изтегления JSON в защитено място и го отворете с текстов редактор. Проверете, че съдържа
"type": "service_account", правилнияproject_id,client_emailиprivate_key.
Този път е описан в инструкциите на Firebase за частен ключ на сървър. Проверете правата на акаунта; готовият Firebase Admin акаунт може да има по-широки права от нужните за push.
Вариант B: отделен акаунт само за YS Board FCM
- В Google Cloud Console изберете същия проект. Отворете IAM & Admin → Service Accounts → Create service account.
- Дайте име например
ysboard-push. При задаване на права върху проекта изберете Firebase Cloud Messaging API Admin —roles/firebasecloudmessaging.admin. За този сценарий не е нужно да давате Owner/Editor върху целия проект. - Завършете създаването. Отворете акаунта от списъка, после Keys → Add key → Create new key → JSON → Create.
- Отворете изтегления файл. Всяко поле трябва да остане в оригиналния JSON, включително кавичките и escape последователностите
\nв частния ключ.
Справки: FCM роли и създаване и изтриване на Service account ключове. Ако фирмена организационна политика забранява създаването на ключове, обърнете се към администратора на Google Cloud организацията за одобрен начин на достъп.
7. Въвеждане в YS Board
- Отворете YS Board по доверен HTTPS адрес. Влезте като един от тримата администратори.
- Изберете Администраторски достъп, въведете собствената си парола и отворете таба FCM известия.
- Попълнете четирите клиентски полета от стъпка 4. Всички трябва да сочат един и същ Firebase проект.
- В Нов Service account JSON поставете цялото съдържание на частния JSON файл, от отварящата до затварящата фигурна скоба. Не поставяйте само текста между BEGIN/END PRIVATE KEY.
- Отбележете Включи изпращането през FCM и натиснете Запази FCM настройките.
- При успех полето за частния JSON се изчиства. Над него трябва да пише Има запазен ключ и да се вижда email на Service account. Това не е изгубен ключ — той не се връща в браузъра.
Записването проверява формата, частния ключ и съответствието на проектите локално. То не проверява онлайн IAM правата, разрешения API или реалната доставка до телефон. Не е нужен рестарт на услугата след успешно запазване. Празно поле за JSON при следващ запис запазва ключа. Махането на отметката спира бъдещото FCM изпращане, като запазва настройките.
Ключът се пази шифрован в базата. За възстановяване са необходими както базата, така и data/secret.key. Нормалният пълен бекъп на YS Board включва и двете. Журналът записва административната промяна, без самия частен ключ, API ключ или device token.
8. Настройка на Android и проба
- Инсталирайте
YS_Board_ver8.apkвърху предишното тестово приложение. Разрешете известията в Android. - Отворете APK, проверете HTTPS адреса на YS Board и влезте. След промяна на FCM настройките отворете приложението отново/презаредете страницата, за да се получат актуалните клиентски данни.
- В личните Настройки → Android: FCM / UnifiedPush / FETCH изберете FCM (Google услуги). Този избор е за конкретния телефон.
- Проверете дали в съответния чат са разрешени push известия и дали зададеният часови диапазон включва текущия час.
- Оставете APK във фон с Home. От друг потребител, на друг браузър/телефон, изпратете ново съобщение в общ чат или в личен разговор към тестовия получател.
- Проверете системното известие и отварянето на правилния чат. Не използвайте Android Force stop за тази проба — след принудително спиране отворете приложението отново.
YS Board не изпраща push към самия автор. Получаването на push не отбелязва съобщението като прочетено. Във foreground APK използва живото обновяване на чата, а системният банер може да бъде потиснат, за да няма дублиране.
9. Ако няма известие
- „Има запазен ключ“, но няма push: това показва локално запазена конфигурация. Проверете API, IAM правата, интернет достъпа на Pi и телефона, Google Play services и настройката FCM в APK. В Android Settings → Apps → YS Board → Notifications разрешете известията и канала им. Вижте също Do Not Disturb и ограниченията за батерията на производителя.
- Невалиден JSON: нужен е Service account JSON.
google-services.jsonе за четирите клиентски полета. Не добавяйте Markdown ограждения и не променяйте\nв ключа. - Несъвпадение на проекти/Sender ID: изтеглете конфигурацията от правилното Android приложение
bg.ysboard. Ключът, Project ID, Sender ID и App ID трябва да са от един проект. - FCM 401/403: при външна диагностика тези отговори обикновено сочат удостоверяване, права или неактивен API. Проверете дали ключът не е изтрит/деактивиран, дали Service account има FCM правото и дали часът на Pi е точен. Обикновеният журнал на YS Board не записва подробни технически HTTP отговори.
- SENDER_ID_MISMATCH / UNREGISTERED: първото насочва към различни проекти, второто към остаряла регистрация на приложението. След корекция отворете APK и изберете FCM отново; сървърът премахва регистрации, които Google изрично отчита като UNREGISTERED. Вижте официалните FCM грешки.
- Само тестът от същия акаунт не работи: изпратете от друг акаунт. Проверете и дали съобщението вече не е прочетено от друг отворен клиент на получателя.
- iPhone няма push: тази FCM настройка не е за iPhone. Добавете YS Board на началния екран, стартирайте го от иконата и включете web push от личните настройки. Нужни са доверен HTTPS и разрешение за известия. Декларативният формат вече се изпраща; вижте обяснението на WebKit.
10. Смяна на ключ, проект или сървър
Нов ключ в същия проект: генерирайте го, поставете целия нов JSON и запазете. След успешна реална проба можете да отнемете стария ключ в Google Cloud. Не изтривайте работещия ключ преди да имате проверен заместник. Ако ключ е изтекъл, отнемете го в Google Cloud и подменете конфигурацията.
Друг Firebase проект: сменете четирите клиентски полета и частния JSON заедно. Отворете отново всяко APK, за да получи новата конфигурация и да направи нова FCM регистрация. Ново компилиране само за конфигурацията не е необходимо.
Преместване на YS Board: възстановете пълния бекъп с база, конфигурация, изображения и ключове, включително secret.key. Настройката от ver5 се пренася с базата. Предишни инсталации с firebase и fcm_service_account в конфигурационния файл продължават да ги използват до първия запис от новия таб; след това записът в базата има предимство.
Бутонът „Изтрий web push“: той изчиства само браузърните web push регистрации на избрания потребител, от всички негови устройства. Не засяга FCM, UnifiedPush, входа и съобщенията. Нови web push съобщения няма да се изпращат до повторно активиране от личните настройки; вече подадено към доставчика известие може да пристигне. Системното разрешение в браузъра не се премахва дистанционно.
← Обща помощ и история на версиите
Хелп при миграция на YS Board
При нов Board URL FCM не се настройва с OAuth redirect URI. Ако Firebase проектът, Android app и подписът се запазват, не създавайте нов проект или JSON ключ заради домейна.
- Пренесете PostgreSQL/settings, data и secret.key; запишете новия public_url на Board и рестартирайте услугата.
- В FCM таба проверете project_id/app_id/api_key/sender_id и статуса на запазения service account. Частният JSON не трябва да се вижда след запис.
- В APK: Настройки → Android: FCM / UnifiedPush / FETCH → Адрес на сървъра → новия основен HTTPS адрес → Отвори → нов вход → изберете FCM.
- Google Cloud промяна е нужна при реална смяна на Firebase app/проект/ключ или Android package/certificate restrictions, а не само заради нов Board домейн.
- Пробвайте получаване на push на заден план и отваряне на правилния чат. Browser/PWA web push е отделен и се регистрира отново за новия origin.
Пълното ръководство за миграция, общите Board стъпки и проверките за тази услуга.