StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.
Google Drive backup sync — setup guide
StreamVault can sync its backup file to a private folder of your Google Drive
(scope drive.appdata). The folder is owned by the app, invisible in the
standard Drive UI, and wiped automatically when the user uninstalls the app.
This page targets maintainers and contributors who want to build/debug the feature locally. End users don't need to do anything — they just sign in from Settings → Backup & Restore → Google Drive sync.
Why per-build setup is required
The Google Sign-In Android SDK authenticates a running app by matching the
pair (packageName, signing certificate SHA-1) against the OAuth client IDs
registered in a Google Cloud Console project. There is no client secret in
the code — every fork/maintainer/release channel must register its own pair.
That means:
| Build flavour | Needs its own OAuth client | Why |
|---|---|---|
master debug, local on dev machine |
yes | each developer signs with their own debug keystore (different SHA-1) |
| Official release on Play Store | yes | Davidona's release key SHA-1 |
| CI build | yes (or share the dev one) | depending on signing strategy |
The code in data/manager/GoogleDriveBackupSyncManager.kt never references an
OAuth client ID — it just asks Play Services for the locally-installed client
matching its (packageName, SHA-1). If no client is registered, sign-in fails
silently with ApiException status DEVELOPER_ERROR (10).
One-time setup (Google Cloud Console)
1. Create a Cloud project
Open https://console.cloud.google.com/projectcreate and create a project of
your choice (e.g. streamvault-dev-<your-handle>). Select it.
2. Enable the Google Drive API
https://console.cloud.google.com/apis/library/drive.googleapis.com → Enable.
3. Configure the OAuth consent screen
https://console.cloud.google.com/apis/credentials/consent
- User type → External
- App name →
StreamVault(or your fork name) - User support email + Developer contact → your email
- Scopes → add
https://www.googleapis.com/auth/drive.appdata - Test users → add the Google account(s) you'll sign in with on the device
While the project stays in Testing state, only the listed test users can sign in (hard cap: 100 accounts). That's fine for development. To open the flow to all users, see the publishing section below.
4. Create the OAuth Android client(s)
https://console.cloud.google.com/apis/credentials → Create credentials → OAuth client ID → Android.
| Field | Value |
|---|---|
| Name | StreamVault — debug (<your handle>) |
| Package name | com.streamvault.app |
| SHA-1 certificate fingerprint | from keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android |
Repeat the step for every signing certificate that will run the feature (release key, CI key, …). You don't need to copy any returned ID anywhere — the runtime resolves it transparently.
5. Add a Google account to the test device
The device or emulator that runs the build must have a Google account added in Settings → Accounts, and that account must be in the OAuth consent screen's Test users list.
6. Publish the app (open the flow to all users)
This step is optional if you only need maintainer access. It is required to let arbitrary end users sign in (Play Store distribution, public release APK, etc.).
The good news: drive.appdata belongs to Google's non-sensitive scope
category — official list
shows it without the (Sensitive) or (Restricted) tag. Concrete consequence:
no verification process, no security assessment, no waiting period. You can
flip the project from Testing to In production immediately and unknown users
will be able to sign in right after.
Walkthrough (matches what I went through yesterday on the real project):
- Open the OAuth consent screen page (https://console.cloud.google.com/apis/credentials/consent).
- Under the project status pill (currently Testing), click Publish app.
- A confirmation dialog appears titled Push to production? — confirm.
- The pill flips to In production. The page now states "This OAuth client is now ready to be used by any user with a Google account. Verification is not required for this app."
- Done. New users (outside the Test users list) can sign in immediately.
Notes:
- The Test users list becomes irrelevant in production — sign-ins are no longer gated by it.
- Refresh tokens issued by Testing projects expire after 7 days; in
production they don't (matches our
GoogleAuthUtil.getTokenper-call strategy, where this is mostly invisible to the user). - If you ever add a sensitive or restricted scope later (e.g. full
drive), then verification kicks in — but as long as the only scope isdrive.appdata, you stay on the fast path.
Verifying the setup
- Install the debug APK.
- Settings → Backup & Restore → Google Drive sync → Connect to Google Drive.
- Pick the test user account in the system picker. The consent screen must
ask only for the
drive.appdatascope — if it asks for more (or fails with "Developer error"), you have a SHA-1 / package name mismatch.
Troubleshooting
| Symptom | Likely cause |
|---|---|
Sign-in dialog closes immediately, ApiException(10) in logcat |
OAuth Android client missing or wrong SHA-1 / package name |
Sign-in succeeds but push/pull errors with drive_auth_failed |
Drive API not enabled, or scope not granted in consent screen |
Google Play Services required snackbar |
Emulator built with AOSP images (no GMS). Use a "Google APIs"/"Google Play" emulator image |
Push works, pull says drive_no_remote_backup |
Drive appDataFolder is empty for this account — push first |
Privacy notes
- New pushes use timestamped v2 artifacts named like
streamvault_backup_bundle_20260814_120000_123_a1b2c3d4.json. Each contains the exact currentBackupManagerJSON export text and the matching provider-credentials snapshot. The app keeps the ten newest timestamped bundles and lets the user choose a snapshot before preview/import. Pull also accepts the original fixed-name v2 bundle, existing v1 bundles, and older standalone backup/credentials files as read-only migration fallbacks. Preserving the exported text keeps checksum verification compatible with backups produced by older release builds. New local and Drive exports carry the matching credentials field so a restored provider can sync immediately; older backups without that field still require password re-entry. - Auth tokens fetched via
GoogleAuthUtil.getTokenare never logged. - The scope
drive.appdatacannot read files outside the app's private folder.
Managing saved Drive backups
Open Settings → Backup & Restore → Manage Drive backups to see the saved
snapshots in newest-first order. The app asks for confirmation before deleting
one. It validates the selected snapshot against the current appDataFolder
listing, then refreshes the list after deletion. This prevents a stale screen
from deleting an unrelated Drive file.
For older installations that have a legacy standalone
streamvault_backup.json, deleting that backup also attempts to remove its
legacy streamvault_credentials.json companion. Current timestamped v2 bundles
are self-contained, so only the selected bundle is deleted.
Credentials storage (fork extension, M3)
Each timestamped streamvault_backup_bundle_*.json carries the configuration plus
its matching credentials snapshot in one versioned artifact. The current bundle
stores the backup JSON text unchanged so the main backup checksum remains
verifiable after Drive round-tripping. Older installations may still
have a second sibling file in the same appDataFolder:
streamvault_credentials.json—[{serverUrl, username, password}], cleartext.
Why cleartext in the bundle on Drive:
- The file is invisible to the OS and to the standard Drive UI (the
drive.appdatascope is the only path that can read it). - Access is gated by the user's Google account + OAuth consent.
- It is purged automatically when the app is uninstalled.
- Cross-device-by-design — a per-device Keystore key would defeat the purpose (the file would be unreadable on a fresh install, which is precisely the use case it solves).
- A passphrase-protected variant was considered and rejected: it adds significant UX friction (user must remember a passphrase across devices) for a small additional security margin given the threat model above.
The local DB still stores credentials encrypted via
AndroidKeystoreCredentialCrypto. Cleartext also exists in new local backup
files and in the Drive appDataFolder; during import it is applied to the
restored provider and then kept only in the encrypted local DB.
Matching is by (serverUrl, username) so provider IDs reshuffled by the SAF
import do not break the restore. Providers present locally but absent from a
credential snapshot are left untouched.
Pre-bundle backups (no v2 bundle in appDataFolder) are handled gracefully: the
pull path lists and falls back to the legacy standalone backup file;
pullCredentials returns an empty list when no legacy credentials file exists, and
the import path restores providers without passwords so the user can re-enter them
manually.