> For the complete documentation index, see [llms.txt](https://help.twinr.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.twinr.dev/native-integrations/google-sign-in.md).

# Google Sign-In

Let customers sign in with the Google account already on their phone, in one tap.

Google Sign-In lets customers sign in with the Google account already on their phone. They tap, pick an account, and they are in — no password to remember, no form to fill in on a small screen.

Inside the app it uses the phone's own native sign-in, so it looks and feels like every other app they use.

{% hint style="warning" %}
**Twinr does not add a sign-in button to your app.** Your website's own "Sign in with Google" button calls Twinr, which opens the native picker and hands the result back to you.

If you turn this on and expect a button to appear, nothing will happen. The website change in [Step 4](#step-4-connect-your-website) is what makes it work.
{% endhint %}

### How it fits together

1. A customer taps your site's Google sign-in button inside the app.
2. Your page calls `twinr_google_sign_in()`.
3. The phone shows its native Google account picker.
4. Google authenticates them and Twinr receives a token.
5. Twinr sends that token to your **Auth callback URL**.
6. Your server verifies it, signs the customer in, and tells the app which page to open.

Your server stays in charge of sessions throughout. Twinr delivers a verified token; what counts as being signed in remains yours.

### What you will need

<table><thead><tr><th width="330">Requirement</th><th>Notes</th></tr></thead><tbody><tr><td>A Google Cloud account</td><td>With admin access to the project.</td></tr><tr><td>Your <strong>iOS bundle ID</strong> and <strong>Android package name</strong></td><td>Twinr shows both on the Google Sign-In screen, with a copy button.</td></tr><tr><td>Your Android <strong>SHA-1 certificate fingerprint</strong></td><td>See <a href="#find-your-sha-1-fingerprint">Find your SHA-1 fingerprint</a>.</td></tr><tr><td>Access to your website's code</td><td>Both the sign-in button and a server endpoint.</td></tr></tbody></table>

***

## Step 1: Turn it on

Open **Native Features → Google Sign-In** and switch on **Enable Google Sign-In**.

<figure><img src="https://3731994945-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlBy5z08zL1UoCwNqmg%2Fuploads%2Fgit-blob-ab8f1508c50d3ca4769ea345c39294bf948723ec%2Fgoogle-sign-in-screen.png?alt=media" alt="The Google Sign-In screen with its enable toggle"><figcaption></figcaption></figure>

The settings below stay hidden until it is on.

***

## Step 2: Choose how the token reaches you

**Send token via** offers two options.

<table><thead><tr><th width="330">Option</th><th>What happens</th></tr></thead><tbody><tr><td><strong>Webhook (POST JSON)</strong></td><td>Twinr POSTs the token to your <strong>Auth callback URL</strong> as JSON.</td></tr><tr><td><strong>URL redirect (query parameters)</strong></td><td>The customer is redirected to your <strong>Redirect URL</strong> with the data in the query string.</td></tr></tbody></table>

Choose **Webhook** if your server verifies tokens before creating a session — it keeps the token off the customer's screen and out of their browser history. Choose **URL redirect** if your existing web sign-in already works that way.

Enter the matching URL. It must be HTTPS and publicly reachable.

***

## Step 3: Create your Google OAuth client IDs

Google only signs a customer in when the request comes from an app it recognises. You tell Google about your app by creating **OAuth client IDs** in the Google Cloud Console — one per platform — then pasting them into Twinr.

{% hint style="info" %}
**Already use Google Sign-In on your website?** Use that same Google Cloud project and skip ahead to [Create the client IDs](#create-the-client-ids). Your web client ID is probably already there.
{% endhint %}

### Create a Google Cloud project

{% stepper %}
{% step %}

#### Open the console

Sign in to the [Google Cloud Console](https://console.cloud.google.com/).
{% endstep %}

{% step %}

#### Create the project

Click **New Project**, enter a **Project name** such as `MyStore Sign-In`, and click **Create**.
{% endstep %}
{% endstepper %}

### Configure the OAuth consent screen

This is the screen customers see when they pick an account.

{% stepper %}
{% step %}

#### Open the consent screen settings

Go to **APIs & Services → OAuth consent screen**.

<figure><img src="https://3731994945-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlBy5z08zL1UoCwNqmg%2Fuploads%2Fgit-blob-c9075bea3e40d85be5be8bedfa8a78836a1c1f12%2Fgoogle-signin-gcp-consent-nav.png?alt=media" alt="The Google Cloud Console navigation menu with APIs &#x26; Services expanded and OAuth consent screen highlighted"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Fill in your app information

Open **Branding** and complete **App information**.

<figure><img src="https://3731994945-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlBy5z08zL1UoCwNqmg%2Fuploads%2Fgit-blob-ff52151b5d2570b0ddae7bc75bac9746e312e2cd%2Fgoogle-signin-gcp-branding.png?alt=media" alt="The Branding page showing App name and User support email fields"><figcaption></figcaption></figure>

<table><thead><tr><th width="300">Field</th><th>What to enter</th></tr></thead><tbody><tr><td><strong>App name</strong></td><td>The name customers see on the consent screen.</td></tr><tr><td><strong>User support email</strong></td><td>An address customers can contact.</td></tr><tr><td><strong>App logo</strong></td><td>Optional. Uploading one requires verification unless the app is internal or in testing.</td></tr></tbody></table>
{% endstep %}

{% step %}

#### Finish and save

Add your **Developer contact information**, accept the **Google API Services: User Data Policy**, and click **Save and Continue**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Using Firebase as well?** Set a support email in **Firebase Console → Project settings → General → Public settings → Support email** too. Without it, sign-in fails.
{% endhint %}

### Create the client IDs

Create one client per platform. For each, go to **APIs & Services → Credentials → Create credentials → OAuth client ID**.

<figure><img src="https://3731994945-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlBy5z08zL1UoCwNqmg%2Fuploads%2Fgit-blob-7e02cc09620d51979f74b3132a8001550ef97db2%2Fgoogle-signin-gcp-create-credentials.png?alt=media" alt="The Credentials page with the Create credentials menu open and OAuth client ID highlighted"><figcaption></figcaption></figure>

{% tabs %}
{% tab title="iOS" %}

<figure><img src="https://3731994945-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlBy5z08zL1UoCwNqmg%2Fuploads%2Fgit-blob-b9202d809704ef7f83d278a4822ae12475a960de%2Fgoogle-signin-gcp-ios-client.png?alt=media" alt="The Create OAuth client ID form with Application type set to iOS and the Bundle ID field filled in"><figcaption></figcaption></figure>

{% stepper %}
{% step %}

#### Set the application type

Choose **iOS**.
{% endstep %}

{% step %}

#### Name the client

Enter a **Name** such as `MyStore iOS`. It is only shown inside the console.
{% endstep %}

{% step %}

#### Enter your bundle ID

In **Bundle ID**, paste the **iOS bundle ID** copied from Twinr.

Leave **App Store ID** and **Team ID** empty.
{% endstep %}

{% step %}

#### Create and copy

Click **Create**, then copy the **Client ID**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Android" %}

<figure><img src="https://3731994945-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlBy5z08zL1UoCwNqmg%2Fuploads%2Fgit-blob-02c1b198e747561e6a0f116d62a12cc29493e997%2Fgoogle-signin-gcp-android-client.png?alt=media" alt="The Create OAuth client ID form with Application type set to Android, showing the Package name and SHA-1 certificate fingerprint fields"><figcaption></figcaption></figure>

Google checks two things before it lets your Android app sign anyone in: the app's **package name**, and the **SHA-1 fingerprint** of the key that signed the build.

{% stepper %}
{% step %}

#### Set the application type

Choose **Android**.
{% endstep %}

{% step %}

#### Name the client

Enter a **Name** such as `MyStore Android`.
{% endstep %}

{% step %}

#### Enter your package name

In **Package name**, paste the **Android package name** copied from Twinr.
{% endstep %}

{% step %}

#### Enter the SHA-1 fingerprint

Enter the fingerprint of the key that signed the app customers install. Which key that is depends on how the app reaches them — see [Find your SHA-1 fingerprint](#find-your-sha-1-fingerprint).
{% endstep %}

{% step %}

#### Create and copy

Click **Create**, then copy the **Client ID**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Web" %}
Optional, but recommended. Your server uses it to check that a token really came from Google and was issued for your app.

{% stepper %}
{% step %}

#### Set the application type

Choose **Web application**.
{% endstep %}

{% step %}

#### Name the client

Enter a **Name** such as `MyStore Web`.
{% endstep %}

{% step %}

#### Leave the URL fields empty

Leave **Authorized JavaScript origins** and **Authorized redirect URIs** empty unless your website's own sign-in needs them.
{% endstep %}

{% step %}

#### Create and copy

Click **Create**, then copy the **Client ID**.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

### Find your SHA-1 fingerprint

Which fingerprint you need depends on how customers get the app.

{% tabs %}
{% tab title="From Google Play" %}
With Play App Signing — the default for new apps — Google re-signs your app before customers download it. Use **Google's** key, not the one in Twinr.

{% stepper %}
{% step %}

#### Open App integrity

In **Google Play Console**, go to your app → **Test and release → Setup → App integrity**.
{% endstep %}

{% step %}

#### Open the App signing tab

Select **App signing**.
{% endstep %}

{% step %}

#### Copy the fingerprint

Under **App signing key certificate**, copy the **SHA-1 certificate fingerprint**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Signed by Twinr" %}
For an APK you hand out yourself, or an internal test build, use the fingerprint of your Twinr keystore.

{% stepper %}
{% step %}

#### Download your keystore

In your app's dashboard, go to **App Build → Android build**. Under **Build signing key**, click **Keystore**. Two files download:

* your keystore file (`.jks`)
* `Android key store information.txt`, containing your **Key Alias**, **Key Password** and **Store Password**

If there is no **Keystore** button, your app has no signing key yet. Click **Add**, then either auto-generate a key or upload your existing `.jks`.
{% endstep %}

{% step %}

#### Read the SHA-1 from the keystore

`keytool` ships with Java — if you have Android Studio, you already have it. Run:

```bash
keytool -list -v -keystore path/to/your-keystore.jks -alias YOUR_KEY_ALIAS
```

Replace `YOUR_KEY_ALIAS` with the **Key Alias** from the text file. When prompted for a password, use the **Store Password**.
{% endstep %}

{% step %}

#### Copy the fingerprint

Under **Certificate fingerprints**, copy the line beginning `SHA1:`. It looks like `AB:CD:12:…` — 20 pairs of characters.
{% endstep %}
{% endstepper %}

{% hint style="danger" %}
Keep the keystore and `Android key store information.txt` private. Anyone holding both can sign apps as you.
{% endhint %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Need both?** If customers get the app from Google Play and you also test builds signed by Twinr, create two Android clients with the same package name — one per fingerprint. Put the **Google Play** one in Twinr.
{% endhint %}

### Paste the IDs into Twinr

Back on the **Google Sign-In** screen, fill in **Google OAuth client IDs**.

<table><thead><tr><th width="330">Twinr field</th><th>Paste</th></tr></thead><tbody><tr><td><strong>Web client ID (optional)</strong></td><td>The Web application client ID</td></tr><tr><td><strong>iOS client ID</strong></td><td>The iOS client ID</td></tr><tr><td><strong>Android client ID</strong></td><td>Your <strong>production</strong> Android client ID</td></tr></tbody></table>

Every client ID ends in `.apps.googleusercontent.com`.

Click **Save as draft**.

{% hint style="info" %}
**Google Sign-In does not use the Firebase config files.** `google-services.json` and `GoogleService-Info.plist` are for [push notifications](https://help.twinr.dev/push/firebase-push-notification.md) and [Firebase Analytics](https://help.twinr.dev/native-integrations/firebase-analytics.md) — see [Firebase Setup](https://help.twinr.dev/push/firebase-push-notification/firebase-setup.md). Google Sign-In needs the three OAuth client IDs above, and nothing else.

Both come from Google, which is why they are easily confused. Uploading a config file will not switch Google Sign-In on, and these client IDs will not enable push.
{% endhint %}

***

## Step 4: Connect your website

Your website needs two changes: your sign-in button calls Twinr, and your server handles the token Twinr sends back.

{% hint style="info" %}
**Why not use your existing Google sign-in?** Google blocks its sign-in page inside apps that show websites (`Error 403: disallowed_useragent`). Inside the app, the phone's native picker is the only way in — which is why your button has to call Twinr.
{% endhint %}

### Call Twinr from your sign-in button

When Google Sign-In is enabled, the app adds `twinr_google_sign_in()` to every page it opens. It exists only inside your app with this feature on — not in a normal browser. Check for it, and fall back to your usual web sign-in:

```javascript
function handleGoogleSignIn() {
  if (typeof twinr_google_sign_in === 'function') {
    twinr_google_sign_in();   // inside the app: native account picker
  } else {
    runWebGoogleSignIn();     // in a browser: your existing Google sign-in
  }
}
```

Wire your existing Google button to `handleGoogleSignIn()`.

### Receive the token by webhook

With **Send token via** set to **Webhook (POST JSON)**, the app sends a `POST` to your **Auth callback URL** after every attempt:

```http
POST /auth/google
Content-Type: application/json
Cookie: <the cookies your site set in the app>

{
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "platform": "android",
  "success": true,
  "user_info": null
}
```

<table><thead><tr><th width="210">Field</th><th>What it holds</th></tr></thead><tbody><tr><td><code>id_token</code></td><td>The Google ID token (a JWT). <code>null</code> when <code>success</code> is <code>false</code>.</td></tr><tr><td><code>platform</code></td><td><code>ios</code> or <code>android</code>.</td></tr><tr><td><code>success</code></td><td><code>true</code> when the customer signed in and Google returned a token.</td></tr><tr><td><code>user_info</code></td><td>A username or buyer ID the app already knows for this customer, if any. Usually <code>null</code> — identify the customer from the token, not this.</td></tr><tr><td><code>error_message</code></td><td>Sent only when <code>success</code> is <code>false</code>. <code>cancelled</code> means the customer closed the picker; anything else is the failure reason.</td></tr></tbody></table>

The `Cookie` header carries your site's cookies from the app, so you can match the sign-in to an existing visitor — a guest cart, for example.

**Reply with HTTP `200` and the page to open:**

```json
{ "load_url": "https://your-domain.com/auth/google/complete?ticket=8f3c2a..." }
```

<table><thead><tr><th width="330">Your reply</th><th>What the customer sees</th></tr></thead><tbody><tr><td><code>200</code> with <code>load_url</code></td><td>The app opens <code>load_url</code>.</td></tr><tr><td><code>200</code> without <code>load_url</code></td><td>Nothing changes. The page stays where it was.</td></tr><tr><td>Any other status, or no response</td><td>A <strong>Sign In Failed</strong> message.</td></tr></tbody></table>

When sign-in fails on the phone, the app still calls your webhook with `success: false` and shows **Sign In Failed** itself. If the customer cancelled, it shows nothing. Reply `200` to these calls.

{% hint style="danger" %}
**You cannot sign the customer in from the webhook reply.** The app calls your webhook directly, not through the page the customer is looking at, so a `Set-Cookie` header in the reply never reaches their session.

Instead, make `load_url` a one-time sign-in link. When the app opens it, your site checks the ticket, sets the session cookie, and redirects to the customer's account. Make each ticket single-use and expire it after a minute or two.
{% endhint %}

#### Verify the token on your server

Never sign anyone in from a token you have not verified. Use Google's library for your language — it checks the signature, issuer and expiry for you.

<table><thead><tr><th width="230">Check</th><th>What to do</th></tr></thead><tbody><tr><td><strong>Audience (<code>aud</code>)</strong></td><td>Accept the client IDs you entered in Twinr. With a <strong>Web client ID</strong> set, tokens from both platforms carry that ID; without one, iPhone tokens carry your <strong>iOS client ID</strong>.</td></tr><tr><td><strong>Customer ID</strong></td><td>Identify the customer by the token's <code>sub</code> field. An email address can change; <code>sub</code> never does.</td></tr><tr><td><strong>Email</strong></td><td>Trust <code>email</code> only when <code>email_verified</code> is <code>true</code>.</td></tr></tbody></table>

### Receive the token by URL redirect

With **Send token via** set to **URL redirect (query parameters)**, the app opens your **Redirect URL** with the result in the query string. Any parameters already in your URL are kept.

```
https://your-domain.com/auth/google/callback?platform=ios&success=true&id_token=eyJhbGciOi...
```

* **On success** — `success=true` and `id_token` are present. Verify the token [as above](#verify-the-token-on-your-server), then set the session cookie in your response. The page opens in the app's browser, so cookies work here.
* **On cancel or failure** — `success=false` and no `id_token`. The reason is not sent in this mode. Show your sign-in page again.

{% hint style="warning" %}
The token appears in the page address in this mode. After signing the customer in, redirect to a clean URL so it does not linger in their history or your server logs.
{% endhint %}

### Optional page callbacks

The app tells the page that called `twinr_google_sign_in()` how the attempt ended, so you can update the button. These run before the token is sent to your server.

```javascript
window.onGoogleSignInResult = function (idToken) {
  // signed in: show a loading state while your server finishes
};

window.onGoogleSignInCancelled = function () {
  // the customer closed the account picker: reset the button
};

window.onGoogleSignInError = function (message) {
  // sign-in failed: reset the button
  console.error('Google Sign-In error:', message);
};
```

Handle the cancelled case. Customers often open the picker and change their minds, and a button left spinning looks broken.

{% hint style="warning" %}
Use these callbacks for the interface only. Do not sign the customer in from the `idToken` they receive — your server must verify it first. With **URL redirect**, the app leaves the page immediately, so the callbacks have little time to run.
{% endhint %}

***

## Troubleshooting

<table><thead><tr><th width="330">Problem</th><th>Where to look</th></tr></thead><tbody><tr><td>Nothing happens when the button is tapped</td><td><code>twinr_google_sign_in</code> is undefined. Check that Google Sign-In is enabled, that the installed app is a build made after you enabled it, and that your button calls <code>handleGoogleSignIn()</code>.</td></tr><tr><td>The account picker does not appear on Android</td><td>Most often the SHA-1 on your Android OAuth client does not match the key that signed this build. Builds from Google Play use the Play app signing key; builds signed by Twinr use your Twinr keystore. Also check the device has Google Play Services and a Google account signed in.</td></tr><tr><td>Authentication fails</td><td>A client ID in Twinr does not match Google Cloud Console, or the bundle ID or package name there differs from the one Twinr shows.</td></tr><tr><td><strong>Sign In Failed</strong> appears after picking an account</td><td>Your webhook did not reply with HTTP <code>200</code>. Check it received the POST and did not reject the token — a wrong <code>aud</code> in your verification is the usual cause.</td></tr><tr><td>Your server signs the customer in, but the app still shows them signed out</td><td>You set the session cookie in the webhook reply, which the app never sees. Return a one-time sign-in link as <code>load_url</code> instead.</td></tr><tr><td>Your callback is never called</td><td>The URL must be HTTPS, publicly reachable, and must match the <strong>Send token via</strong> option you chose.</td></tr><tr><td>Works in a browser, not in the app</td><td>The installed app predates the feature. Customers need a build made after you enabled it.</td></tr></tbody></table>
