README.md

🔐 @react-native-auth/google

Modern Google Authentication for React Native

---

📋 Table of Contents

• ✨ Features
• 📦 Installation
• ⚙️ Setup
  • 📱 Step 1: Enable New Architecture
  • ☁️ Step 2: Google Cloud Console Setup
• 🚀 Usage
  • 🎯 One Tap Sign-In
  • 👤 Sign-In with Account Chooser
  • 🔐 Legacy OAuth Sign-In
• 📝 API Reference
• 🛠️ Troubleshooting
• 📄 License

---

✨ Features

🎯 Modern Authentication ✅ One Tap Sign-In (Credential Manager) ✅ Account Chooser UI ✅ Legacy OAuth Support

⚡ Built with Latest Tech ✅ TurboModule (New Architecture) ✅ Codegen Type Safety ✅ Android Only (for now)

📋 Available Methods

Method	Description	Use Case
oneTap()	One Tap / Credential Manager	Quick sign-in for returning users
signIn()	Account Chooser UI	First-time sign-in, account selection
legacySignIn()	Legacy OAuth with scopes	Advanced features (Drive, Calendar, etc.)
signOut()	Sign out current user	Logout, clear session

---

📦 Installation

# Using npm
npm install @react-native-auth/google

# Using yarn
yarn add @react-native-auth/google

---

⚙️ Setup

📱 Step 1: Enable New Architecture

Show details

Add to your android/gradle.properties:

newArchEnabled=true
kotlin.version=2.1.20

☁️ Step 2: Google Cloud Console Setup

Show details

🌐 Access Console

Go to Google Cloud Console and create/select your project.

🔌 Enable API

1. Navigate to APIs & Services → Library
2. Search for "Google Sign-In API" or "Google Identity"
3. Click Enable

🔑 Create OAuth 2.0 Credentials

You need TWO client IDs:

a) 📱 Android Client ID

For app verification (SHA-1 fingerprint required)

1. Go to APIs & Services → Credentials

2. Click Create Credentials → OAuth 2.0 Client ID

3. Select Android

4. Fill in:

   • Name: Your App (Android)

   • Package name: com.yourapp (from android/app/build.gradle)

   • SHA-1 fingerprint: Get it by running:

     # Debug
     keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
     
     # Release
     keytool -list -v -keystore /path/to/release.keystore -alias your-alias

5. Click Create

b) 🌐 Web Client ID

For authentication (USE THIS IN YOUR CODE)

1. Click Create Credentials → OAuth 2.0 Client ID again
2. Select Web application
3. Fill in:
   • Name: Your App (Web)
   • Authorized redirect URIs: Leave empty
4. Click Create
5. Copy the Web Client ID → xxxxx.apps.googleusercontent.com

💡 Pro Tip: The Android Client ID verifies your app. The Web Client ID is used for authentication.

---

🚀 Usage

📥 Import

import { oneTap, signIn, legacySignIn, signOut } from '@react-native-auth/google';

🎯 One Tap Sign-In

Quick authentication for returning users with saved credentials.

const CLIENT_ID = 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com';

try {
  const result = await oneTap({ clientId: CLIENT_ID });
  console.log('✅ Signed in:', result.idToken);
  console.log('📧 Email:', result.email);
} catch (error) {
  console.error('❌ Sign-in failed:', error);
}

👤 Sign-In with Account Chooser

Display account picker UI for first-time users or account switching.

const result = await signIn({
  clientId: CLIENT_ID,
});

🔐 Legacy OAuth Sign-In

Advanced authentication with custom OAuth scopes (Drive, Calendar, etc.)

const result = await legacySignIn({
  clientId: CLIENT_ID,
  scopes: [
    'https://www.googleapis.com/auth/drive.readonly',
    'https://www.googleapis.com/auth/calendar.readonly',
  ],
  prompt: 'consent', // Optional: Force consent screen
});

📍 prompt Parameter

Controls the authentication flow behavior:

Value	Behavior
undefined	Default behavior - no forced interaction
'consent'	Always show consent screen, even for existing app
'login'	Always show login screen, force account selection
'select_account'	Always show account selection screen
'none'	Silent authentication (may fail if no session)

Example - Force Consent Screen:

const result = await legacySignIn({
  clientId: CLIENT_ID,
  scopes: ['https://www.googleapis.com/auth/calendar'],
  prompt: 'consent', // Useful when updating permissions
});

Example - Force Account Selection:

const result = await legacySignIn({
  clientId: CLIENT_ID,
  prompt: 'select_account', // Always show account picker
});

Example - Force Login:

const result = await legacySignIn({
  clientId: CLIENT_ID,
  prompt: 'login', // Useful for switching accounts
});

🚪 Sign Out

Sign out the current user and clear the session.

try {
  await signOut();
  console.log('✅ Signed out successfully');
} catch (error) {
  console.error('❌ Sign-out failed:', error);
}

---

📝 API Reference

Types

type GoogleAuthOptions = {
  clientId: string; // Your Web Client ID
  scopes?: string[]; // OAuth scopes (legacySignIn only)
  prompt?: string; // Consent behavior: 'consent', 'login', 'none'
};

type GoogleAuthResult = {
  idToken: string; // JWT ID token
  email?: string; // User email (if available)
};

---

🛠️ Troubleshooting

Common Issues

❌ "Sign-in failed" or "Invalid client ID"

• ✅ Verify you're using the Web Client ID, not Android Client ID
• ✅ Check SHA-1 fingerprint is correctly added for Android Client ID
• ✅ Ensure Google Sign-In API is enabled in Console

❌ "Credential Manager not available"

• ✅ Test on Android 9+ (API level 28+)
• ✅ Ensure Google Play Services is updated
• ✅ Test on a physical device (emulators may have issues)

---

📄 License

---

Made with ❤️ for React Native

Report Bug · Request Feature