Skip to content

docs: Clarify Google sign-in setup for web and Android - #724

Merged
developerjamiu merged 2 commits into
mainfrom
docs/google-setup-clarity
Jul 30, 2026
Merged

docs: Clarify Google sign-in setup for web and Android#724
developerjamiu merged 2 commits into
mainfrom
docs/google-setup-clarity

Conversation

@developerjamiu

Copy link
Copy Markdown
Contributor

Fixes friction found by walking the Google sign-in setup guide end to end against a fresh 4.0.0-beta.1 project, testing on Android (emulator) and web.

Setup page

  • Web: the same-origin constraint and the "flutter run -d chrome doesn't work" caveat move into a warning placed before the build command, since setting up around the dev server is the natural mistake and the page only warned about it afterwards. The build command gains --base-href /app/ (without it the app loads blank under /app; FlutterRoute serves files as-is, and the project template's own flutter_build script includes the flag) and a "replace my_project_server" sentence matching the page's placeholder pattern.
  • Web: new warning that the app served at /app is a compiled snapshot, so main.dart changes need a rebuild. Testing showed a stale build is an easy way to hit redirect_uri_mismatch after correcting a redirect URI.
  • Android: the download-and-rename google-services.json steps are removed. The Auth Platform download is a client-secret JSON, not a google-services.json, and a plain Flutter project has no com.google.gms.google-services Gradle plugin to read one, so the step cannot supply the server client ID. Passing serverClientId (the Web client's ID) is now the primary path, shown in the initialize snippet's mobile branch; google-services.json remains as a note for Firebase-based projects. Verified against the failure GoogleSignInException(clientConfigurationError, serverClientId must be provided on Android) and confirmed working after the change.
  • Android: warning that the emulator cannot reach localhost, linking the new troubleshooting entry.

Troubleshooting page

  • New redirect_uri_mismatch cause: stale web build.
  • The "Missing web client entry in google-services.json" entry is retitled to the actual error message ("serverClientId must be provided") and rewritten with the real cause and the programmatic fix; the Firebase re-download guidance is kept for projects that use the Gradle plugin.
  • New entry: endpoint calls fail on Android with connection refused (template assets/config.json pins localhost, which overrides the framework's 10.0.2.2 emulator handling; resolution via --dart-define=SERVER_URL=...).
  • Setup checklist updated to match the Android changes.

Follow-up (not in this PR): the template shipping assets/config.json with localhost affects every scaffolded project on Android and is being raised as a framework issue; the endpoints page's "localhost adapts to the platform" wording should be revisited once that lands.

@developerjamiu developerjamiu self-assigned this Jul 30, 2026
@developerjamiu
developerjamiu requested a review from Zfinix July 30, 2026 10:28
@developerjamiu developerjamiu added bug Something isn't working documentation Improvements or additions to documentation labels Jul 30, 2026
@developerjamiu
developerjamiu force-pushed the docs/google-setup-clarity branch from ab1b0fc to de4a260 Compare July 30, 2026 10:48

@Zfinix Zfinix left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 🚀

@developerjamiu
developerjamiu merged commit ca777b3 into main Jul 30, 2026
4 checks passed
@developerjamiu
developerjamiu deleted the docs/google-setup-clarity branch July 30, 2026 16:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants