Riferimento per integrazioni di terze partiTigerTag Firebase Integration

Come un client si collega a TigerTag

Ogni client segue gli stessi quattro passaggi: recuperare la configurazione pubblica di Firebase, accedere come l'utente, chiamare l'API REST di Firestore con il token dell'utente e mantenere valido quel token.

1. 1

   Recupera la configurazione pubblica

   Una sola GET restituisce la configurazione del progetto Firebase. L'apiKey è pubblica per scelta progettuale: identifica il progetto, non chi effettua la chiamata. Mettila in cache; basta aggiornarla una volta alla settimana.

   01-firebase-config.md
2. 2

   Accedi come l'utente

   L'email e la password dell'utente stesso restituiscono un UID, un idToken da 1 ora e un refreshToken. Google Sign-In richiede un browser, quindi i client senza interfaccia usano una password.

   02-authentication.md
3. 3

   Leggi e scrivi in Firestore

   Invia l'idToken come token Bearer. Le bobine si trovano in users/{uid}/inventory, gli scaffali in users/{uid}/racks; i pesi sono grammi netti, le date millisecondi Unix.

   03-data-model.md
4. 4

   Mantieni valido il token

   Rinnova l'idToken prima che scada l'ora e sostituisci entrambi i token salvati. In caso di permission-denied, rinnova una volta e riprova la lettura una volta.

   Rinnovare l'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}

Integrazioni documentate in questo repository

Ogni guida in docs/clients copre l'autenticazione, i dati che legge o scrive, la mappatura dei campi e il codice. I frammenti qui sotto sono copiati dalle guide.

{
  "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

Sviluppi per un'altra piattaforma? Una nuova guida va in docs/clients, un esempio eseguibile facoltativo in examples/. CONTRIBUTING.md

L'account dell'utente, le regole dell'utente

Non c'è nessuna chiave condivisa da proteggere né alcun token master che possa trapelare: un client può fare esattamente ciò che può fare il suo utente, e Firestore lo impone sul server.

Un contratto pubblico per gli integratori

Il repository è trattato come un contratto pubblico: le modifiche che riguardano i client arrivano in questo repository nella stessa release, e il changelog registra ciascuna come Added, Changed, Deprecated, Removed, Fixed o Security.

Garanzie di stabilità nel READMECHANGELOG.md

Documentazione di riferimento

I documenti di base su cui si fonda ogni integrazione, nell'ordine in cui servono a un client.

• 01-firebase-config.mdL'endpoint pubblico della configurazione Firebase, a cosa serve ciascun campo e per quanto tempo tenerlo in cache.
• 02-authentication.mdAccesso con email e password, rinnovo del token e lo schema di nuovo tentativo in caso di permission-denied.
• 03-data-model.mdOgni collezione e campo di Firestore: inventario, scaffali, amici, profili, bilance.
• 04-friend-system.mdCome funziona l'accesso degli amici: codici pubblici, chiavi private, il legame bidirezionale.
• 05-rate-limiting.mdIntervalli di polling, limiti delle query, monitoraggio e perché App Check non è imposto.
• rules/firestore.rulesLa copia pubblica delle Firestore Security Rules in produzione.

Parte dell'ecosistema TigerTag

Questa guida riguarda l'account cloud. I chip, le app e gli SDK hanno i propri repository.

Domande