stremio/GOOGLE_PLAY_ACCESS_SETUP.md

Google Play Closed Testing — server-side setup

Deze functionaliteit beheert distributietoegang tot de Android-app via Google Play Closed Testing. Het vervangt niet de bestaande app-login of API-autorisatie.

Architectuur

Adminpaneel → backend → Google Cloud Identity Groups API → Google Group
                                                              ↓
                                              Google Play Closed Testing track

• Gebruikers worden niet individueel via de Play Developer API beheerd.
• De Closed Testing-track wordt eenmalig gekoppeld aan PLAY_ACCESS_GROUP_EMAIL.
• Het adminpaneel beheert alleen lidmaatschap van die groep.

Benodigde environment variables

Stel deze in op de master-api server (niet in de admin UI, niet in Git):

Variabele	Verplicht	Beschrijving
GOOGLE_CLOUD_PROJECT_ID	Ja	Google Cloud project ID
GOOGLE_SERVICE_ACCOUNT_EMAIL	Ja	Service account e-mail
GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY	Ja	PEM private key ( \n als \n in env)
PLAY_ACCESS_GROUP_ID	Ja	Group resource ID (zonder groups/ prefix mag ook)
PLAY_ACCESS_GROUP_EMAIL	Ja	E-mailadres van de Google Group
GOOGLE_WORKSPACE_ADMIN_EMAIL	Meestal ja	Admin voor domain-wide delegation
GOOGLE_WORKSPACE_CUSTOMER_ID	Optioneel	Workspace customer ID
GOOGLE_PLAY_OPT_IN_URL	Aanbevolen	Publieke Closed Testing opt-in URL
GOOGLE_PLAY_SYNC_INTERVAL_MS	Optioneel	Reconciliatie-interval (default: 86400000 = 24u)

Waar instellen

• Lokaal: apps/master-api/.env
• Productie/Dokploy: omgeving van de master-api container (deploy/master/.env template)

Google Cloud — handmatige stappen

1. APIs inschakelen

In Google Cloud Console → APIs & Services:

• Cloud Identity Groups API (cloudidentity.googleapis.com)

2. Service account aanmaken

1. IAM & Admin → Service Accounts → Create
2. Download JSON key of kopieer private key naar GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY
3. Noteer client_email → GOOGLE_SERVICE_ACCOUNT_EMAIL

3. Domain-wide delegation (Workspace)

Als de group in Google Workspace staat:

1. Service account → Enable Domain-Wide Delegation
2. Google Admin Console → Security → API Controls → Domain-wide delegation
3. Voeg scope toe: https://www.googleapis.com/auth/cloud-identity.groups
4. Stel GOOGLE_WORKSPACE_ADMIN_EMAIL in op een super admin

4. Service account rechten op de group

De service account (of geïmpersonateerde admin) moet leden kunnen beheren:

• Google Group → Group member manager of Owner
• Of via Cloud Identity met de juiste IAM-rollen

5. Google Group aanmaken

Maak een technische ACL-groep (geen hardcoded naam in code):

• Niet publiek vindbaar
• Self-join uit
• Alleen beheerders beheren leden
• Ledenlijst niet zichtbaar voor gewone members
• Posten/conversations uit indien mogelijk
• Externe accounts alleen toestaan als nodig (bijv. @gmail.com testers)

Noteer:

• Group e-mail → PLAY_ACCESS_GROUP_EMAIL
• Group ID → PLAY_ACCESS_GROUP_ID

Group ID vinden

Via Cloud Identity Groups API lookup:

GET https://cloudidentity.googleapis.com/v1/groups:lookup?groupKey.id=GROUP_EMAIL

Het veld name is bijv. groups/03abc123 → PLAY_ACCESS_GROUP_ID=03abc123

6. Google Play Console — Closed Testing koppelen

1. Play Console → app → Testing → Closed testing
2. Maak of open een track
3. Testers → Google Groups
4. Voeg PLAY_ACCESS_GROUP_EMAIL toe
5. Kopieer de opt-in URL → GOOGLE_PLAY_OPT_IN_URL

Gebruik in adminpaneel

1. Ga naar Kijkers
2. Per kijker: sectie Google Play access
   • Google Play email — het Google-account voor Play (fallback: account-e-mail)
   • Store access — ON/OFF
   • Status — sync-status (ACTIVE, ERROR, …)
   • Retry synchronization — bij ERROR
3. Pagina-acties:
   • Sync all — alle kijkers synchroniseren
   • Reconcile — lokale status vergelijken met Google Group

Testgebruiker toevoegen

1. Maak kijker aan (of bestaande)
2. Vul Google Play e-mail in (bijv. user@gmail.com)
3. Zet Store access aan
4. Status wordt ACTIVE na succesvolle sync
5. Gebruiker opent GOOGLE_PLAY_OPT_IN_URL terwijl ingelogd met hetzelfde Google-account
6. Installeert app via Play Store

Toegang intrekken

1. Zet Store access uit in adminpaneel
2. Backend verwijdert lidmaatschap uit de group
3. Nieuwe installs via Play zijn niet meer mogelijk
4. Let op: reeds geïnstalleerde apps blijven op het toestel — app-login/API blijft leidend voor contenttoegang

Sync & reconciliatie

Lokaal	Google Group	Actie
ON	member	OK
ON	geen member	toevoegen
OFF	member	verwijderen
OFF	geen member	OK

• Sync all: past gewenste status toe voor alle kijkers
• Reconcile: vergelijkt en herstelt afwijkingen
• Scheduled: elke GOOGLE_PLAY_SYNC_INTERVAL_MS (default 24u)

Foutafhandeling

Bij Google API-fouten:

• Gewenste instelling blijft bewaard
• Status → ERROR
• Fout staat in admin UI + audit log
• Gebruik Retry synchronization

Audit log tabel: google_play_access_audit_logs (geen tokens/keys gelogd).

API endpoints (admin only)

Method	Route
GET	/api/v1/admin/google-play-access/config
PATCH	/api/v1/admin/viewers/:id/google-play-access
POST	/api/v1/admin/viewers/:id/google-play-access/retry
POST	/api/v1/admin/google-play-access/sync-all
POST	/api/v1/admin/google-play-access/reconcile

Body PATCH:

{
  "enabled": true,
  "email": "user@gmail.com"
}

Wat jij nog handmatig moet invullen

Stop hier — vul geen credentials in deze repo:

1. GOOGLE_CLOUD_PROJECT_ID
2. GOOGLE_SERVICE_ACCOUNT_EMAIL
3. GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY
4. GOOGLE_WORKSPACE_ADMIN_EMAIL (indien Workspace)
5. PLAY_ACCESS_GROUP_ID
6. PLAY_ACCESS_GROUP_EMAIL
7. GOOGLE_PLAY_OPT_IN_URL

Daarna master-api herstarten en in adminpaneel testen met één tester-account.