Google Calendar API за обикновен Gmail
Версия 15 използва един фирмен Google акаунт и един избран календар за месечен изглед, четене, създаване, редакция, изтриване и покани. OAuth иска calendar.events (четене и запис) и calendar.calendarlist.readonly. Съществуващата връзка от версия 12 се запазва, ако тези права вече са дадени. Не се изисква Google Workspace. Точните адреси чрез Google Maps се настройват отделно.
1. Изберете фирмения календар
Отворете Google Calendar с Gmail акаунта, който го управлява. Проверете кой календар трябва да се вижда в YS Board. Може да е основният или отделен фирмен календар. Всеки логнат потребител на YS Board ще вижда заглавията и часовете от него. Потребителите не свързват личните си Google акаунти на този етап.
2. Отворете Google Cloud
- От компютър отворете Google Cloud Console и влезте с Gmail акаунта.
- Горе изберете проект от селектора. Можете да използвате проекта за FCM или да създадете отделен, например YS Board. Името на проекта е за ваше удобство.
- От менюто отворете APIs & Services → Library. Потърсете Google Calendar API, отворете го и натиснете Enable. Ако пише Manage, API вече е включен.
3. Настройте Google Auth Platform
- Отворете Google Auth Platform. При първо отваряне изберете Get started. При по-стар изглед секцията може да се казва OAuth consent screen.
- В Branding въведете име YS Board, User support email и контактния имейл на разработчика. За този личен тест не е нужно да качвате лого в Google.
- В Audience изберете External. Обикновен Gmail не използва Internal.
- За началните тестове оставете статус Testing. В Test users → Add users добавете точния Gmail адрес, с който ще свържете календара. Не добавяйте всички служители — само акаунта, който ще даде достъп.
- В Data Access → Add or remove scopes добавете двете права по-долу. Може да ги намерите чрез Calendar API или да въведете адресите ръчно. Запазете.
https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.calendarlist.readonly
Първото позволява четене и промяна на събития. Второто позволява избор от наличните календари. Не се иска пълното право за управление, споделяне и изтриване на самите календари. Описание: официални Calendar API права.
4. Създайте Web application OAuth клиент
- Отворете YS Board в обикновен браузър на публичния му HTTPS адрес. Влезте като администратор → Администраторски достъп → Календар. Включете чекчето и изберете тип 2. Не натискайте общото Запази още; действащият ICS ще продължи да работи.
- Копирайте целия адрес от Authorized redirect URI за Google Cloud. Той се извежда от настройката public_url на сървъра. Ако полето е празно, първо трябва да се зададе публичен HTTPS адрес с домейн; локално IP не е подходящ OAuth callback.
- В Google Cloud → Google Auth Platform → Clients → Create client изберете Web application. Дайте име, например YS Board Calendar.
- В Authorized redirect URIs натиснете Add URI и поставете копирания адрес без промяна. Това е пълният адрес с
/api/admin/calendar/google/callback, без допълнителна наклонена черта. Полето Authorized JavaScript origins не е нужно за този сървърен flow. - Създайте клиента и изтеглете OAuth JSON файла. Може да е бутон Download JSON / Download client от страницата на клиента. Това е JSON с корен
web, Client ID и Client secret. Не използвайте FCM Service account JSON, google-services.json или Android client. - Отворете JSON файла като текст и поставете съдържанието в OAuth client JSON в YS Board. Натиснете Запази ключовете. Полето се изчиства; секретът не се показва обратно.
При текущия публичен адрес callback е:
https://ysboard.yanaksoft-callcenter.workers.dev/api/admin/calendar/google/callback
Ако смените публичния адрес на сървъра, използвайте новото поле в панела и обновете URI в Google Cloud. Използвайте един и същ адрес на YS Board за начало и край на свързването.
5. Свържете акаунта
- В YS Board натиснете Свържи с Google. Браузърът отваря Google.
- Изберете Gmail акаунта на фирмения календар. Ако Google показва предупреждение за ваше непроверено тестово приложение, проверете дали това е вашият OAuth клиент и проект. Продължете само ако ги разпознавате.
- Разрешете и двете поискани права, включително запис на събития. Само отметнато четене не е достатъчно за тази конфигурация.
- След връщане в YS Board ще се отвори табът Календар. Натиснете Зареди календарите и изберете фирмения календар. Календари с reader права са обозначени „само за четене“; за създаване/редакция/изтриване е нужен writer/owner достъп.
- Оставете включено „Използвай календар“, тип 2, и натиснете общото Запази. Едва тогава Google API замества ICS като активен източник. Запазеният ICS адрес остава за евентуално връщане към тип 1.
Свързването има 10 минути срок и трябва да приключи, докато администраторският достъп е активен. Не го стартирайте от APK WebView: Google OAuth използва обикновен браузър и неговите cookies. След свързване календарът се вижда от всички поддържани браузъри, PWA и APK без отделно Google влизане.
6. Какво ще виждат служителите
Под папките и чатовете се показват „+ събитие“ и „календар“, „Ваши събития“ и „Всички събития“ за днес и утре по София. Личният филтър все още е по пълното име за показване в заглавието, а не по логин или Google имейл. Например „Мария среща Георги“ е лично събитие и за двамата. Приключилите събития остават по-бледи само в общия списък; личният показва предстоящите и текущите.
Повтарящите се събития се развиват от Google за двата дни. Целодневните събития ползват изключваща крайна дата. В кратките списъци остават само заглавия/часове. При отваряне на Google събитие се зареждат описание, локация и избраните YS Board участници; правата контролират промяната, не прегледа. Месечният изглед показва общия избран календар.
Има един общ сървърен кеш за 5 минути, а видимите клиенти проверяват веднъж на минута. При временен проблем има предупреждение и последни данни до 24 часа само от същия избран календар. При смяна на акаунт/календар старите данни се отхвърлят. Проверките не създават технически журнал и не удължават административния достъп.
„+ събитие“ отваря формата за нова среща. „календар“ показва месеца; дата създава, събитие отваря същата форма за редакция. Под началото са крайна дата/час, по подразбиране +1 час. Цял ден включва крайната дата. Администраторите въвеждат имейли за поканените, управляват Групи за събития и петте отделни права. Липсващ имейл отказва запис. При конфликт Не връща непокътнатата форма. Поканите се изпращат с успешната Google операция.
7. Testing и дългосрочна работа
В Google статус Testing достъпът с тези Calendar права обичайно има refresh token със срок 7 дни. След това ще е нужно повторно свързване. Това е ограничение на Google, а не изтичане на YS Board сесията. За постоянна експлоатация трябва да се подготви Production конфигурация според изискванията на Google, включително евентуална проверка на приложението/домейна. Самото превключване на Production не гарантира, че всички изисквания са изпълнени. За първия тест използваме Test users.
Google може да отнеме достъп и след промяна на разрешенията, изтриване на OAuth клиент или ръчно премахване на приложението от акаунта. Повторното свързване е през същия администраторски таб. Вижте срокове и отнемане на OAuth достъп и официалната схема за Web server OAuth.
8. Чести проблеми
- redirect_uri_mismatch: сравнете URI в Google Cloud с read-only полето на YS Board — схема, домейн, път и крайна наклонена черта трябва да съвпадат.
- access_denied / неразрешен тестов потребител: добавете точния Gmail в Audience → Test users и проверете правилния Cloud проект.
- Google отказва API: включете Google Calendar API в проекта на OAuth клиента и дайте всички поискани права.
- Изтекъл опит: използвайте същия обикновен браузър, cookies и адрес на YS Board, влезте отново в административния панел и започнете нов опит.
- Няма календар: проверете в Google Calendar дали акаунтът има достъп поне за четене. Само free/busy достъп не е достатъчен.
- Няма лично събитие: проверете днешна/утрешна дата, крайния час и пълното име за показване в заглавието.
Премахни връзката от YS Board изтрива локално запазените токени и избора на календар. Не изтрива Google събития, ICS адреса или OAuth ключовете. За пълно отнемане на даденото в Google разрешение използвайте настройките за достъп на самия Google акаунт. Архивите могат да съдържат по-стари шифровани конфигурации; пазете ги като фирмени данни.
Хелп при миграция на YS Board
При смяна на домейна обновете OAuth callback адреса в същия Web application client.
- Новият Board адрес → Администраторски достъп → Календар → копирайте показания Redirect URI.
- Google Cloud Console → изберете проекта → Google Auth Platform → Clients (или APIs & Services → Credentials) → правилния Web application client → Authorized redirect URIs.
- Добавете
https://НОВИЯТ-ДОМЕЙН/api/admin/calendar/google/callbackс действителния домейн и Save. HTTPS/порт/път трябва да съвпадат точно, без допълнителна наклонена черта. - Обновете public_url в Board конфигурацията и рестартирайте услугата. Прегледайте Google Auth Platform → Branding за App domain/home/privacy/terms, ако още сочат стария домейн.
- Пазете същите client ID/secret и пренесените шифровани settings + secret.key. Не презаписвайте JSON само заради URL — това прекратява локалната връзка. Повторно свързване се прави при нужда от обикновен браузър на новия адрес.
- Проверете избрания календар, включения Google режим и Днес/Утре/месечния изглед. При redirect_uri_mismatch сравнете точния показан адрес с URI в правилния client.
Пълното ръководство за миграция, общите Board стъпки и проверките за тази услуга.