docs: config debugger (#78)

vonovak · web-flow · commit 7885d2e62f3c · 2025-09-07T11:38:43.000+02:00
diff --git a/docs/config-doctor.md b/docs/config-doctor.md
@@ -0,0 +1,64 @@
+---
+sidebar_label: Config doctor
+sidebar_position: 75
+sidebar_class_name: sponsor-heart
+---
+
+# Configuration Doctor (beta)
+
+A command-line tool designed to help with Android signing configuration issues and quickly resolve the infamous `DEVELOPER_ERROR`, or potentially [other errors](#when-to-use) too.
+
+## Why
+
+To save time. Developers sometimes waste hours or even days tracking down the [errors](#when-to-use).
+
+This tool gives you the SHA-1 fingerprints that need to be added to your Google project configuration to resolve the error.
+
+## Usage
+
+The tool can extract SHA-1 fingerprints directly from a device/emulator with your app installed, or from an APK file.
+
+Run the command as shown below and follow the instructions.
+
+```bash
+# Usage with device/emulator
+npx @react-native-google-signin/config-doctor --package-name com.yourapp.name
+
+# Usage with an APK file
+npx @react-native-google-signin/config-doctor --apk-path ./app-release.apk
+```
+
+### Arguments
+
+- `--package-name` (optional): Your Android app's package name. If provided, the tool extracts the APK from a connected device/emulator.
+- `--apk-path` (optional): Path to an APK file.
+
+## When to use
+
+When getting `DEVELOPER_ERROR`, unexpected [`cancelled`](https://issuetracker.google.com/issues/424210681) or even `GetCredentialProviderConfigurationException` during Sign-In. You can run into these errors:
+
+- When setting up Google Sign-In for the first time
+- After downloading your app from Play Store
+- When switching between debug and release builds
+
+### Example Output
+
+```
+✔ Application package name: com.some.app.android
+
+🔍 Found the following SHA-1 certificate fingerprints:
+
+A1:B2:C3:D4:E5:F6:G7:H8:I9:J0:K1:L2:M3:N4:O5:P6:Q7:R8:S9:T0
+
+Next steps:
+...
+```
+
+## Requirements
+
+- Valid subscription (get access at [universal-sign-in.com](https://universal-sign-in.com))
+- Android device/emulator with your app installed, OR a built APK file
+
+## Related Documentation
+
+- [Collecting configuration information](./setting-up/get-config-file.mdx)
diff --git a/docs/install.mdx b/docs/install.mdx
@@ -20,13 +20,17 @@ Why paid? According to the [State of React Native Survey](https://results.2024.s
   - iOS & macOS: Powered by the [Google Sign-In SDK](https://developers.google.com/identity/sign-in/ios/start)
 
 - **Licensed:** see [pricing](https://universal-sign-in.com/#pricing) and [license](https://universal-sign-in.com/license).
-- **Trusted**: A total of over 250k npm package downloads.
+- **Trusted**: A total of over 400k npm package downloads.
 - **Faster Sign-Ups**: Reduce sign-up and sign-in times on Android by up to 50%, according to [Google](https://developer.android.com/identity/sign-in/legacy-gsi-migration#authentication).
 - **See the UI**: [screenshots](screenshots) of the features.
+- **Widely compatible & stable:** Both old and [new architecture](https://reactnative.dev/architecture/landing-page) of React Native are supported. See version [compatibility table](#requirements) below.
 
-🛡️ **Advanced [security features](/docs/security)**
+🔧 **Easier setup**:
+
+- Android [Config Doctor](/docs/config-doctor) that might save you from pulling your hair out.
+- Automatic detection of [configuration parameters](one-tap#automatic-config) for faster integration.
 
-🔧 **Easier setup** — Automatic detection of [configuration parameters](one-tap#automatic-config) for faster integration.
+🛡️ **Advanced [security features](/docs/security)**
 
 [//]: # '🖥️ **Unified API** - Write code once, deploy everywhere.'
 
@@ -36,7 +40,7 @@ Why paid? According to the [State of React Native Survey](https://results.2024.s
 
 Available on the public npm registry, this version:
 
-- Uses the functional, but deprecated [legacy Android Google Sign-In](https://web.archive.org/web/20240308064911/https://developers.google.com/identity/sign-in/android/start-integrating) which may be removed from the Google Play Services Auth SDK (`com.google.android.gms:play-services-auth`) at some point ([source](https://developer.android.com/identity/sign-in/legacy-gsi-migration)). The free package will continue to use a version where the deprecated but functional SDK is present.
+- Uses the functional, but deprecated [legacy Android Google Sign-In](https://web.archive.org/web/20240308064911/https://developers.google.com/identity/sign-in/android/start-integrating). The free package will continue to use a version where the deprecated but functional SDK is present.
 - Has platform support limited to Android and iOS.
 - Contains none of the extra features listed above.
 
@@ -113,6 +117,11 @@ There are several guides to follow now:
 
 For latest version of Universal Sign In, `compileSdkVersion` must be {'>='} 35 and `kotlinVersion` must be {'>='} 2.0.21 in your Android project. If you use Expo SDK 53 or newer, these requirements are already met. Use [`expo-build-properties`](https://docs.expo.dev/versions/latest/sdk/build-properties/#example-appjson-with-config-plugin) to specify these values on Expo SDK {'<='} 52.
 
-The latest versions of the packages support the last three stable releases of React Native. Use older versions of the packages if you run older React Native.
+The latest version of the Universal Sign In package supports:
+
+|              | supported range |
+| ------------ | --------------- |
+| expo         | 52.0.40 - 54    |
+| react-native | 0.76.0 - 0.81   |
 
-[React Native new architecture](https://reactnative.dev/architecture/landing-page) is supported.
+Use older versions of the package if you run older React Native / Expo.
diff --git a/docs/setting-up/get-config-file.mdx b/docs/setting-up/get-config-file.mdx
@@ -5,55 +5,76 @@ sidebar_label: Configuration
 
 # Collecting configuration information
 
-Before getting your hands dirty with code, some configuration needs to be taken care of. Be patient, this is the most complex part of the setup.
+Before getting your hands dirty with code, some configuration needs to be taken care of. Configuration information collected in this guide is used in later steps of the setup and in the `configure()` call: [1](/docs/one-tap#configure) or [2](/docs/original#configure).
 
-Configuration information collected in this guide is used in later steps of the setup and in the `configure()` call: [1](/docs/one-tap#configure) or [2](/docs/original#configure).
-
-You **do not** need Firebase to configure Google Sign In. However, if you use it, it's a little easier to set up the sign in experience because Firebase gives you one file to download and put into your project.
+You **do not** need to use Firebase to configure Google Sign In.
 
 ## Android
 
-Follow the 2 steps below to set up Google Sign In for your Android app.
+Follow the two steps below to set up Google Sign In for your Android app.
+
+:::warning
+In case you encounter any of the following issues, revisit this guide - it means the steps below weren't fully completed.
+
+- if you ever get the infamous `DEVELOPER_ERROR` error
+- if you can sign in with debug APK and not in release (or vice versa)
 
-:::danger
-Completing this guide is crucial for Google Sign-In to work on Android. If not done correctly, you will get the infamous `DEVELOPER_ERROR` error [(how to troubleshoot it)](/docs/troubleshooting#developer_error).
 :::
 
-### Step 1: Collect SHA-1 certificate fingerprints
+### Step 1: Collect SHA-1 (not SHA-256) certificate fingerprints
+
+Your Android app probably uses multiple signing configurations. For example, an app might be signed differently when building `debug` and `release` APKs locally or when building on [Expo EAS](https://docs.expo.dev/app-signing/managed-credentials/#inspecting-credentials-configuration). Then there's the [Play App Signing](https://support.google.com/googleplay/android-developer/answer/9842756?hl=en) for store deployments — Google Play Store may _re-sign_ your app using one of its own signing configurations.
 
-Your Android app probably uses multiple signing configurations. For example, an app might be signed differently when building `debug` and `release` APKs locally or when building on [Expo EAS](https://docs.expo.dev/app-signing/managed-credentials/#inspecting-credentials-configuration). Then there's the [Play App Signing](https://support.google.com/googleplay/android-developer/answer/9842756?hl=en) for store deployments — while the Google Play Store does not (re)build your app, it may _re-sign_ it using one of its own signing configurations.
+:::important
+If your app is not yet in the Play Store, focus only on the development APK and its SHA-1 certificate fingerprint. You can come back to this guide later when you upload your app to the Play Store.
 
-It's extremely common for an app to have three or more signing configurations, each with its own SHA-1 certificate fingerprint.
+However, be advised that in the end, you need to get the SHA-1 certificate fingerprints for _all_ signing configurations and then use _all_ of those SHA-1 fingerprints in [Step 2](#step-2) below.
+:::
 
-First, you need to **get the SHA-1 certificate fingerprints for all signing configurations** using the instructions below.
-Then, use _all_ of those SHA-1 fingerprints in [Step 2](#step-2) below.
+#### Collect SHA-1 certificate fingerprints from:
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 <Tabs>
-  <TabItem value="playStore" label="When releasing via Google Play Store">
+  <TabItem value="config-doctor" label="A device or any APK file" default>
+
+Use the [Configuration Doctor](../config-doctor.md). (Requires an [Universal sign in](/docs/install#sponsor-only-version) license.)
+
+1. Get a device / emulator with the app installed, or get the APK (build it locally or in cloud, download from the Play Console / Play Store...)
+2. Run the tool and follow its instructions:
+
+```bash
+npx @react-native-google-signin/config-doctor
+```
+
+</TabItem>
+
+  <TabItem value="playStore" label="Google Play Store (when downloading from it)">
     Check if "Google Play App Signing" is enabled for your app [in the console](https://play.google.com/console/).
     If it is enabled, you need to take the following steps:
 
     1. In Google Play Console, navigate to: \<Your App\> -> Release section (in the left sidebar) -> Setup -> App Signing.
-    2. Under the "App signing key certificate" _and also_ "Upload key certificate", take note of `SHA-1 certificate fingerprint`. That's a total of two or more fingerprints (Play Store sometimes has more than one "App signing key certificate"!).
+    2. Under the "App signing key certificate", take note of `SHA-1 certificate fingerprint`(s). Play Store sometimes has more than one "App signing key certificate"!
 
   </TabItem>
 
-<TabItem value="eas" label="When using Expo EAS">
+<TabItem value="eas" label="EAS Build">
   If you use [Expo EAS](https://expo.dev/eas), run `eas credentials` to obtain
   the Keystore information, which includes the SHA-1 fingerprint. See [EAS
   credentials
   docs](https://docs.expo.dev/app-signing/managed-credentials/#inspecting-credentials-configuration)
   to learn more.
 </TabItem>
 
-  <TabItem value="local" label="When developing locally">
-    1. From your project root, `cd android && ./gradlew signingReport`.
-    2. Scroll to the top of output, see the fingerprints. Debug fingerprint is used for locally-built debug apk,
-    release fingerprint is used for release APK.
-  </TabItem>
+<TabItem value="local" label="Local build">
+
+1. From your project root, `cd android && ./gradlew signingReport`.
+2. Scroll to the top of output, see the fingerprints. Debug fingerprint is used for
+   locally-built debug APK, release fingerprint is used for release APK.
+
+</TabItem>
+
 </Tabs>
 
 <br />
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -9,26 +9,31 @@ sidebar_position: 70
 
 ### Login does not work when downloading from the Play Store.
 
-See [the next paragraph](#developer_error).
+See [`DEVELOPER_ERROR` paragraph](#developer_error).
 
 ### `DEVELOPER_ERROR` or `code: 10` or `Developer console is not set up correctly` error message {#developer_error}
 
-This is always (!_always_!) a configuration mismatch between your app and the server-side setup (in Firebase or Google Cloud console).
+This is always (! _absolutely always_ !) a configuration mismatch between your app and the server-side setup (in Firebase or Google Cloud console).
 
-Follow these pointers:
+Firstly, if you are using Firebase Auth, verify Google is enabled as a Sign-in method in Firebase Console (Build -> Authentication -> Sign-in method).
 
-- Follow the [setup guide](/docs/setting-up/get-config-file) and perform its steps once again.
-- Make sure that your SHA-1 (_NOT_ SHA-256!) certificate fingerprints and Android package name you entered in [Firebase Console](https://console.firebase.google.com/) / [Google Cloud Console](https://console.cloud.google.com/apis/credentials?project=_) are correct.
-- Add the SHA-1 from the output of [this command](https://x.com/vonovak/status/1692127631473529226) to your Firebase / Google Cloud Console. You should be able to recognize the SHA-1 — do not add a hash if you're not sure of its origin.
-- [Search the issue tracker](https://github.com/react-native-google-signin/google-signin/issues?q=is%3Aissue+DEVELOPER+ERROR+is%3Aclosed) for old reports of the error.
+Then: if you have the APK that gives this error, we recommend to run the [Configuration Doctor](./config-doctor.md) and follow its instructions:
+
+```bash
+npx @react-native-google-signin/config-doctor
+```
+
+Otherwise, we recommend:
+
+- Follow the [setup guide](/docs/setting-up/get-config-file) and perform its steps once again, very carefully.
 - If you're passing `webClientId` in the configuration object to `GoogleSignin.configure()`, make sure it's correct and that it is of type web (NOT Android!). You can get your `webClientId` from [Google Developer Console](https://console.developers.google.com/apis/credentials). It is listed under "OAuth 2.0 client IDs".
-- If you are using Firebase, you need to add Google as a Sign-in method in Firebase itself (Build -> Authentication -> Sign-in method). If you have already created an app, you will be prompted for fingerprints and then you will get a new `google-services.json` which you need to use in your app instead of the old one.
+- [Search the issue tracker](https://github.com/react-native-google-signin/google-signin/issues?q=is%3Aissue+DEVELOPER+ERROR+is%3Aclosed) for old reports of the error.
 
 ### Login does not work when using Internal App Sharing.
 
 If you get a `DEVELOPER_ERROR` when using Internal App Sharing, it is because Google resigns your application with its own key.
 
-See [the previous paragraph](#developer_error).
+See [`DEVELOPER_ERROR` paragraph](#developer_error).
 
 ### "A non-recoverable sign in failure occurred"
 
@@ -50,6 +55,6 @@ Along with "Your app is missing support for the following URL schemes" error in
 
 Your `Url Schemes` configuration is incorrect.
 
-If you use Expo, make sure that the [config plugin](setting-up/expo#add-config-plugin) is configured correctly.
+If you use Expo, verify that the [config plugin](setting-up/expo#add-config-plugin) is configured correctly.
 
 In vanilla React Native projects, add URL type [like this](https://react-native-google-signin.github.io/docs/setting-up/ios#xcode-configuration).
