Справочник по сторонним интеграциямTigerTag Firebase Integration

Как клиент подключается к TigerTag

Каждый клиент выполняет одни и те же четыре шага: получает публичную конфигурацию Firebase, входит от имени пользователя, вызывает Firestore REST API с токеном пользователя и поддерживает этот токен актуальным.

1. 1

   Получите публичную конфигурацию

   Один GET-запрос возвращает конфигурацию проекта Firebase. apiKey публичен по замыслу: он идентифицирует проект, а не вызывающую сторону. Кэшируйте его; обновления раз в неделю достаточно.

   01-firebase-config.md
2. 2

   Войдите от имени пользователя

   Собственные адрес электронной почты и пароль пользователя возвращают UID, idToken на 1 час и refreshToken. Google Sign-In требует браузера, поэтому клиенты без интерфейса используют пароль.

   02-authentication.md
3. 3

   Чтение и запись в Firestore

   Передавайте idToken как Bearer-токен. Катушки хранятся в users/{uid}/inventory, стеллажи — в users/{uid}/racks; вес указывается нетто в граммах, даты — в миллисекундах Unix.

   03-data-model.md
4. 4

   Поддерживайте токен актуальным

   Обновляйте idToken до истечения часа и заменяйте оба сохранённых токена. При ошибке permission-denied обновите токен один раз и один раз повторите чтение.

   Обновление idToken

GET  https://tigertag-cdn.web.app/__/firebase/init.json

POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={apiKey}
     { "email": "user@example.com", "password": "…", "returnSecureToken": true }

GET  https://firestore.googleapis.com/v1/projects/{projectId}/databases/(default)/documents/users/{uid}/inventory
     Authorization: Bearer {idToken}

Интеграции, описанные в этом репозитории

Каждое руководство в docs/clients охватывает аутентификацию, читаемые или записываемые данные, сопоставление полей и код. Приведённые ниже фрагменты скопированы из руководств.

{
  "domain": "tigertag",
  "name":   "TigerTag",
  "version": "0.1.0",
  "requirements": ["pyrebase4>=4.5.0"],
  "config_flow": true,
  "iot_class": "cloud_polling"
}

weight_available = max(0, measured_raw_weight - container_weight)

pip install -r requirements.txt
python tigertag_client.py

pip install -r requirements.txt
export TIGERTAG_EMAIL=you@example.com
export TIGERTAG_PASSWORD=yourpassword
export SPOOLMAN_URL=http://192.168.1.10:7912
export DRY_RUN=1                    # dry-run mode
python3 sync.py

users/{uid}/scales/{mac}          ← heartbeat, every 30 s
users/{uid}/inventory/{spoolId}   ← weight_available + last_update

Разрабатываете для другой платформы? Новое руководство помещается в docs/clients, а необязательный рабочий пример — в examples/. CONTRIBUTING.md

Аккаунт пользователя, правила пользователя

Нет общего ключа, который нужно защищать, и нет мастер-токена, который может утечь: клиент может делать ровно то, что может его пользователь, и Firestore обеспечивает это на сервере.

Публичный контракт для интеграторов

Репозиторий считается публичным контрактом: изменения, затрагивающие клиенты, попадают в этот репозиторий в том же выпуске, а журнал изменений относит каждое из них к категории Added, Changed, Deprecated, Removed, Fixed или Security.

Гарантии стабильности в READMECHANGELOG.md

Справочная документация

Основные документы, на которых строится любая интеграция, в том порядке, в каком они нужны клиенту.

• 01-firebase-config.mdПубличный эндпоинт конфигурации Firebase, назначение каждого поля и срок кэширования.
• 02-authentication.mdВход по адресу электронной почты и паролю, обновление токена и схема повтора при permission-denied.
• 03-data-model.mdВсе коллекции и поля Firestore: инвентарь, стеллажи, друзья, профили, весы.
• 04-friend-system.mdКак работает доступ друзей: публичные коды, закрытые ключи, двусторонняя связь.
• 05-rate-limiting.mdИнтервалы опроса, ограничения запросов, мониторинг и почему App Check не применяется принудительно.
• rules/firestore.rulesПубличная копия развёрнутых Firestore Security Rules.

Часть экосистемы TigerTag

Это руководство посвящено облачному аккаунту. У чипов, приложений и SDK есть собственные репозитории.

Вопросы