使用文员

托管身份验证会在你的应用上通过浏览器身份验证会话打开 Clerk 的 账户门户。用户可以完成你 Clerk 应用启用的任何登录或注册方式，SDK 会在你的应用中激活生成的会话。从 useHostedAuth() 钩子调用 startHostedAuth():

🌐 Hosted authentication opens Clerk's Account Portal in a browser authentication session over your app. Users can complete any sign-in or sign-up method enabled for your Clerk application, and the SDK activates the resulting session in your app. Call startHostedAuth() from the useHostedAuth() hook:

import { useAuth } from '@clerk/expo';
import { useHostedAuth } from '@clerk/expo/hosted-auth';
import { ActivityIndicator, Button, Text, View } from 'react-native';

export default function MainScreen() {
  const { isLoaded, isSignedIn } = useAuth();
  const { startHostedAuth } = useHostedAuth();

  const handleSignUp = async () => {
    try {
      await startHostedAuth({ mode: 'sign-up' });
    } catch (error) {
      // Handle the error in your app
    }
  };

  if (!isLoaded) {
    return <ActivityIndicator size="large" />;
  }

  return (
    <View>
      {isSignedIn ? (
        <Text>You're signed in</Text>
      ) : (
        <Button title="注册" onPress={handleSignUp} />
      )}
    </View>
  );
}

身份验证完成后，SDK 会关闭浏览器会话，激活新的会话，并用已登录的状态更新 useAuth()。浏览器不会保留单独的活动会话。

🌐 After authentication completes, the SDK closes the browser session, activates the new session, and updates useAuth() with the signed-in state. The browser doesn't retain a separate active session.

startHostedAuth() 默认会打开登录页面并接受 mode: 'sign-in' | 'sign-up'。当用户在未完成操作时关闭浏览器，它会以 null createdSessionId 方式结束；如果认证失败，则会抛出错误。

这种方法在 Expo Go 中有效，因为 Expo 提供了一个开发回调。在开发或生产构建中，回调是根据你的 iOS bundle identifier 或 Android 包名生成的，所以在更改任一标识符后，保持 @clerk/expo 配置插件在你的应用配置中，并重新构建原生项目。

🌐 This approach works in Expo Go, where Expo supplies a development callback. In a development or production build, the callback is derived from your iOS bundle identifier or Android package name, so keep the @clerk/expo config plugin in your app config and rebuild the native project after changing either identifier.

账户门户在浏览器中运行，所以社交登录使用每个提供商的网页OAuth流程，而不是本地流程。有关生产凭证要求和故障排除，请参阅托管认证指南。

🌐 Account Portal runs in a browser, so social sign-in uses each provider's web OAuth flow rather than the native one. See the hosted authentication guide for production credential requirements and troubleshooting.

<AuthView /> 提供了一个完整的原生登录和注册界面，可以处理邮箱、电话、通行密钥、多因素认证以及 Clerk 控制面板中启用的任何社交登录。它会在你的 React Native 视图层级中内嵌渲染，所以你可以把它放在模态框、路由或全屏视图中。下面的例子展示了如何在模态框中打开它：

import { useAuth } from '@clerk/expo';
import { AuthView, UserButton } from '@clerk/expo/native';
import { useState } from 'react';
import { ActivityIndicator, Button, Modal, View } from 'react-native';

export default function MainScreen() {
  const { isLoaded, isSignedIn } = useAuth({ treatPendingAsSignedOut: false });
  const [isAuthOpen, setIsAuthOpen] = useState(false);

  if (!isLoaded) {
    return <ActivityIndicator size="large" />;
  }

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      {isSignedIn ? <UserButton /> : <Button title="注册" onPress={() => setIsAuthOpen(true)} />}
      <Modal
        animationType="slide"
        visible={isAuthOpen}
        presentationStyle="pageSheet"
        onRequestClose={() => setIsAuthOpen(false)}>
        <AuthView onDismiss={() => setIsAuthOpen(false)} />
      </Modal>
    </View>
  );
}

用户登录后，本地会话会同步回 JavaScript SDK，因此 useAuth() 和 useUser() 会反映已登录状态。将 treatPendingAsSignedOut: false 传给 useAuth()，这样待处理的 会话任务 不会被当作已登出。

🌐 After the user signs in, the native session is synchronized back to the JavaScript SDK, so useAuth() and useUser() reflect the signed-in state. Pass treatPendingAsSignedOut: false to useAuth() so pending session tasks are not treated as signed out.

警告 保持包含 <AuthView /> 的 <Modal> 挂载在与你已登录和未登录内容相同的层级。如果你只在未登录内容中渲染它，认证状态在会话任务仍在进行时可能会发生变化，你的条件渲染会过早卸载模态框。

<AuthView /> 接受 mode="signIn" | "signUp" | "signInOrUp"（默认值）、一个控制原生关闭按钮的 isDismissible 布尔值，以及一个 onDismiss 回调。当用户必须先进行身份验证才能继续时，使用 isDismissible={false} 将其呈现为全屏视图，而不是模态窗口。

<UserButton /> 不需要任何属性。它会显示已登录用户的头像或名称首字母，点击后会打开原生的 <UserProfileView />，用户可以在其中管理个人信息、安全设置并退出登录。

<AuthView /> 会自动显示在 Clerk 仪表板中启用的任何社交登录按钮，并在内部处理登录流程，所以你不需要 expo-crypto 或原生登录钩子。原生 OAuth 仍然需要在 Clerk 仪表板和提供商控制台中设置凭据。否则，按钮会显示，但点击时会失败。请按照本页底部链接的 Clerk Google 登录和 Apple 登录指南操作。

这种方法需要开发构建，因为这些组件由原生模块支持：

🌐 This approach requires a development build because the components are backed by native modules:

使用 Core 3 钩子构建你自己的界面。这在 Expo Go 中可用。下面的示例使用 useSignUp() 构建一个带有邮箱验证码验证的邮箱和密码注册表单：

🌐 Build your own screens with the Core 3 hooks. This works in Expo Go. The following example uses useSignUp() to build an email and password sign-up form with email code verification:

import { useAuth, useSignUp } from '@clerk/expo';
import { useState } from 'react';
import { Button, Text, TextInput, View } from 'react-native';

export default function MainScreen() {
  const { isLoaded, isSignedIn } = useAuth();
  const { signUp } = useSignUp();

  const [emailAddress, setEmailAddress] = useState('');
  const [password, setPassword] = useState('');
  const [code, setCode] = useState('');
  const [isVerifying, setIsVerifying] = useState(false);

  const handleSignUp = async () => {
    const { error } = await signUp.password({ emailAddress, password });
    if (error) {
      console.error(JSON.stringify(error, null, 2));
      return;
    }

    const { error: sendError } = await signUp.verifications.sendEmailCode();
    if (sendError) {
      console.error(JSON.stringify(sendError, null, 2));
      return;
    }

    setIsVerifying(true);
  };

  const handleVerify = async () => {
    const { error } = await signUp.verifications.verifyEmailCode({ code });
    if (error) {
      console.error(JSON.stringify(error, null, 2));
      return;
    }

    await signUp.finalize();
  };

  if (!isLoaded) {
    return null;
  }

  if (isSignedIn) {
    return <Text>You're signed in</Text>;
  }

  if (isVerifying) {
    return (
      <View>
        <TextInput
          value={code}
          placeholder="Enter your verification code"
          onChangeText={setCode}
          keyboardType="numeric"
        />
        <Button title="验证" onPress={handleVerify} />
      </View>
    );
  }

  return (
    <View>
      <TextInput
        autoCapitalize="none"
        value={emailAddress}
        placeholder="Enter email"
        onChangeText={setEmailAddress}
        keyboardType="email-address"
      />
      <TextInput
        value={password}
        placeholder="Enter password"
        secureTextEntry
        onChangeText={setPassword}
      />
      <Button title="注册" onPress={handleSignUp} />
      {/* Required for sign-up flows on Expo web. Clerk skips the browser CAPTCHA on Android and iOS */}
      <View nativeID="clerk-captcha" />
    </View>
  );
}

在 Core 3 中，像 signUp.password() 和 signUp.verifications.verifyEmailCode() 这样的方法在遇到验证错误时会返回 { error }，而不是抛出异常。当验证完成注册后，signUp.finalize() 会将其转换为活跃会话，并更新 useAuth() 为已登录状态。

🌐 In Core 3, methods such as signUp.password() and signUp.verifications.verifyEmailCode() return { error } instead of throwing for validation errors. When verification completes the sign-up, signUp.finalize() converts it into an active session and updates useAuth() with the signed-in state.

对应的登录流程使用 useSignIn()，其中 finalize() 接受一个 navigate 回调，这样你就可以在重定向之前处理 会话任务：

🌐 The corresponding sign-in flow uses useSignIn(), where finalize() accepts a navigate callback so you can handle session tasks before redirecting:

import { useSignIn } from '@clerk/expo';
import { type Href, useRouter } from 'expo-router';

export default function SignInScreen() {
  const { signIn } = useSignIn();
  const router = useRouter();

  const handleSignIn = async (emailAddress: string, password: string) => {
    const { error } = await signIn.password({ emailAddress, password });
    if (error) {
      return;
    }

    if (signIn.status === 'complete') {
      await signIn.finalize({
        navigate: ({ session, decorateUrl }) => {
          if (session?.currentTask) return; // let the session task layer handle it
          router.replace(decorateUrl('/') as Href);
        },
      });
    }
  };

  // ... render your email and password fields
}

要在你的自定义界面中添加原生的“使用 Google 登录”和“使用 Apple 登录”按钮，可以使用来自 @clerk/expo/google 的 useSignInWithGoogle() 钩子以及来自 @clerk/expo/apple 的 useSignInWithApple() 钩子。两者都返回一个启动方法（startGoogleAuthenticationFlow() 和 startAppleAuthenticationFlow()），调用后会返回 { createdSessionId, setActive }。

🌐 To add native Sign in with Google and Sign in with Apple buttons to your custom screens, use the useSignInWithGoogle() hook from @clerk/expo/google and the useSignInWithApple() hook from @clerk/expo/apple. Both return a start method (startGoogleAuthenticationFlow() and startAppleAuthenticationFlow()) that resolves with { createdSessionId, setActive }.

这两个 hooks 都使用了原生模块，所以它们需要开发版本和安装步骤中的相关包。useSignInWithGoogle() 还需要 @clerk/expo-google-signin 配置插件。在 iOS 上，根据 App Store 指南 4.8，任何提供第三方社交登录的应用也必须提供 Apple 登录。按照本页底部链接的 Clerk 指南，在 Clerk 控制面板和对应提供商的控制台中注册你的凭证。

🌐 Both hooks use native modules, so they require a development build and the packages from the install step. useSignInWithGoogle() also needs the @clerk/expo-google-signin config plugin. On iOS, App Store Guideline 4.8 requires that any app offering third-party social sign-in must also offer Sign in with Apple. Follow the Clerk guides linked at the bottom of this page to register your credentials in the Clerk Dashboard and the provider consoles.

对于托管认证和自定义流程的方法，运行以下命令并在 Expo Go 中打开项目：

🌐 For the hosted authentication and custom flow approaches, run the following command and open the project in Expo Go: