From 748f97336cbc4e283d999f1ebe1e3afa6931f05c Mon Sep 17 00:00:00 2001 From: ChrisCanin Date: Mon, 10 Nov 2025 16:34:55 -0800 Subject: [PATCH 01/12] Add guides for native Sign in with Google in Expo and document useSignInWithGoogle hook --- .../sign-in-with-google.expo.mdx | 383 ++++++++++++++++++ docs/reference/expo/use-google-sign-in.mdx | 236 +++++++++++ 2 files changed, 619 insertions(+) create mode 100644 docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx create mode 100644 docs/reference/expo/use-google-sign-in.mdx diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx new file mode 100644 index 0000000000..4a8f9f1359 --- /dev/null +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -0,0 +1,383 @@ +--- +title: Sign in with Google +description: Learn how to use Clerk to natively Sign in with Google in your Expo app. +sdk: expo +--- + +This guide will teach you how to add native Sign in with Google to your Clerk Expo apps. + +> [!NOTE] +> Google Sign-In works on both iOS and Android devices and requires a native build. It will not work with Expo Go. + + + ## Install dependencies + + The [@react-native-google-signin/google-signin library](https://react-native-google-signin.github.io/docs/) provides access to Google's native Sign-In functionality from your Expo app. + + Run the following command to install the library: + + ```npm {{ filename: 'terminal' }} + npm install @react-native-google-signin/google-signin + ``` + + ## Configure Google Cloud Console + + Before you can use Google Sign-In in your app, you need to create OAuth 2.0 credentials in the Google Cloud Console. + + ### Create a Google Cloud Project + + 1. Go to the [Google Cloud Console](https://console.cloud.google.com/) + 2. Create a new project or select an existing one + 3. Enable the **Google+ API** for your project + + ### Create OAuth 2.0 Credentials + + You'll need to create three sets of credentials: + + #### 1. Web Client ID (for token verification) + + 1. Navigate to **APIs & Services** → **Credentials** + 2. Click **Create Credentials** → **OAuth client ID** + 3. Select **Web application** + 4. Add a name (e.g., "Web client for token verification") + 5. Click **Create** + 6. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID` + + #### 2. iOS Client ID + + 1. Click **Create Credentials** → **OAuth client ID** + 2. Select **iOS** + 3. Add your iOS **Bundle ID** (from your `app.json` or `app.config.ts`) + 4. Click **Create** + 5. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID` + + #### 3. Android Client ID + + 1. Click **Create Credentials** → **OAuth client ID** + 2. Select **Android** + 3. Add your Android **Package name** (from your `app.json` or `app.config.ts`) + 4. Add your **SHA-1 certificate fingerprint**: + + For debug builds: + ```bash {{ filename: 'terminal' }} + # macOS/Linux + keytool -keystore ~/.android/debug.keystore -list -v -alias androiddebugkey -storepass android -keypass android + + # Windows + keytool -keystore %USERPROFILE%\.android\debug.keystore -list -v -alias androiddebugkey -storepass android -keypass android + ``` + + For release builds, use your release keystore + 5. Click **Create** + 6. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID` + + ## Add your iOS application to Clerk + + Add your iOS application to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page in the Clerk Dashboard. You will need your iOS app's **App ID Prefix** (Team ID) and **Bundle ID**. + + ## Add your Android application to Clerk + + Add your Android application to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page in the Clerk Dashboard. You will need your Android app's **Package Name**. + + ## Enable Google as a social connection + + 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For all users**. + 1. In the **Choose provider** dropdown, select **Google**. + 1. Ensure that **Enable for sign-up and sign-in** is toggled on. + + ## Configure environment variables + + Add the Google OAuth client IDs to your `.env` file: + + ```bash {{ filename: '.env' }} + EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID=your-ios-client-id.apps.googleusercontent.com + EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID=your-android-client-id.apps.googleusercontent.com + EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=your-web-client-id.apps.googleusercontent.com + ``` + + ## Add @react-native-google-signin/google-signin to your app config + + Add the `@react-native-google-signin/google-signin` plugin to your `app.json` or `app.config.ts` and configure it with your client IDs. + + + ```json {{ filename: 'app.json' }} + { + "expo": { + "plugins": [ + [ + "@react-native-google-signin/google-signin", + { + "iosClientId": "your-ios-client-id.apps.googleusercontent.com", + "androidClientId": "your-android-client-id.apps.googleusercontent.com" + } + ] + ] + } + } + ``` + + ```ts {{ filename: 'app.config.ts' }} + export default { + expo: { + plugins: [ + [ + '@react-native-google-signin/google-signin', + { + iosClientId: process.env.EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID, + androidClientId: process.env.EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID, + }, + ], + ], + }, + } + ``` + + + ## Build your sign-in flow + + The following example uses the [`useSignInWithGoogle()`](/docs/reference/expo/use-google-sign-in) hook to manage the Google sign-in flow. It handles the ID token exchange with Clerk's Backend and automatically manages the transfer flow between sign-in and sign-up. + + + + The following example demonstrates how to add Google Sign-In to your sign-in page. + + ```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }} + import { useSignIn, useSignInWithGoogle } from '@clerk/clerk-expo' + import { useRouter } from 'expo-router' + import { Text, TouchableOpacity, StyleSheet, Alert, Platform } from 'react-native' + + export default function SignInPage() { + const { signIn, setActive, isLoaded } = useSignIn() + const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + const router = useRouter() + + const onGoogleSignInPress = async () => { + try { + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() + + if (createdSessionId && setActive) { + await setActive({ session: createdSessionId }) + router.replace('/') + } + } catch (err: any) { + // User canceled the sign-in flow + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + + Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') + console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) + } + } + + // Only show on iOS and Android + if (Platform.OS !== 'ios' && Platform.OS !== 'android') { + return null + } + + return ( + <> + + Sign in with Google + + + {/* Your email/password sign-in form */} + + ) + } + + const styles = StyleSheet.create({ + googleButton: { + backgroundColor: '#4285F4', + padding: 15, + borderRadius: 8, + alignItems: 'center', + marginBottom: 10, + }, + googleButtonText: { + color: '#fff', + fontSize: 16, + fontWeight: '600', + }, + }) + ``` + + + + The following example demonstrates how to add Google Sign-In to your sign-up page. The same `useSignInWithGoogle()` hook works for both sign-in and sign-up, and Clerk automatically handles the transfer flow: + + - If the Google account exists, it completes sign-in. + - If the Google account is new, it creates a new sign-up. + + ```tsx {{ filename: 'app/(auth)/sign-up.tsx', collapsible: true }} + import { useSignUp, useSignInWithGoogle } from '@clerk/clerk-expo' + import { useRouter } from 'expo-router' + import { Text, TouchableOpacity, StyleSheet, Alert, Platform } from 'react-native' + + export default function SignUpPage() { + const { signUp, setActive, isLoaded } = useSignUp() + const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + const router = useRouter() + + const onGoogleSignInPress = async () => { + try { + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() + + if (createdSessionId && setActive) { + await setActive({ session: createdSessionId }) + router.replace('/') + } + } catch (err: any) { + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + + Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') + console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) + } + } + + if (Platform.OS !== 'ios' && Platform.OS !== 'android') { + return null + } + + return ( + <> + + Sign up with Google + + + {/* Your email/password sign-up form */} + + ) + } + + const styles = StyleSheet.create({ + googleButton: { + backgroundColor: '#4285F4', + padding: 15, + borderRadius: 8, + alignItems: 'center', + marginBottom: 10, + }, + googleButtonText: { + color: '#fff', + fontSize: 16, + fontWeight: '600', + }, + }) + ``` + + + + The following example demonstrates how to implement a reusable component that works on both sign-in and sign-up pages. + + ```tsx {{ filename: 'components/GoogleSignInButton.tsx', collapsible: true }} + import { useSignInWithGoogle } from '@clerk/clerk-expo' + import { useRouter } from 'expo-router' + import { Alert, Platform, StyleSheet, Text, TouchableOpacity, View } from 'react-native' + + interface GoogleSignInButtonProps { + onSignInComplete?: () => void + showDivider?: boolean + } + + export function GoogleSignInButton({ + onSignInComplete, + showDivider = true, + }: GoogleSignInButtonProps) { + const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + const router = useRouter() + + // Only render on iOS and Android + if (Platform.OS !== 'ios' && Platform.OS !== 'android') { + return null + } + + const handleGoogleSignIn = async () => { + try { + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() + + if (createdSessionId && setActive) { + await setActive({ session: createdSessionId }) + + if (onSignInComplete) { + onSignInComplete() + } else { + router.replace('/') + } + } + } catch (err: any) { + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + + Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') + console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) + } + } + + return ( + <> + + Sign in with Google + + + {showDivider && ( + + + OR + + + )} + + ) + } + + const styles = StyleSheet.create({ + googleButton: { + backgroundColor: '#4285F4', + padding: 15, + borderRadius: 8, + alignItems: 'center', + marginBottom: 10, + }, + googleButtonText: { + color: '#fff', + fontSize: 16, + fontWeight: '600', + }, + divider: { + flexDirection: 'row', + alignItems: 'center', + marginVertical: 20, + }, + dividerLine: { + flex: 1, + height: 1, + backgroundColor: '#ccc', + }, + dividerText: { + marginHorizontal: 10, + color: '#666', + }, + }) + ``` + + + + ## Create a native build + + Create a native build with EAS Build or a local prebuild, since Google Sign-In is not supported in Expo Go. + + ```bash {{ filename: 'terminal' }} + # Using EAS Build + eas build --platform ios + eas build --platform android + + # Or using local prebuild + npx expo prebuild && npx expo run:ios --device + npx expo prebuild && npx expo run:android --device + ``` + diff --git a/docs/reference/expo/use-google-sign-in.mdx b/docs/reference/expo/use-google-sign-in.mdx new file mode 100644 index 0000000000..79425ebb4c --- /dev/null +++ b/docs/reference/expo/use-google-sign-in.mdx @@ -0,0 +1,236 @@ +--- +title: '`useSignInWithGoogle()`' +description: Clerk's useSignInWithGoogle() hook provides native Sign in with Google functionality for iOS and Android devices. +sdk: expo +--- + +> [!NOTE] +> This hook is available on iOS and Android devices and requires a native build. It will not work with Expo Go. + +The `useSignInWithGoogle()` hook provides native Sign in with Google functionality for iOS and Android devices. It automatically handles the ID token exchange with Clerk's Backend and manages the transfer flow between sign-in and sign-up. + + + +## Returns + +The `useSignInWithGoogle()` hook returns the `startGoogleAuthenticationFlow()` method, which you can use to initiate the native Google Sign-In flow. + +### `startGoogleAuthenticationFlow()` + +`startGoogleAuthenticationFlow()` has the following function signature: + +```ts +function startGoogleAuthenticationFlow( + startGoogleAuthenticationFlowParams?: StartGoogleAuthenticationFlowParams, +): Promise +``` + +#### Parameters + +`startGoogleAuthenticationFlow()` accepts the following parameters (`StartGoogleAuthenticationFlowParams`): + + + - `unsafeMetadata?` + - [`SignUpUnsafeMetadata`](/docs/reference/javascript/types/metadata#sign-up-unsafe-metadata) + + Metadata that can be read and set from the frontend and the backend. Once the authentication process is complete, the value of this field will be automatically copied to the created user's unsafe metadata (`User.unsafeMetadata`). One common use case is to collect custom information about the user during the authentication process and store it in this property. Read more about [unsafe metadata](/docs/guides/users/extending#unsafe-metadata). + + +#### Returns + +`startGoogleAuthenticationFlow()` returns the following: + + + - `createdSessionId` + - `string | null` + + The ID of the session that was created, if authentication is successful. + + --- + + - `setActive?` + - `(params: SetActiveParams) => Promise` + + A method used to set the active session and/or organization. Accepts a [`SetActiveParams`](/docs/reference/javascript/types/set-active-params) object. + + --- + + - `signIn?` + - [SignIn](/docs/reference/javascript/sign-in) | undefined + + The [`SignIn`](/docs/reference/javascript/sign-in) object that was created, which holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. + + --- + + - `signUp?` + - [SignUp](/docs/reference/javascript/sign-up) | undefined + + The [`SignUp`](/docs/reference/javascript/sign-up) object that was created, which holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process. + + +## How to use the `useSignInWithGoogle()` hook + +### Basic usage + +The following example uses the `useSignInWithGoogle()` hook to manage both sign-in and sign-up flows. Clerk automatically handles the transfer flow based on whether the Google account already exists: + +- If the Google account exists, it completes sign-in. +- If the Google account is new, it creates a new sign-up. + +```tsx {{ filename: 'app/(auth)/sign-in.tsx' }} +import { useSignInWithGoogle } from '@clerk/clerk-expo' +import { useRouter } from 'expo-router' +import { Alert, Platform, TouchableOpacity, Text } from 'react-native' + +export default function SignInPage() { + const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + const router = useRouter() + + const onGoogleSignInPress = async () => { + try { + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() + + if (createdSessionId && setActive) { + await setActive({ session: createdSessionId }) + router.replace('/') + } + } catch (err: any) { + // User canceled the sign-in flow + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + + Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') + console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) + } + } + + // Only show on iOS and Android + if (Platform.OS !== 'ios' && Platform.OS !== 'android') { + return null + } + + return ( + + Sign in with Google + + ) +} +``` + +### With custom metadata + +The following example demonstrates how to pass custom metadata that will be saved to the user's unsafe metadata during sign-up. + +```tsx +const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + +const onGoogleSignInPress = async () => { + try { + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow({ + unsafeMetadata: { + referralSource: 'mobile-app', + signupDate: new Date().toISOString(), + }, + }) + + if (createdSessionId && setActive) { + await setActive({ session: createdSessionId }) + // Navigate to home or onboarding + } + } catch (err: any) { + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + // Handle error + } +} +``` + +### Reusable component + +The following example demonstrates how to implement a reusable component that works on both sign-in and sign-up pages. + +```tsx {{ filename: 'components/GoogleSignInButton.tsx', collapsible: true }} +import { useSignInWithGoogle } from '@clerk/clerk-expo' +import { useRouter } from 'expo-router' +import { Alert, Platform, StyleSheet, Text, TouchableOpacity } from 'react-native' + +interface GoogleSignInButtonProps { + onSignInComplete?: () => void +} + +export function GoogleSignInButton({ onSignInComplete }: GoogleSignInButtonProps) { + const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + const router = useRouter() + + // Only render on iOS and Android + if (Platform.OS !== 'ios' && Platform.OS !== 'android') { + return null + } + + const handleGoogleSignIn = async () => { + try { + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() + + if (createdSessionId && setActive) { + await setActive({ session: createdSessionId }) + + if (onSignInComplete) { + onSignInComplete() + } else { + router.replace('/') + } + } + } catch (err: any) { + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + + Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') + console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) + } + } + + return ( + + Sign in with Google + + ) +} + +const styles = StyleSheet.create({ + googleButton: { + backgroundColor: '#4285F4', + padding: 15, + borderRadius: 8, + alignItems: 'center', + }, + googleButtonText: { + color: '#fff', + fontSize: 16, + fontWeight: '600', + }, +}) +``` + +## Error handling + +The `useSignInWithGoogle()` hook may throw errors in the following scenarios: + +- **User cancellation**: The user cancels the sign-in flow, resulting in an error with code `SIGN_IN_CANCELLED` or `-5`. +- **Platform error**: The hook is called on an unsupported platform (not iOS or Android). +- **Missing package**: The `@react-native-google-signin/google-signin` package is not installed. +- **Authentication failure**: Google authentication fails or the returned ID token is invalid. +- **Play Services error** (Android only): Google Play Services is not available or outdated on the device. + +> [!IMPORTANT] +> Always wrap calls to `startGoogleAuthenticationFlow()` in a `try/catch` block, and handle the `SIGN_IN_CANCELLED` and `-5` error codes separately. From 9db3d01e4ab5def56bfc335da021dc27e1365b2d Mon Sep 17 00:00:00 2001 From: ChrisCanin Date: Thu, 13 Nov 2025 18:47:13 -0800 Subject: [PATCH 02/12] Update Sign in with Google guide and add useSignInWithGoogle reference --- .../sign-in-with-google.expo.mdx | 33 ++++++++++--------- docs/manifest.json | 4 +++ 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx index 4a8f9f1359..bbb1605030 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -27,8 +27,8 @@ This guide will teach you how to add native Sign in with Google to your Clerk Ex ### Create a Google Cloud Project 1. Go to the [Google Cloud Console](https://console.cloud.google.com/) - 2. Create a new project or select an existing one - 3. Enable the **Google+ API** for your project + 1. Create a new project or select an existing one + 1. Enable the **Google+ API** for your project ### Create OAuth 2.0 Credentials @@ -37,28 +37,29 @@ This guide will teach you how to add native Sign in with Google to your Clerk Ex #### 1. Web Client ID (for token verification) 1. Navigate to **APIs & Services** → **Credentials** - 2. Click **Create Credentials** → **OAuth client ID** - 3. Select **Web application** - 4. Add a name (e.g., "Web client for token verification") - 5. Click **Create** - 6. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID` + 1. Click **Create Credentials** → **OAuth client ID** + 1. Select **Web application** + 1. Add a name (e.g., "Web client for token verification") + 1. Click **Create** + 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID` #### 2. iOS Client ID 1. Click **Create Credentials** → **OAuth client ID** - 2. Select **iOS** - 3. Add your iOS **Bundle ID** (from your `app.json` or `app.config.ts`) - 4. Click **Create** - 5. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID` + 1. Select **iOS** + 1. Add your iOS **Bundle ID** (from your `app.json` or `app.config.ts`) + 1. Click **Create** + 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID` #### 3. Android Client ID 1. Click **Create Credentials** → **OAuth client ID** - 2. Select **Android** - 3. Add your Android **Package name** (from your `app.json` or `app.config.ts`) - 4. Add your **SHA-1 certificate fingerprint**: + 1. Select **Android** + 1. Add your Android **Package name** (from your `app.json` or `app.config.ts`) + 1. Add your **SHA-1 certificate fingerprint**: For debug builds: + ```bash {{ filename: 'terminal' }} # macOS/Linux keytool -keystore ~/.android/debug.keystore -list -v -alias androiddebugkey -storepass android -keypass android @@ -68,8 +69,8 @@ This guide will teach you how to add native Sign in with Google to your Clerk Ex ``` For release builds, use your release keystore - 5. Click **Create** - 6. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID` + 1. Click **Create** + 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID` ## Add your iOS application to Clerk diff --git a/docs/manifest.json b/docs/manifest.json index e2d45c319a..b218f95f69 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1590,6 +1590,10 @@ "title": "`useSignInWithApple()`", "href": "/docs/reference/expo/use-sign-in-with-apple" }, + { + "title": "`useSignInWithGoogle()`", + "href": "/docs/reference/expo/use-google-sign-in" + }, { "title": "`useSSO()`", "href": "/docs/reference/expo/use-sso" From dabc038a59f4b29bff73039917ccafe816182f68 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Thu, 20 Nov 2025 09:33:48 -0600 Subject: [PATCH 03/12] docs review --- .../expo/use-sign-in-with-google-example.mdx | 93 +++++ .../sign-in-with-google.expo.mdx | 346 ++++-------------- .../auth-strategies/sign-in-with-google.mdx | 2 +- docs/manifest.json | 2 +- docs/reference/expo/use-google-sign-in.mdx | 236 ------------ .../expo/use-sign-in-with-google.mdx | 0 6 files changed, 160 insertions(+), 519 deletions(-) create mode 100644 docs/_partials/expo/use-sign-in-with-google-example.mdx delete mode 100644 docs/reference/expo/use-google-sign-in.mdx create mode 100644 docs/reference/expo/use-sign-in-with-google.mdx diff --git a/docs/_partials/expo/use-sign-in-with-google-example.mdx b/docs/_partials/expo/use-sign-in-with-google-example.mdx new file mode 100644 index 0000000000..6a6811b985 --- /dev/null +++ b/docs/_partials/expo/use-sign-in-with-google-example.mdx @@ -0,0 +1,93 @@ +The following example demonstrates how to use the [`useSignInWithGoogle()`](/docs/reference/expo/use-sign-in-with-google) hook to manage the Google authentication flow. Because the `useSignInWithGoogle()` hook automatically manages the [transfer flow](!transfer-flow) between sign-up and sign-in, you can use this component for both your sign-up and sign-in pages. + +```tsx {{ filename: 'components/GoogleSignInButton.tsx', collapsible: true }} +import { useSignInWithGoogle } from '@clerk/clerk-expo' +import { useRouter } from 'expo-router' +import { Alert, Platform, StyleSheet, Text, TouchableOpacity, View } from 'react-native' + +interface GoogleSignInButtonProps { + onSignInComplete?: () => void + showDivider?: boolean +} + +export function GoogleSignInButton({ + onSignInComplete, + showDivider = true, +}: GoogleSignInButtonProps) { + const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + const router = useRouter() + + // Only render on iOS and Android + if (Platform.OS !== 'ios' && Platform.OS !== 'android') { + return null + } + + const handleGoogleSignIn = async () => { + try { + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() + + if (createdSessionId && setActive) { + await setActive({ session: createdSessionId }) + + if (onSignInComplete) { + onSignInComplete() + } else { + router.replace('/') + } + } + } catch (err: any) { + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + + Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') + console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) + } + } + + return ( + <> + + Sign in with Google + + + {showDivider && ( + + + OR + + + )} + + ) +} + +const styles = StyleSheet.create({ + googleButton: { + backgroundColor: '#4285F4', + padding: 15, + borderRadius: 8, + alignItems: 'center', + marginBottom: 10, + }, + googleButtonText: { + color: '#fff', + fontSize: 16, + fontWeight: '600', + }, + divider: { + flexDirection: 'row', + alignItems: 'center', + marginVertical: 20, + }, + dividerLine: { + flex: 1, + height: 1, + backgroundColor: '#ccc', + }, + dividerText: { + marginHorizontal: 10, + color: '#666', + }, +}) +``` diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx index bbb1605030..f9a93c5609 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -4,21 +4,35 @@ description: Learn how to use Clerk to natively Sign in with Google in your Expo sdk: expo --- -This guide will teach you how to add native Sign in with Google to your Clerk Expo apps. + -> [!NOTE] -> Google Sign-In works on both iOS and Android devices and requires a native build. It will not work with Expo Go. +[Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) helps you easily and securely sign in to third-party apps or services with your Google Account, without having to enter a username and password repeatedly across different services. - - ## Install dependencies +This guide will teach you how to add native Sign in with Google to your Clerk Expo application. This is different from Google OAuth - if you want to use Google OAuth, see the [dedicated guide](/docs/guides/configure/auth-strategies/social-connections/google). - The [@react-native-google-signin/google-signin library](https://react-native-google-signin.github.io/docs/) provides access to Google's native Sign-In functionality from your Expo app. +To make the setup process easier, it's recommended to keep two browser tabs open - one for the [Clerk Dashboard](https://dashboard.clerk.com/~/user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). - Run the following command to install the library: + + ## Enable Google as a social connection - ```npm {{ filename: 'terminal' }} - npm install @react-native-google-signin/google-signin - ``` + 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page. + 1. Select **Add connection** and select **For all users**. + 1. In the **Choose provider** dropdown, select **Google**. + 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. + 1. Save the **Authorized Redirect URI** somewhere secure. Keep this modal and page open. ## Configure Google Cloud Console @@ -26,51 +40,47 @@ This guide will teach you how to add native Sign in with Google to your Clerk Ex ### Create a Google Cloud Project - 1. Go to the [Google Cloud Console](https://console.cloud.google.com/) - 1. Create a new project or select an existing one - 1. Enable the **Google+ API** for your project + 1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/). + 1. Select an existing project or [create a new one](https://console.cloud.google.com/projectcreate). You'll be redirected to your project's **Dashboard** page. + 1. Enable the **Google+ API** for your project. ### Create OAuth 2.0 Credentials You'll need to create three sets of credentials: - #### 1. Web Client ID (for token verification) + #### Web Client ID (for token verification) - 1. Navigate to **APIs & Services** → **Credentials** - 1. Click **Create Credentials** → **OAuth client ID** - 1. Select **Web application** - 1. Add a name (e.g., "Web client for token verification") - 1. Click **Create** - 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID` + 1. Navigate to **APIs & Services**. Then, select **Credentials**. + 1. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. You might need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849#userconsent). Otherwise, you'll be redirected to the **Create OAuth client ID** page. + 1. For the **Application type**, select **Web application**. + 1. Add a name (e.g., "Web client for token verification"). + 1. Select **Create**. + 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID`. - #### 2. iOS Client ID + #### iOS Client ID - 1. Click **Create Credentials** → **OAuth client ID** - 1. Select **iOS** - 1. Add your iOS **Bundle ID** (from your `app.json` or `app.config.ts`) - 1. Click **Create** - 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID` + 1. In the same project, create another client. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. + 1. For the **Application type**, select **iOS**. + 1. Add your iOS **Bundle ID** (from your `app.json` or `app.config.ts`). + 1. Select **Create**. + 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID`. - #### 3. Android Client ID + #### Android Client ID - 1. Click **Create Credentials** → **OAuth client ID** - 1. Select **Android** - 1. Add your Android **Package name** (from your `app.json` or `app.config.ts`) - 1. Add your **SHA-1 certificate fingerprint**: + 1. In the same project, create another client. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. + 1. For the **Application type**, select **Android**. + 1. Complete the required fields: + - **Package name**: Your package name is in your `app.json` or `app.config.ts`. + - **SHA-1 certificate fingerprint**: To get your SHA-1, run the following command in your terminal: - For debug builds: + ```sh {{ filename: 'terminal' }} + $ keytool -keystore path-to-debug-or-production-keystore -list -v + ``` - ```bash {{ filename: 'terminal' }} - # macOS/Linux - keytool -keystore ~/.android/debug.keystore -list -v -alias androiddebugkey -storepass android -keypass android - - # Windows - keytool -keystore %USERPROFILE%\.android\debug.keystore -list -v -alias androiddebugkey -storepass android -keypass android - ``` - - For release builds, use your release keystore - 1. Click **Create** - 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID` + > [!NOTE] + > Replace `path-to-debug-or-production-keystore` with the path to your debug or ßproduction keystore. By default, the debug keystore is located in `~/.android/debug.keystore`. It may ask for a keystore password, which is `android`. **Please note that Java is required to run the `keytool` command.** + 1. Select **Create**. + 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID`. ## Add your iOS application to Clerk @@ -78,14 +88,17 @@ This guide will teach you how to add native Sign in with Google to your Clerk Ex ## Add your Android application to Clerk - Add your Android application to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page in the Clerk Dashboard. You will need your Android app's **Package Name**. + Add your Android application to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page in the Clerk Dashboard. You will need your Android app's **package Name**. - ## Enable Google as a social connection + ## Install dependencies - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. - 1. Select **Add connection** and select **For all users**. - 1. In the **Choose provider** dropdown, select **Google**. - 1. Ensure that **Enable for sign-up and sign-in** is toggled on. + The [@react-native-google-signin/google-signin library](https://react-native-google-signin.github.io/docs/) provides access to Google's native Sign-In functionality from your Expo app. + + Run the following command to install the library: + + ```npm + npm install @react-native-google-signin/google-signin + ``` ## Configure environment variables @@ -135,242 +148,13 @@ This guide will teach you how to add native Sign in with Google to your Clerk Ex ``` - ## Build your sign-in flow - - The following example uses the [`useSignInWithGoogle()`](/docs/reference/expo/use-google-sign-in) hook to manage the Google sign-in flow. It handles the ID token exchange with Clerk's Backend and automatically manages the transfer flow between sign-in and sign-up. - - - - The following example demonstrates how to add Google Sign-In to your sign-in page. - - ```tsx {{ filename: 'app/(auth)/sign-in.tsx', collapsible: true }} - import { useSignIn, useSignInWithGoogle } from '@clerk/clerk-expo' - import { useRouter } from 'expo-router' - import { Text, TouchableOpacity, StyleSheet, Alert, Platform } from 'react-native' - - export default function SignInPage() { - const { signIn, setActive, isLoaded } = useSignIn() - const { startGoogleAuthenticationFlow } = useSignInWithGoogle() - const router = useRouter() - - const onGoogleSignInPress = async () => { - try { - const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() - - if (createdSessionId && setActive) { - await setActive({ session: createdSessionId }) - router.replace('/') - } - } catch (err: any) { - // User canceled the sign-in flow - if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { - return - } - - Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') - console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) - } - } - - // Only show on iOS and Android - if (Platform.OS !== 'ios' && Platform.OS !== 'android') { - return null - } - - return ( - <> - - Sign in with Google - - - {/* Your email/password sign-in form */} - - ) - } - - const styles = StyleSheet.create({ - googleButton: { - backgroundColor: '#4285F4', - padding: 15, - borderRadius: 8, - alignItems: 'center', - marginBottom: 10, - }, - googleButtonText: { - color: '#fff', - fontSize: 16, - fontWeight: '600', - }, - }) - ``` - - - - The following example demonstrates how to add Google Sign-In to your sign-up page. The same `useSignInWithGoogle()` hook works for both sign-in and sign-up, and Clerk automatically handles the transfer flow: - - - If the Google account exists, it completes sign-in. - - If the Google account is new, it creates a new sign-up. - - ```tsx {{ filename: 'app/(auth)/sign-up.tsx', collapsible: true }} - import { useSignUp, useSignInWithGoogle } from '@clerk/clerk-expo' - import { useRouter } from 'expo-router' - import { Text, TouchableOpacity, StyleSheet, Alert, Platform } from 'react-native' - - export default function SignUpPage() { - const { signUp, setActive, isLoaded } = useSignUp() - const { startGoogleAuthenticationFlow } = useSignInWithGoogle() - const router = useRouter() - - const onGoogleSignInPress = async () => { - try { - const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() - - if (createdSessionId && setActive) { - await setActive({ session: createdSessionId }) - router.replace('/') - } - } catch (err: any) { - if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { - return - } - - Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') - console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) - } - } - - if (Platform.OS !== 'ios' && Platform.OS !== 'android') { - return null - } - - return ( - <> - - Sign up with Google - - - {/* Your email/password sign-up form */} - - ) - } - - const styles = StyleSheet.create({ - googleButton: { - backgroundColor: '#4285F4', - padding: 15, - borderRadius: 8, - alignItems: 'center', - marginBottom: 10, - }, - googleButtonText: { - color: '#fff', - fontSize: 16, - fontWeight: '600', - }, - }) - ``` - - - - The following example demonstrates how to implement a reusable component that works on both sign-in and sign-up pages. - - ```tsx {{ filename: 'components/GoogleSignInButton.tsx', collapsible: true }} - import { useSignInWithGoogle } from '@clerk/clerk-expo' - import { useRouter } from 'expo-router' - import { Alert, Platform, StyleSheet, Text, TouchableOpacity, View } from 'react-native' - - interface GoogleSignInButtonProps { - onSignInComplete?: () => void - showDivider?: boolean - } - - export function GoogleSignInButton({ - onSignInComplete, - showDivider = true, - }: GoogleSignInButtonProps) { - const { startGoogleAuthenticationFlow } = useSignInWithGoogle() - const router = useRouter() - - // Only render on iOS and Android - if (Platform.OS !== 'ios' && Platform.OS !== 'android') { - return null - } - - const handleGoogleSignIn = async () => { - try { - const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() - - if (createdSessionId && setActive) { - await setActive({ session: createdSessionId }) - - if (onSignInComplete) { - onSignInComplete() - } else { - router.replace('/') - } - } - } catch (err: any) { - if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { - return - } - - Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') - console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) - } - } - - return ( - <> - - Sign in with Google - - - {showDivider && ( - - - OR - - - )} - - ) - } + ## Build your authentication flow - const styles = StyleSheet.create({ - googleButton: { - backgroundColor: '#4285F4', - padding: 15, - borderRadius: 8, - alignItems: 'center', - marginBottom: 10, - }, - googleButtonText: { - color: '#fff', - fontSize: 16, - fontWeight: '600', - }, - divider: { - flexDirection: 'row', - alignItems: 'center', - marginVertical: 20, - }, - dividerLine: { - flex: 1, - height: 1, - backgroundColor: '#ccc', - }, - dividerText: { - marginHorizontal: 10, - color: '#666', - }, - }) - ``` - - + ## Create a native build - Create a native build with EAS Build or a local prebuild, since Google Sign-In is not supported in Expo Go. + Create a native build with EAS Build or a local prebuild, since Google Authentication is not supported in Expo Go. ```bash {{ filename: 'terminal' }} # Using EAS Build diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx index 17dc76cbc1..0518b888a1 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx @@ -41,7 +41,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the top-left, select the menu icon (**≡**) and select **APIs & Services**. Then, select **Credentials**. 1. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID.** You might need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849#userconsent). Otherwise, you'll be redirected to the **Create OAuth client ID** page. 1. For the **Application type**, select **Android**. - 1. Complete the required fields. + 1. Complete the required fields: - **Package name**: Your package name is in your `build.gradle` file, formatted as `com.example.myclerkapp`. - **SHA-1 certificate fingerprint**: To get your SHA-1, run the following command in your terminal: diff --git a/docs/manifest.json b/docs/manifest.json index b218f95f69..f4e5650f69 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1592,7 +1592,7 @@ }, { "title": "`useSignInWithGoogle()`", - "href": "/docs/reference/expo/use-google-sign-in" + "href": "/docs/reference/expo/use-sign-in-with-google" }, { "title": "`useSSO()`", diff --git a/docs/reference/expo/use-google-sign-in.mdx b/docs/reference/expo/use-google-sign-in.mdx deleted file mode 100644 index 79425ebb4c..0000000000 --- a/docs/reference/expo/use-google-sign-in.mdx +++ /dev/null @@ -1,236 +0,0 @@ ---- -title: '`useSignInWithGoogle()`' -description: Clerk's useSignInWithGoogle() hook provides native Sign in with Google functionality for iOS and Android devices. -sdk: expo ---- - -> [!NOTE] -> This hook is available on iOS and Android devices and requires a native build. It will not work with Expo Go. - -The `useSignInWithGoogle()` hook provides native Sign in with Google functionality for iOS and Android devices. It automatically handles the ID token exchange with Clerk's Backend and manages the transfer flow between sign-in and sign-up. - - - -## Returns - -The `useSignInWithGoogle()` hook returns the `startGoogleAuthenticationFlow()` method, which you can use to initiate the native Google Sign-In flow. - -### `startGoogleAuthenticationFlow()` - -`startGoogleAuthenticationFlow()` has the following function signature: - -```ts -function startGoogleAuthenticationFlow( - startGoogleAuthenticationFlowParams?: StartGoogleAuthenticationFlowParams, -): Promise -``` - -#### Parameters - -`startGoogleAuthenticationFlow()` accepts the following parameters (`StartGoogleAuthenticationFlowParams`): - - - - `unsafeMetadata?` - - [`SignUpUnsafeMetadata`](/docs/reference/javascript/types/metadata#sign-up-unsafe-metadata) - - Metadata that can be read and set from the frontend and the backend. Once the authentication process is complete, the value of this field will be automatically copied to the created user's unsafe metadata (`User.unsafeMetadata`). One common use case is to collect custom information about the user during the authentication process and store it in this property. Read more about [unsafe metadata](/docs/guides/users/extending#unsafe-metadata). - - -#### Returns - -`startGoogleAuthenticationFlow()` returns the following: - - - - `createdSessionId` - - `string | null` - - The ID of the session that was created, if authentication is successful. - - --- - - - `setActive?` - - `(params: SetActiveParams) => Promise` - - A method used to set the active session and/or organization. Accepts a [`SetActiveParams`](/docs/reference/javascript/types/set-active-params) object. - - --- - - - `signIn?` - - [SignIn](/docs/reference/javascript/sign-in) | undefined - - The [`SignIn`](/docs/reference/javascript/sign-in) object that was created, which holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. - - --- - - - `signUp?` - - [SignUp](/docs/reference/javascript/sign-up) | undefined - - The [`SignUp`](/docs/reference/javascript/sign-up) object that was created, which holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process. - - -## How to use the `useSignInWithGoogle()` hook - -### Basic usage - -The following example uses the `useSignInWithGoogle()` hook to manage both sign-in and sign-up flows. Clerk automatically handles the transfer flow based on whether the Google account already exists: - -- If the Google account exists, it completes sign-in. -- If the Google account is new, it creates a new sign-up. - -```tsx {{ filename: 'app/(auth)/sign-in.tsx' }} -import { useSignInWithGoogle } from '@clerk/clerk-expo' -import { useRouter } from 'expo-router' -import { Alert, Platform, TouchableOpacity, Text } from 'react-native' - -export default function SignInPage() { - const { startGoogleAuthenticationFlow } = useSignInWithGoogle() - const router = useRouter() - - const onGoogleSignInPress = async () => { - try { - const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() - - if (createdSessionId && setActive) { - await setActive({ session: createdSessionId }) - router.replace('/') - } - } catch (err: any) { - // User canceled the sign-in flow - if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { - return - } - - Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') - console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) - } - } - - // Only show on iOS and Android - if (Platform.OS !== 'ios' && Platform.OS !== 'android') { - return null - } - - return ( - - Sign in with Google - - ) -} -``` - -### With custom metadata - -The following example demonstrates how to pass custom metadata that will be saved to the user's unsafe metadata during sign-up. - -```tsx -const { startGoogleAuthenticationFlow } = useSignInWithGoogle() - -const onGoogleSignInPress = async () => { - try { - const { createdSessionId, setActive } = await startGoogleAuthenticationFlow({ - unsafeMetadata: { - referralSource: 'mobile-app', - signupDate: new Date().toISOString(), - }, - }) - - if (createdSessionId && setActive) { - await setActive({ session: createdSessionId }) - // Navigate to home or onboarding - } - } catch (err: any) { - if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { - return - } - // Handle error - } -} -``` - -### Reusable component - -The following example demonstrates how to implement a reusable component that works on both sign-in and sign-up pages. - -```tsx {{ filename: 'components/GoogleSignInButton.tsx', collapsible: true }} -import { useSignInWithGoogle } from '@clerk/clerk-expo' -import { useRouter } from 'expo-router' -import { Alert, Platform, StyleSheet, Text, TouchableOpacity } from 'react-native' - -interface GoogleSignInButtonProps { - onSignInComplete?: () => void -} - -export function GoogleSignInButton({ onSignInComplete }: GoogleSignInButtonProps) { - const { startGoogleAuthenticationFlow } = useSignInWithGoogle() - const router = useRouter() - - // Only render on iOS and Android - if (Platform.OS !== 'ios' && Platform.OS !== 'android') { - return null - } - - const handleGoogleSignIn = async () => { - try { - const { createdSessionId, setActive } = await startGoogleAuthenticationFlow() - - if (createdSessionId && setActive) { - await setActive({ session: createdSessionId }) - - if (onSignInComplete) { - onSignInComplete() - } else { - router.replace('/') - } - } - } catch (err: any) { - if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { - return - } - - Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') - console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) - } - } - - return ( - - Sign in with Google - - ) -} - -const styles = StyleSheet.create({ - googleButton: { - backgroundColor: '#4285F4', - padding: 15, - borderRadius: 8, - alignItems: 'center', - }, - googleButtonText: { - color: '#fff', - fontSize: 16, - fontWeight: '600', - }, -}) -``` - -## Error handling - -The `useSignInWithGoogle()` hook may throw errors in the following scenarios: - -- **User cancellation**: The user cancels the sign-in flow, resulting in an error with code `SIGN_IN_CANCELLED` or `-5`. -- **Platform error**: The hook is called on an unsupported platform (not iOS or Android). -- **Missing package**: The `@react-native-google-signin/google-signin` package is not installed. -- **Authentication failure**: Google authentication fails or the returned ID token is invalid. -- **Play Services error** (Android only): Google Play Services is not available or outdated on the device. - -> [!IMPORTANT] -> Always wrap calls to `startGoogleAuthenticationFlow()` in a `try/catch` block, and handle the `SIGN_IN_CANCELLED` and `-5` error codes separately. diff --git a/docs/reference/expo/use-sign-in-with-google.mdx b/docs/reference/expo/use-sign-in-with-google.mdx new file mode 100644 index 0000000000..e69de29bb2 From d7c9f14683d5c267d7b4f2c4fb29851caa082c46 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Thu, 20 Nov 2025 09:43:37 -0600 Subject: [PATCH 04/12] Fix build --- .../expo/use-sign-in-with-google.mdx | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) diff --git a/docs/reference/expo/use-sign-in-with-google.mdx b/docs/reference/expo/use-sign-in-with-google.mdx index e69de29bb2..04f67e1fbd 100644 --- a/docs/reference/expo/use-sign-in-with-google.mdx +++ b/docs/reference/expo/use-sign-in-with-google.mdx @@ -0,0 +1,151 @@ +--- +title: '`useSignInWithGoogle()`' +description: Clerk's useSignInWithGoogle() hook provides native Sign in with Google functionality for iOS and Android devices. +sdk: expo +--- + + + + +> [!NOTE] +> This hook is available on iOS and Android devices and requires a native build. It will not work with Expo Go. + +The `useSignInWithGoogle()` hook provides native [Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) functionality for iOS and Android devices. It handles the ID token exchange with Clerk's backend and automatically manages the [transfer flow](!transfer-flow) between sign-up and sign-in. + +## Returns + +The `useSignInWithGoogle()` hook returns the `startGoogleAuthenticationFlow()` method, which you can use to initiate the native Google Sign-In flow. + +### `startGoogleAuthenticationFlow()` + +`startGoogleAuthenticationFlow()` has the following function signature: + +```ts +function startGoogleAuthenticationFlow( + startGoogleAuthenticationFlowParams?: StartGoogleAuthenticationFlowParams, +): Promise +``` + +#### Parameters + +`startGoogleAuthenticationFlow()` accepts the following parameters (`StartGoogleAuthenticationFlowParams`): + + + - `unsafeMetadata?` + - [`SignUpUnsafeMetadata`](/docs/reference/javascript/types/metadata#sign-up-unsafe-metadata) + + Metadata that can be read and set from the frontend and the backend. Once the authentication process is complete, the value of this field will be automatically copied to the created user's unsafe metadata (`User.unsafeMetadata`). One common use case is to collect custom information about the user during the authentication process and store it in this property. Read more about [unsafe metadata](/docs/guides/users/extending#unsafe-metadata). + + +#### Returns + +`startGoogleAuthenticationFlow()` returns the following: + + + - `createdSessionId` + - `string | null` + + The ID of the session that was created, if authentication is successful. + + --- + + - `setActive?` + - `(params: SetActiveParams) => Promise` + + A method used to set the active session and/or organization. Accepts a [`SetActiveParams`](/docs/reference/javascript/types/set-active-params) object. + + --- + + - `signIn?` + - [SignIn](/docs/reference/javascript/sign-in) | undefined + + The [`SignIn`](/docs/reference/javascript/sign-in) object that was created, which holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. + + --- + + - `signUp?` + - [SignUp](/docs/reference/javascript/sign-up) | undefined + + The [`SignUp`](/docs/reference/javascript/sign-up) object that was created, which holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process. + + +## Examples + +### Reusable component + + + +### With custom metadata + +The following example demonstrates how to pass custom metadata that will be saved to the user's [unsafe metadata](/docs/guides/users/extending#unsafe-metadata) during sign-up. + +```tsx {{ filename: 'app/(auth)/sign-in.tsx' }} +import { useRouter } from 'expo-router' +import { useSignInWithGoogle } from '@clerk/clerk-expo' +import { Alert, Platform, TouchableOpacity, Text } from 'react-native' + +export default function SignInPage() { + const { startGoogleAuthenticationFlow } = useSignInWithGoogle() + const router = useRouter() + + // Only show on iOS and Android + if (Platform.OS !== 'ios' && Platform.OS !== 'android') { + return null + } + + const onGoogleSignInPress = async () => { + try { + const { createdSessionId, setActive } = await startAppleAuthenticationFlow({ + // Add information about the user to their unsafe metadata + unsafeMetadata: { + referralSource: 'mobile-app', + signupDate: new Date().toISOString(), + }, + }) + + if (createdSessionId && setActive) { + // Set the created session as the active session + await setActive({ session: createdSessionId }) + // Once the session is set as active, + // redirect the user to the home page + router.replace('/') + } + } catch (err: any) { + // User canceled the sign-in flow + if (err.code === 'SIGN_IN_CANCELLED' || err.code === '-5') { + return + } + + Alert.alert('Error', err.message || 'An error occurred during Google Sign-In') + console.error('Google Sign-In error:', JSON.stringify(err, null, 2)) + } + } + + return ( + + Sign in with Google + + ) +} +``` + +## Error handling + +The `useSignInWithGoogle()` hook may throw errors in the following scenarios: + +- **User cancellation**: The user cancels the sign-in flow, resulting in an error with code `SIGN_IN_CANCELLED` or `-5`. +- **Platform error**: The hook is called on an unsupported platform (not iOS or Android). +- **Missing package**: The `@react-native-google-signin/google-signin` package is not installed. +- **Authentication failure**: Google authentication fails or the returned ID token is invalid. +- **Play Services error** (Android only): Google Play Services is not available or outdated on the device. + +> [!IMPORTANT] +> Always wrap calls to `startGoogleAuthenticationFlow()` in a `try/catch` block, and handle the `SIGN_IN_CANCELLED` and `-5` error codes separately. \ No newline at end of file From 4e88cb36c286eaa54cbf97fb98c3c4ef239f0773 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Thu, 20 Nov 2025 09:45:07 -0600 Subject: [PATCH 05/12] Fix wrong method --- docs/reference/expo/use-sign-in-with-google.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/reference/expo/use-sign-in-with-google.mdx b/docs/reference/expo/use-sign-in-with-google.mdx index 04f67e1fbd..dfbbfe7806 100644 --- a/docs/reference/expo/use-sign-in-with-google.mdx +++ b/docs/reference/expo/use-sign-in-with-google.mdx @@ -14,7 +14,6 @@ sdk: expo ]} /> - > [!NOTE] > This hook is available on iOS and Android devices and requires a native build. It will not work with Expo Go. @@ -103,7 +102,7 @@ export default function SignInPage() { const onGoogleSignInPress = async () => { try { - const { createdSessionId, setActive } = await startAppleAuthenticationFlow({ + const { createdSessionId, setActive } = await startGoogleAuthenticationFlow({ // Add information about the user to their unsafe metadata unsafeMetadata: { referralSource: 'mobile-app', @@ -148,4 +147,4 @@ The `useSignInWithGoogle()` hook may throw errors in the following scenarios: - **Play Services error** (Android only): Google Play Services is not available or outdated on the device. > [!IMPORTANT] -> Always wrap calls to `startGoogleAuthenticationFlow()` in a `try/catch` block, and handle the `SIGN_IN_CANCELLED` and `-5` error codes separately. \ No newline at end of file +> Always wrap calls to `startGoogleAuthenticationFlow()` in a `try/catch` block, and handle the `SIGN_IN_CANCELLED` and `-5` error codes separately. From ec79f81cc9935381d6c1c07b073b4ade718c9a5b Mon Sep 17 00:00:00 2001 From: ChrisCanin Date: Tue, 25 Nov 2025 16:35:30 -0800 Subject: [PATCH 06/12] Update Sign in with Google guide to reflect correct environment variable names and remove outdated package reference --- .../sign-in-with-google.expo.mdx | 76 +++++++++++-------- .../expo/use-sign-in-with-google.mdx | 1 - 2 files changed, 43 insertions(+), 34 deletions(-) diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx index f9a93c5609..04572baf85 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -55,7 +55,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. For the **Application type**, select **Web application**. 1. Add a name (e.g., "Web client for token verification"). 1. Select **Create**. - 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID`. + 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_WEB_CLIENT_ID`. #### iOS Client ID @@ -63,7 +63,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. For the **Application type**, select **iOS**. 1. Add your iOS **Bundle ID** (from your `app.json` or `app.config.ts`). 1. Select **Create**. - 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID`. + 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID`. #### Android Client ID @@ -80,7 +80,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open > [!NOTE] > Replace `path-to-debug-or-production-keystore` with the path to your debug or ßproduction keystore. By default, the debug keystore is located in `~/.android/debug.keystore`. It may ask for a keystore password, which is `android`. **Please note that Java is required to run the `keytool` command.** 1. Select **Create**. - 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID`. + 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_ANDROID_CLIENT_ID`. ## Add your iOS application to Clerk @@ -90,43 +90,37 @@ To make the setup process easier, it's recommended to keep two browser tabs open Add your Android application to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page in the Clerk Dashboard. You will need your Android app's **package Name**. - ## Install dependencies - - The [@react-native-google-signin/google-signin library](https://react-native-google-signin.github.io/docs/) provides access to Google's native Sign-In functionality from your Expo app. - - Run the following command to install the library: - - ```npm - npm install @react-native-google-signin/google-signin - ``` - ## Configure environment variables Add the Google OAuth client IDs to your `.env` file: ```bash {{ filename: '.env' }} - EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID=your-ios-client-id.apps.googleusercontent.com - EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID=your-android-client-id.apps.googleusercontent.com - EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=your-web-client-id.apps.googleusercontent.com + EXPO_PUBLIC_CLERK_GOOGLE_WEB_CLIENT_ID=your-web-client-id.apps.googleusercontent.com + EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID=your-ios-client-id.apps.googleusercontent.com + EXPO_PUBLIC_CLERK_GOOGLE_ANDROID_CLIENT_ID=your-android-client-id.apps.googleusercontent.com + + # iOS only: URL scheme for Google Sign-In callback + # Format: com.googleusercontent.apps.{IOS_CLIENT_ID_PREFIX} + EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME=com.googleusercontent.apps.your-ios-client-id ``` - ## Add @react-native-google-signin/google-signin to your app config + ## Configure the Clerk Expo plugin (iOS only) + + > [!NOTE] + > The `@clerk/clerk-expo` config plugin is **optional** and only required if you're using native Google Sign-In on iOS. It configures the URL scheme needed for Google's authentication callback. Android does not require this configuration. - Add the `@react-native-google-signin/google-signin` plugin to your `app.json` or `app.config.ts` and configure it with your client IDs. + Add the `@clerk/clerk-expo` plugin to your `app.json` or `app.config.ts`: ```json {{ filename: 'app.json' }} { "expo": { "plugins": [ - [ - "@react-native-google-signin/google-signin", - { - "iosClientId": "your-ios-client-id.apps.googleusercontent.com", - "androidClientId": "your-android-client-id.apps.googleusercontent.com" - } - ] - ] + "@clerk/clerk-expo" + ], + "extra": { + "EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME": "com.googleusercontent.apps.your-ios-client-id" + } } } ``` @@ -135,19 +129,35 @@ To make the setup process easier, it's recommended to keep two browser tabs open export default { expo: { plugins: [ - [ - '@react-native-google-signin/google-signin', - { - iosClientId: process.env.EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID, - androidClientId: process.env.EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID, - }, - ], + '@clerk/clerk-expo', ], + extra: { + EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME: + process.env.EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME, + }, }, } ``` + The plugin reads the `EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME` from either: + 1. Environment variable (for EAS builds, set in `eas.json`) + 2. `config.extra` field in your app config + + For EAS builds, add the environment variable to your build profile in `eas.json`: + + ```json {{ filename: 'eas.json' }} + { + "build": { + "development": { + "env": { + "EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME": "com.googleusercontent.apps.your-ios-client-id" + } + } + } + } + ``` + ## Build your authentication flow diff --git a/docs/reference/expo/use-sign-in-with-google.mdx b/docs/reference/expo/use-sign-in-with-google.mdx index dfbbfe7806..e412d5af52 100644 --- a/docs/reference/expo/use-sign-in-with-google.mdx +++ b/docs/reference/expo/use-sign-in-with-google.mdx @@ -142,7 +142,6 @@ The `useSignInWithGoogle()` hook may throw errors in the following scenarios: - **User cancellation**: The user cancels the sign-in flow, resulting in an error with code `SIGN_IN_CANCELLED` or `-5`. - **Platform error**: The hook is called on an unsupported platform (not iOS or Android). -- **Missing package**: The `@react-native-google-signin/google-signin` package is not installed. - **Authentication failure**: Google authentication fails or the returned ID token is invalid. - **Play Services error** (Android only): Google Play Services is not available or outdated on the device. From bc036c5a74735adf208ae346e514d133aecc710c Mon Sep 17 00:00:00 2001 From: ChrisCanin Date: Wed, 26 Nov 2025 07:59:23 -0800 Subject: [PATCH 07/12] Refactor code blocks in Sign in with Google guide for consistency in plugin array formatting --- .../auth-strategies/sign-in-with-google.expo.mdx | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx index 04572baf85..bdd76776a9 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -115,9 +115,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ```json {{ filename: 'app.json' }} { "expo": { - "plugins": [ - "@clerk/clerk-expo" - ], + "plugins": ["@clerk/clerk-expo"], "extra": { "EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME": "com.googleusercontent.apps.your-ios-client-id" } @@ -128,12 +126,9 @@ To make the setup process easier, it's recommended to keep two browser tabs open ```ts {{ filename: 'app.config.ts' }} export default { expo: { - plugins: [ - '@clerk/clerk-expo', - ], + plugins: ['@clerk/clerk-expo'], extra: { - EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME: - process.env.EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME, + EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME: process.env.EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME, }, }, } @@ -141,8 +136,9 @@ To make the setup process easier, it's recommended to keep two browser tabs open The plugin reads the `EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME` from either: + 1. Environment variable (for EAS builds, set in `eas.json`) - 2. `config.extra` field in your app config + 1. `config.extra` field in your app config For EAS builds, add the environment variable to your build profile in `eas.json`: From c94235d59f8c334b413e523dfaaaf6899027b2e8 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Wed, 26 Nov 2025 12:31:07 -0600 Subject: [PATCH 08/12] docs review pt 2 after changes --- .../sign-in-with-apple.expo.mdx | 4 ++-- .../sign-in-with-google.expo.mdx | 24 +++++++++---------- .../auth-strategies/sign-in-with-google.mdx | 2 +- .../expo/use-sign-in-with-google.mdx | 4 ++-- 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/guides/configure/auth-strategies/sign-in-with-apple.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-apple.expo.mdx index 1f4715f023..e364b89570 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-apple.expo.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-apple.expo.mdx @@ -12,11 +12,11 @@ This guide will teach you how to add native [Sign in with Apple](https://develop ## Add your Native Application - Add your iOS application to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page in the Clerk Dashboard. You will need your iOS app's **App ID Prefix** (Team ID) and **Bundle ID**. + Add your iOS application to the [**Native Applications**](https://dashboard.clerk.com/~/native-applications) page in the Clerk Dashboard. You will need your iOS app's **App ID Prefix** (Team ID) and **Bundle ID**. ## Enable Apple as a social connection - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page. 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Apple**. 1. Ensure that **Enable for sign-up and sign-in** is toggled on. diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx index bdd76776a9..2eb1934be6 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -54,16 +54,16 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. You might need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849#userconsent). Otherwise, you'll be redirected to the **Create OAuth client ID** page. 1. For the **Application type**, select **Web application**. 1. Add a name (e.g., "Web client for token verification"). - 1. Select **Create**. - 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_WEB_CLIENT_ID`. + 1. Select **Create**. A modal will open with your **Client ID**. + 1. Copy and save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_WEB_CLIENT_ID`. #### iOS Client ID 1. In the same project, create another client. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. 1. For the **Application type**, select **iOS**. 1. Add your iOS **Bundle ID** (from your `app.json` or `app.config.ts`). - 1. Select **Create**. - 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID`. + 1. Select **Create**. A modal will open with your **Client ID**. + 1. Copy ans save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID`. #### Android Client ID @@ -78,17 +78,17 @@ To make the setup process easier, it's recommended to keep two browser tabs open ``` > [!NOTE] - > Replace `path-to-debug-or-production-keystore` with the path to your debug or ßproduction keystore. By default, the debug keystore is located in `~/.android/debug.keystore`. It may ask for a keystore password, which is `android`. **Please note that Java is required to run the `keytool` command.** - 1. Select **Create**. - 1. Copy the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_ANDROID_CLIENT_ID`. + > Replace `path-to-debug-or-production-keystore` with the path to your debug or production keystore. By default, the debug keystore is located in `~/.android/debug.keystore`. It may ask for a keystore password, which is `android`. **Please note that Java is required to run the `keytool` command.** + 1. Select **Create**. A modal will open with your **Client ID**. + 1. Copy and save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_ANDROID_CLIENT_ID`. ## Add your iOS application to Clerk - Add your iOS application to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page in the Clerk Dashboard. You will need your iOS app's **App ID Prefix** (Team ID) and **Bundle ID**. + Add your iOS application to the [**Native Applications**](https://dashboard.clerk.com/~/native-applications) page in the Clerk Dashboard. You will need your iOS app's **App ID Prefix** (Team ID) and **Bundle ID**. ## Add your Android application to Clerk - Add your Android application to the [**Native Applications**](https://dashboard.clerk.com/last-active?path=native-applications) page in the Clerk Dashboard. You will need your Android app's **package Name**. + Add your Android application to the [**Native Applications**](https://dashboard.clerk.com/~/native-applications) page in the Clerk Dashboard. You will need your Android app's **package name**. ## Configure environment variables @@ -135,10 +135,10 @@ To make the setup process easier, it's recommended to keep two browser tabs open ``` - The plugin reads the `EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME` from either: + The plugin resolves the `EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME` value from either of the following: - 1. Environment variable (for EAS builds, set in `eas.json`) - 1. `config.extra` field in your app config + 1. An environment variable (recommended for EAS builds, configured in `eas.json`). + 1. The `config.extra` field in your app config. For EAS builds, add the environment variable to your build profile in `eas.json`: diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx index 0518b888a1..43f2ce53d1 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx @@ -1,6 +1,6 @@ --- title: Sign in with Google -description: Learn how to configure Sign in with Google for your Clerk-powered Android app. +description: earn how to use Clerk to natively Sign in with Google in your Android app. sdk: android --- diff --git a/docs/reference/expo/use-sign-in-with-google.mdx b/docs/reference/expo/use-sign-in-with-google.mdx index e412d5af52..cae5193ac0 100644 --- a/docs/reference/expo/use-sign-in-with-google.mdx +++ b/docs/reference/expo/use-sign-in-with-google.mdx @@ -21,7 +21,7 @@ The `useSignInWithGoogle()` hook provides native [Sign in with Google](https://s ## Returns -The `useSignInWithGoogle()` hook returns the `startGoogleAuthenticationFlow()` method, which you can use to initiate the native Google Sign-In flow. +The `useSignInWithGoogle()` hook returns the `startGoogleAuthenticationFlow()` method, which you can use to initiate the native Google authentication flow. ### `startGoogleAuthenticationFlow()` @@ -140,7 +140,7 @@ export default function SignInPage() { The `useSignInWithGoogle()` hook may throw errors in the following scenarios: -- **User cancellation**: The user cancels the sign-in flow, resulting in an error with code `SIGN_IN_CANCELLED` or `-5`. +- **User cancellation**: The user cancels the authentication flow, resulting in an error with code `SIGN_IN_CANCELLED` or `-5`. - **Platform error**: The hook is called on an unsupported platform (not iOS or Android). - **Authentication failure**: Google authentication fails or the returned ID token is invalid. - **Play Services error** (Android only): Google Play Services is not available or outdated on the device. From 0eb9922af10a0354effdb9486494ba571a6a3646 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Wed, 26 Nov 2025 12:34:12 -0600 Subject: [PATCH 09/12] linting --- .../configure/auth-strategies/sign-in-with-google.expo.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx index 2eb1934be6..8d0fae874b 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -54,7 +54,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. You might need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849#userconsent). Otherwise, you'll be redirected to the **Create OAuth client ID** page. 1. For the **Application type**, select **Web application**. 1. Add a name (e.g., "Web client for token verification"). - 1. Select **Create**. A modal will open with your **Client ID**. + 1. Select **Create**. A modal will open with your **Client ID**. 1. Copy and save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_WEB_CLIENT_ID`. #### iOS Client ID @@ -62,7 +62,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the same project, create another client. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. 1. For the **Application type**, select **iOS**. 1. Add your iOS **Bundle ID** (from your `app.json` or `app.config.ts`). - 1. Select **Create**. A modal will open with your **Client ID**. + 1. Select **Create**. A modal will open with your **Client ID**. 1. Copy ans save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID`. #### Android Client ID From 298d8b31979aaad468aa9f7049ddf7959ee9b605 Mon Sep 17 00:00:00 2001 From: Christopher Canin Date: Wed, 26 Nov 2025 10:34:53 -0800 Subject: [PATCH 10/12] L was missing from "Learn" --- docs/guides/configure/auth-strategies/sign-in-with-google.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx index 43f2ce53d1..32408e2492 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx @@ -1,6 +1,6 @@ --- title: Sign in with Google -description: earn how to use Clerk to natively Sign in with Google in your Android app. +description: Learn how to use Clerk to natively Sign in with Google in your Android app. sdk: android --- From e2a0ddb4ab8d0e9f0e12fdeb6d21e48f0d3e89d5 Mon Sep 17 00:00:00 2001 From: ChrisCanin Date: Mon, 1 Dec 2025 17:22:52 -0600 Subject: [PATCH 11/12] Update Google Sign-In setup instructions for OAuth client ID creation --- .../configure/auth-strategies/sign-in-with-google.expo.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx index 8d0fae874b..001c818472 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -54,8 +54,10 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. You might need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849#userconsent). Otherwise, you'll be redirected to the **Create OAuth client ID** page. 1. For the **Application type**, select **Web application**. 1. Add a name (e.g., "Web client for token verification"). - 1. Select **Create**. A modal will open with your **Client ID**. + 1. Under **Authorized redirect URIs**, select **Add URI** and paste the **Authorized Redirect URI** you saved from the Clerk Dashboard. + 1. Select **Create**. A modal will open with your **Client ID** and **Client Secret**. 1. Copy and save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_WEB_CLIENT_ID`. + 1. Copy the **Client ID** and **Client Secret** and paste them into the respective fields in the Clerk Dashboard. Then select **Add connection** to complete the setup. #### iOS Client ID From 0168ba508086aefa40098242444d7f1bef26f8cb Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Fri, 5 Dec 2025 12:16:58 -0600 Subject: [PATCH 12/12] docs review pt2 --- .../enable-google-social-connection.mdx | 5 ++ .../sign-in-with-google.expo.mdx | 48 ++++++++++--------- .../auth-strategies/sign-in-with-google.mdx | 17 ++++--- .../social-connections/apple.mdx | 2 +- .../social-connections/google.mdx | 6 +-- 5 files changed, 40 insertions(+), 38 deletions(-) create mode 100644 docs/_partials/authentication/social-connections/enable-google-social-connection.mdx diff --git a/docs/_partials/authentication/social-connections/enable-google-social-connection.mdx b/docs/_partials/authentication/social-connections/enable-google-social-connection.mdx new file mode 100644 index 0000000000..0e19c29f82 --- /dev/null +++ b/docs/_partials/authentication/social-connections/enable-google-social-connection.mdx @@ -0,0 +1,5 @@ +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page. +1. Select **Add connection** and select **For all users**. +1. In the **Choose provider** dropdown, select **Google**. +1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. +1. Save the **Authorized Redirect URI** somewhere secure. Keep this modal and page open. \ No newline at end of file diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx index 001c818472..0bcb39ca1a 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.expo.mdx @@ -15,24 +15,23 @@ sdk: expo title: "A Google Developer account is required.", link: "https://console.developers.google.com/", icon: "user-circle", - } + }, + { + title: "Follow the Expo quickstart", + link: "/docs/expo/getting-started/quickstart", + icon: "expo", + }, ]} /> -[Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) helps you easily and securely sign in to third-party apps or services with your Google Account, without having to enter a username and password repeatedly across different services. - -This guide will teach you how to add native Sign in with Google to your Clerk Expo application. This is different from Google OAuth - if you want to use Google OAuth, see the [dedicated guide](/docs/guides/configure/auth-strategies/social-connections/google). +This guide will teach you how to add native [Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) to your Clerk Expo application. This is different from Google OAuth - if you want to use Google OAuth, see the [dedicated guide](/docs/guides/configure/auth-strategies/social-connections/google). To make the setup process easier, it's recommended to keep two browser tabs open - one for the [Clerk Dashboard](https://dashboard.clerk.com/~/user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). ## Enable Google as a social connection - 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page. - 1. Select **Add connection** and select **For all users**. - 1. In the **Choose provider** dropdown, select **Google**. - 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. Save the **Authorized Redirect URI** somewhere secure. Keep this modal and page open. + ## Configure Google Cloud Console @@ -42,28 +41,18 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Navigate to the [Google Cloud Console](https://console.cloud.google.com/). 1. Select an existing project or [create a new one](https://console.cloud.google.com/projectcreate). You'll be redirected to your project's **Dashboard** page. - 1. Enable the **Google+ API** for your project. + 1. Enable the [**Google+ API**](https://console.cloud.google.com/apis/library/plus.googleapis.com?project=expo-testing-480017) for your project. ### Create OAuth 2.0 Credentials - You'll need to create three sets of credentials: + You'll need to create **three sets of credentials**: - #### Web Client ID (for token verification) + #### iOS Client ID 1. Navigate to **APIs & Services**. Then, select **Credentials**. 1. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. You might need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849#userconsent). Otherwise, you'll be redirected to the **Create OAuth client ID** page. - 1. For the **Application type**, select **Web application**. - 1. Add a name (e.g., "Web client for token verification"). - 1. Under **Authorized redirect URIs**, select **Add URI** and paste the **Authorized Redirect URI** you saved from the Clerk Dashboard. - 1. Select **Create**. A modal will open with your **Client ID** and **Client Secret**. - 1. Copy and save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_WEB_CLIENT_ID`. - 1. Copy the **Client ID** and **Client Secret** and paste them into the respective fields in the Clerk Dashboard. Then select **Add connection** to complete the setup. - - #### iOS Client ID - - 1. In the same project, create another client. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. 1. For the **Application type**, select **iOS**. - 1. Add your iOS **Bundle ID** (from your `app.json` or `app.config.ts`). + 1. Add your iOS **Bundle ID**. 1. Select **Create**. A modal will open with your **Client ID**. 1. Copy ans save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_IOS_CLIENT_ID`. @@ -84,6 +73,18 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Create**. A modal will open with your **Client ID**. 1. Copy and save the **Client ID** - you'll need this for `EXPO_PUBLIC_CLERK_GOOGLE_ANDROID_CLIENT_ID`. + #### Web Client ID (for token verification) + + 1. In the same project, create another client. Next to **Credentials**, select **Create Credentials**. Then, select **OAuth client ID**. + 1. For the **Application type**, select **Web application**. + 1. Add a name (e.g., "Web client for token verification"). + 1. Under **Authorized redirect URIs**, select **Add URI** and paste the **Authorized Redirect URI** you saved from the Clerk Dashboard. + 1. Select **Create**. A modal will open with your **Client ID** and **Client Secret**. Save these values somewhere secure. You'll need these for the following steps. + + ## Set the Client ID and Client Secret in the Clerk Dashboard (from your web client) + + + ## Add your iOS application to Clerk Add your iOS application to the [**Native Applications**](https://dashboard.clerk.com/~/native-applications) page in the Clerk Dashboard. You will need your iOS app's **App ID Prefix** (Team ID) and **Bundle ID**. @@ -103,6 +104,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open # iOS only: URL scheme for Google Sign-In callback # Format: com.googleusercontent.apps.{IOS_CLIENT_ID_PREFIX} + # IOS_CLIENT_ID_PREFIX is the part of your iOS Client ID before ".apps.googleusercontent.com" EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME=com.googleusercontent.apps.your-ios-client-id ``` diff --git a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx index 32408e2492..753a68085a 100644 --- a/docs/guides/configure/auth-strategies/sign-in-with-google.mdx +++ b/docs/guides/configure/auth-strategies/sign-in-with-google.mdx @@ -15,24 +15,23 @@ sdk: android title: "A Google Developer account is required.", link: "https://console.developers.google.com/", icon: "user-circle", - } + }, + { + title: "Follow the Android quickstart", + link: "/docs/android/getting-started/quickstart", + icon: "android", + }, ]} /> -[Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) helps you easily and securely sign in to third-party apps or services with your Google Account, without having to enter a username and password repeatedly across different services. - -This guide will teach you how to add native Sign in with Google to your Clerk apps on Android platforms. This is different from Google OAuth - if you want to use Google OAuth, see the [dedicated guide](/docs/guides/configure/auth-strategies/social-connections/google). +This guide will teach you how to add native [Sign in with Google](https://support.google.com/accounts/answer/12849458?hl=en) to your Clerk apps on Android platforms. This is different from Google OAuth - if you want to use Google OAuth, see the [dedicated guide](/docs/guides/configure/auth-strategies/social-connections/google). To make the setup process easier, it's recommended to keep two browser tabs open - one for the [Clerk Dashboard](https://dashboard.clerk.com/~/user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). ## Enable Google as a social connection - 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page. - 1. Select **Add connection** and select **For all users**. - 1. In the **Choose provider** dropdown, select **Google**. - 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. Save the **Authorized Redirect URI** somewhere secure. Keep this modal and page open. + ## Create the Google Developer Android client diff --git a/docs/guides/configure/auth-strategies/social-connections/apple.mdx b/docs/guides/configure/auth-strategies/social-connections/apple.mdx index 401513a3bc..fe163a47bd 100644 --- a/docs/guides/configure/auth-strategies/social-connections/apple.mdx +++ b/docs/guides/configure/auth-strategies/social-connections/apple.mdx @@ -21,7 +21,7 @@ description: Learn how to allow users to sign up and sign in to your Clerk app w Enabling OAuth via [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) allows your users to sign in and sign up to your Clerk app with their Apple ID. > [!IMPORTANT] -> This guide explains how to configure Sign in with Apple for web based flows. To configure native Sign in with Apple on native applications (iOS), see the [dedicated guide](/docs/guides/configure/auth-strategies/sign-in-with-apple). +> This guide explains how to configure Sign in with Apple for web based flows. To configure native Sign in with Apple on native applications, see the [dedicated guide](/docs/guides/configure/auth-strategies/sign-in-with-apple). ## Configure for your development instance diff --git a/docs/guides/configure/auth-strategies/social-connections/google.mdx b/docs/guides/configure/auth-strategies/social-connections/google.mdx index d98ccc6635..88e6ce8b9a 100644 --- a/docs/guides/configure/auth-strategies/social-connections/google.mdx +++ b/docs/guides/configure/auth-strategies/social-connections/google.mdx @@ -41,11 +41,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Enable Google as a social connection - 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page. - 1. Select **Add connection** and select **For all users**. - 1. In the **Choose provider** dropdown, select **Google**. - 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. Save the **Authorized Redirect URI** somewhere secure. Keep this modal and page open. + ### Create a Google Developer project