Een Google Calendar verbinden

Deze gids laat zien hoe je Google Calendar met een werkruimte verbindt. De koppeling geldt per werkruimte: de afspraken van die werkruimte worden alleen-lezen naar Control Center gesynchroniseerd. Zie Agenda en planning voor het volledige beeld.

Een account verbinden

Open Agenda in de sidebar.
Klik in de sidebar van de agenda op Agenda-account toevoegen. (Dezelfde sectie staat ook onder Instellingen → Werkruimte → Profiel en identiteit, onder Google Agenda.)
Kies hoe je autoriseert:
- Google-app van Control Center gebruiken — niets in te stellen. Dit is de standaardoptie als je build er een meelevert.
- Mijn eigen Google Cloud-client gebruiken — plak een client-id en secret uit je eigen project (zie Je eigen Google-client meenemen).
Klik op Google Agenda verbinden. Het dialoogvenster toont een korte code en een link naar de apparaatpagina van Google.
Open die pagina op een willekeurig apparaat, voer de code in en keur de gevraagde toegang goed. Het dialoogvenster sluit vanzelf en je afspraken worden gesynchroniseerd.

De server voert deze uitwisseling uit, niet je apparaat, en bewaart het resulterende refresh token — daarom keur je de code goed op “een willekeurig apparaat” en niet specifiek in deze app.

Het account wordt alleen aan de actieve werkruimte gekoppeld. Wissel je van werkruimte, dan zie je in plaats daarvan de agenda’s van die werkruimte.

De verbindingsflow vraagt calendar.readonly plus je e-mailadres aan — dezelfde scopes voor de ingebouwde app en voor een client die je zelf plakt. Control Center leest afspraken; het maakt ze niet aan, bewerkt of verwijdert ze niet en reageert niet op uitnodigingen bij Google.

Hoe synchronisatie werkt

De server beheert het schema: elke twee minuten loopt hij alle verbonden accounts van elke werkruimte na en schrijft de afspraken naar de database van die werkruimte. Clients praten nooit met Google — ze lezen wat de server heeft geschreven.

De ronde is incrementeel. De eerste doorgang per agenda haalt een rollend venster op (60 dagen terug, 90 dagen vooruit) en legt het synctoken van Google vast; latere doorgangen bieden dat token aan en ontvangen alleen wat is gewijzigd, en dat is wat een ritme van twee minuten betaalbaar maakt. Het venster wordt elke 24 uur opnieuw verankerd met een volledige synchronisatie, en ook wanneer Google het token ongeldig maakt.

Refresh tokens staan aan de serverkant in secrets.json in de gegevensmap van de server, weggeschreven met alleen rechten voor de eigenaar (0600) — niet in de sleutelhanger van het besturingssysteem en nooit op een clientapparaat.

Meerdere accounts verbinden

Een werkruimte kan meerdere Google-accounts verbinden (bijvoorbeeld werk en privé). Herhaal de verbindingsstap voor elk account; hun afspraken komen samen in dezelfde weergaven maand / week / agenda. Elk account synchroniseert en vernieuwt zelfstandig, en elk kan afzonderlijk worden losgekoppeld.

Een verlopen account opnieuw verbinden

Als Google het token van een account permanent ongeldig maakt (een ingetrokken of lang verlopen sessie), stopt de synchronisatie en toont Control Center een banner Opnieuw verbinden in de agenda, plus een melding op de desktop. Klik op Opnieuw verbinden en keur een nieuwe code goed; de banner verdwijnt bij de volgende geslaagde synchronisatie.

Een account loskoppelen

Klik in de sidebar van de agenda (of onder Instellingen → Werkruimte → Profiel en identiteit) bij het account op Verbinding verbreken. Hiermee worden de gesynchroniseerde afspraken verwijderd en de opgeslagen tokens op de server gewist.

Verbinden vanaf een headless server

Een server zonder aangesloten GUI verbindt hetzelfde account vanaf zijn eigen terminal:

GOOGLE_OAUTH_CLIENT_ID=<id> GOOGLE_OAUTH_CLIENT_SECRET=<secret> \
  cc_server calendar connect --data-dir <dir> --workspace <workspace-id>

Hij toont een code en een URL, wacht op goedkeuring en bewaart daarna de tokens; de volgende ronde synchroniseert hij.

Een build vanaf de broncode bevat geen Google-client, dus zijn de id en het secret vereist — stel GOOGLE_OAUTH_CLIENT_ID en GOOGLE_OAUTH_CLIENT_SECRET in. Er is geen --google-client-id-flag (onbekende flags worden genegeerd). Zonder het omgevingspaar stopt de opdracht met een fout over een ontbrekende client.

Je eigen Google-client meenemen (forks en self-hosting)

Releasebuilds bevatten een Google-client, dus de meeste mensen komen hier nooit aan te pas. Neem je eigen client als je vanaf de broncode bouwt, je eigen server draait, of wilt dat het toestemmingsscherm de naam van je eigen project toont.

Schakel in de Google Cloud Console de Google Calendar API in en configureer het OAuth-toestemmingsscherm, waarbij je de scopes calendar.readonly, openid en email toevoegt. Zolang de app niet is geverifieerd, voeg je jezelf toe als testgebruiker. Het toevoegen van calendar.events op het toestemmingsscherm maakt RSVP niet mogelijk — Control Center vraagt die scope nooit aan.
Maak een OAuth-client-ID aan van het applicatietype TVs and limited input devices en kopieer zowel de client-id als het client-secret.
Geef ze door, ofwel per verbinding (kies Mijn eigen Google Cloud-client gebruiken in het dialoogvenster), ofwel serverbreed met GOOGLE_OAUTH_CLIENT_ID en GOOGLE_OAUTH_CLIENT_SECRET.

Een serverbreed paar vervangt het ingebouwde paar overal, ook achter de optie “Google-app van Control Center gebruiken” — dus op je eigen server is die optie jouw app.

Het client-secret verlaat de server nooit: geen enkel RPC-antwoord bevat het, en een account dat via de eigen client van de server is verbonden, bewaart een markering in plaats van een kopie van het paar; het roteren ervan is dus een kwestie van opnieuw starten met een nieuwe waarde.

Problemen oplossen

Symptoom	Waarschijnlijke oorzaak
Het dialoogvenster biedt geen ingebouwde optie	Deze build bevat geen Google-client (een build vanaf de broncode), of de server is gestart met slechts één helft van het paar. Zowel de id als het secret is vereist
`invalid_scope` bij het starten van de flow	Calendar is in dat Cloud-project niet toegestaan voor een device-codeclient. Gebruik in plaats daarvan een project met een loopback- of webclient
`invalid_client` van Google	De client is geen TVs and limited input devices-client, of de id en het secret komen uit verschillende clients
Goedkeuring lukt, maar de synchronisatie blijft leeg	Je account is op het toestemmingsscherm geen testgebruiker, of `calendar.readonly` is niet toegekend
De code verloopt voordat je hem goedkeurt	Device-codes zijn kortlevend. Start de verbinding opnieuw voor een nieuwe code
“Kon je reactie niet bijwerken” bij een RSVP	Verwacht: de verbindingsflow vraagt `calendar.events` nooit aan
De synchronisatie stopt met een waarschuwing over het vernieuwen van tokens in het serverlog	Het account is verbonden met een client die niet meer is geconfigureerd. Verbind het account opnieuw, of herstel die client-id en dat secret

Gerelateerde gidsen

Een vergadering opnemen en samenvatten: maak van een afspraak een opname
Een headless server draaien: waar de tokens en het synchronisatieschema staan
GitHub-integratie instellen

Gerelateerde concepten

Agenda en planning