托管电子邮件/密码用户 — React Native SDK

在此页面上

先决条件

在客户端中配置用户身份验证
设置 @realm/react 提供者
使用回退组件登录
注册新用户帐户
确认用户的电子邮件地址
重试用户确认方法
重新发送确认电子邮件
重试用户确认函数
重置用户密码
使用电子邮件重置密码
调用密码重置函数
useEmailPasswordAuth 钩子参考

Realm 现已更名为 Atlas Device SDK – 了解详情

您可以在应用的 React Native 客户端代码中注册新用户帐户、确认用户电子邮件地址或重置用户密码。

@realm/react钩子useEmailPasswordAuth具有专门用于管理电子邮件/密码用户的方法和枚举。有关快速参考，请参阅useEmailPasswordAuth 钩子。

先决条件

在对用户进行身份验证之前，您必须：

创建 App Services App
在应用程序中启用电子邮件/密码身份验证。有关详细信息，请参阅 App Services 文档中的电子邮件/密码身份验证。
安装 React Native SDK

在客户端中配置用户身份验证

@realm/react 具有用于用户身份验证的提供者和挂钩。要配置用户身份验证，请执行以下操作：

设置 @realm/react 提供者。
使用UserProvider回退组件让用户登录。

设置 @realm/react 提供者

AppProvider包装的组件可以访问useApp和useAuth钩子。仅当AppProvider成功连接到 App Services 后端时，这些组件才会呈现。

UserProvider包装的组件可以使用useUser钩子访问经过身份验证的用户。仅当您的应用具有经过身份验证的用户时，才会呈现这些组件

要配置用户身份验证，请执行以下操作：

将需要访问 App Services 的所有组件封装在 AppProvider 中。
在 AppProvider 内部，用 UserProvider 来封装您希望经过身份验证的用户有权访问的所有组件。
在 UserProvider 中，包含一个 fallback 属性（附带用于用户登录的组件）。如果没有经过身份验证的用户，该应用则会显示此组件。

import React from 'react';
import {AppProvider, UserProvider} from '@realm/react';
// Fallback log in component that's defined in another file.
import {LogIn} from './Login';
export const LoginExample = () => {
  return (
    <ScrollView>
      <AppProvider id={APP_ID}>
        {/* If there is no authenticated user, mount the
         `fallback` component. When user successfully
          authenticates, the app unmounts the `fallback`
          component (in this case, the `LogIn` component). */}
        <UserProvider fallback={LogIn}>
          {/* Components inside UserProvider have access
            to the user. These components only mount if
            there's an authenticated user. */}
          <UserInformation />
        </UserProvider>
      </AppProvider>
    </ScrollView>
  );
};

使用回退组件登录

用户必须拥有注册的电子邮件/密码帐户才能登录。用户登录后，包装在UserProvider中的所有组件都可以通过useUser钩子访问该用户对象的实例。

若要使用电子邮件地址和密码使某一用户登录：

注册用户（如果尚未注册）。
从 useEmailPasswordAuth 挂钩解构 logIn 和 result。
将用户的电子邮件地址和密码作为对象传递给 LogIn()。
处理 result。

export const LoginWithEmail = () => {
  const {logIn, result} = useEmailPasswordAuth();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const performLogin = () => {
    logIn({email, password});
  };
  // Handle `result`...
};

注册新用户帐户

在注册新的电子邮件/密码用户之前，您需要获取他们的电子邮件地址和密码。该电子邮件地址不得与其他电子邮件/密码用户关联，并且密码必须介于 6 到 128 个字符之间。

注册后，您必须确认新用户的电子邮件地址，他们才能登录您的应用程序。

要注册新用户帐户：

从 useEmailPasswordAuth 挂钩解构 register 和 result。
将用户的电子邮件地址和密码作为对象传递给 register()。
确认用户的电子邮件地址。

type RegisterButtonProps = {
  email: string;
  password: string;
};
const RegisterButton = ({email, password}: RegisterButtonProps) => {
  const {register, result, logIn} = useEmailPasswordAuth();
  // Log in the user after successful registration
  useEffect(() => {
    if (result.success && result.operation === AuthOperationName.Register) {
      logIn({email, password});
    }
  }, [result, logIn, email, password]);
  // For this example, the App Services backend automatically
  // confirms users' emails.
  const performRegistration = () => {
    register({email, password});
  };
  return (
    <Button
      title="Register"
      onPress={performRegistration}
    />
  );
};

确认用户的电子邮件地址

新用户必须确认他们拥有自己的电子邮件地址，然后才能登录您的应用程序，除非将身份验证提供程序配置为自动确认新用户。确认过程在您注册用户时开始，在您通过客户端代码确认用户时结束。

电子邮件确认需要有效的token和tokenId 。您可以从不同位置获取这些值，具体取决于身份验证提供者的配置：

发送确认电子邮件。 token和tokenId值作为查询参数包含在 Email Confirmation URL中。
运行确认函数。 token和tokenId值作为参数传递给函数。

要确认注册用户，请执行以下操作：

在 App Services 中，确保将User Confirmation Method设置为Send a confirmation email 。
在客户端代码中，从useEmailPasswordAuth钩子解构confirm和result 。
将token和tokenId作为对象传递给confirm() 。
根据result处理确认。

interface ConfirmUserProps {
  token: string;
  tokenId: string;
}
const ConfirmUser = ({token, tokenId}: ConfirmUserProps) => {
  const {confirm, result} = useEmailPasswordAuth();
  const performConfirmation = () => {
    confirm({token, tokenId});
  };
  // Handle `result`...
}

重试用户确认方法

SDK 提供了各种方法，允许重新发送用户确认邮件或重试自定义确认方法。

重新发送确认电子邮件

如果提供商配置为发送确认电子邮件，则 Atlas App Services 会在用户注册时自动发送确认电子邮件。该电子邮件包含已配置Email Confirmation URL的链接，该链接带有有效期为30分钟的令牌。如果用户没有在该期限内点击链接并确认，则必须请求新的确认电子邮件。

要重新发送确认电子邮件：

从 useEmailPasswordAuth 挂钩解构 resendConfirmationEmail 和 result。
将用户的电子邮件作为对象传递给resendConfirmationEmail() 。
根据result处理确认。

const ResendUserConfirmationEmail = () => {
  const {resendConfirmationEmail, result} = useEmailPasswordAuth();
  const [email, setEmail] = useState('');
  const performResendConfirmationEmail = () => {
    resendConfirmationEmail({email});
  };
  // Handle `result`...
}

重试用户确认函数

如果需要，您可以重新运行自定义确认函数。

要重试用户确认函数：

从 useEmailPasswordAuth 挂钩解构 retryCustomConfirmation 和 result。
将用户的电子邮件作为对象传递给retryCustomConfirmation() 。
根据result处理确认。

const RetryCustomUserConfirmation = () => {
  const {retryCustomConfirmation, result} = useEmailPasswordAuth();
  const [email, setEmail] = useState('');
  const performRetryCustomConfirmation = () => {
    retryCustomConfirmation({email});
  };
  // Handle `result`...
}

重置用户密码

重置用户密码是一个多步骤的过程。

在客户端应用程序中，为用户提供一个用于重置密码的用户界面。然后，您的 App Services App 可以发送电子邮件或运行自定义函数来确认用户的身份。
确认用户身份后，完成密码重置请求。
密码重置完成后，用户可以使用新密码登录。

有关如何设置首选密码重置方法的详细信息，请参阅App Services 电子邮件/密码身份验证文档。

使用电子邮件重置密码

您可以发送密码重置电子邮件以确认用户身份。您必须将 App Services App 配置为发送密码重置电子邮件。移动应用程序可以直接在应用程序中处理密码重置。在 Android 中配置深度链接，在 iOS 中配置通用链接。

密码重置电子邮件中的token和tokenId值的有效期为 30 分钟。如果用户在这段时间内没有访问电子邮件的Password Reset URL ，这些值就会过期，用户必须请求另一封密码重置电子邮件。

要使用电子邮件重置密码：

在 App Services 中，确保将Password Reset Method设置为Send a password reset email 。
在客户端代码中，从useEmailPasswordAuth钩子解构sendResetPasswordEmail 、 resetPassword和result 。
将用户的电子邮件作为对象传递给sendResetPasswordEmail() 。
从重置电子邮件密码 URL 中提取token和tokenId值。
将新用户密码token tokenId和resetPassword() 作为对象传递给。

const SendResetPasswordEmailButton = ({email}: {email: string}) => {
  const [errorMessage, setErrorMessage] = useState('');
  const {sendResetPasswordEmail, result} = useEmailPasswordAuth();
  const performSendResetPasswordEmail = () => {
    sendResetPasswordEmail({email: email});
  };
  // Handle `result`...
};

interface ResetPasswordButtonProps {
  password: string;
  token: string;
  tokenId: string;
}
const ResetPasswordButton = ({
  password,
  token,
  tokenId,
}: ResetPasswordButtonProps) => {
  const [errorMessage, setErrorMessage] = useState('');
  const {resetPassword, result} = useEmailPasswordAuth();
  const performPasswordReset = () => {
    resetPassword({token, tokenId, password});
  };
  // Handle `result`...
};

调用密码重置函数

您可以调用自己定义的 App Services Function 来处理密码重置。您必须配置 App Services App 才能运行密码重置功能。

此函数可以接受用户名、密码和任意数量的其他参数。您可以使用这些参数指定用户应传递以成功完成密码重置的详细信息，例如安全问题回答或其他挑战。

在 App Services 端，您可以定义在调用此方法时运行的自定义密码重置函数。该函数应返回三种可能状态之一：

fail
pending
success

fail状态被视为错误。 SDK 方法callResetPasswordFunction()不接受返回值，因此不会向客户端返回pending或success状态。

要调用密码重置函数，请执行以下操作：

在 App Services 中，创建密码重置函数。
在 App Services 中，确保将Password Reset Method设置为Run a password reset function并将其指向您的新函数。
在客户端代码中，从useEmailPasswordAuth钩子解构callResetPasswordFunction和result 。
将用户的电子邮件和密码作为对象传递给callResetPasswordFunction() ，然后是您为自定义函数定义的任何其他参数。

const ResetPasswordWithFunction = () => {
  const {callResetPasswordFunction, result} = useEmailPasswordAuth();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const performResetPassword = () => {
    callResetPasswordFunction({email, password}, "extraArg1", "extraArg2");
  };
}

服务器端待处理案例

如果您希望用户采取其他步骤来确认其身份，您的App Services 密码重置函数可能会返回pending 。但是，该返回值不会传递给 SDK 的callResetPasswordFunction() ，因此您的客户端应用程序必须实现自己的逻辑来处理pending状态。

您的服务器端函数可能会使用自定义电子邮件提供商发送电子邮件。或者，您也可以使用短信，通过短信确认用户的身份。

您可以在 App Services 密码重置函数上下文中访问token和tokenId 。如果您通过 App Services 密码重置函数传递此信息，则可以使用特定于平台的深度链接或通用链接将这些值传递回您的应用程序。然后，客户端应用程序可以使用useEmailPasswordAuth 钩子来完成密码重置流程。

interface ResetPasswordButtonProps {
  password: string;
  token: string;
  tokenId: string;
}
const ResetPasswordButton = ({
  password,
  token,
  tokenId,
}: ResetPasswordButtonProps) => {
  const [errorMessage, setErrorMessage] = useState('');
  const {resetPassword, result} = useEmailPasswordAuth();
  const performPasswordReset = () => {
    resetPassword({token, tokenId, password});
  };
  // Handle `result`...
};

服务器端成功案例

如果您的App Services 密码重置函数在函数内进行了额外验证，或者如果您在尝试重置密码之前已验证用户身份，则可以将 App Services 函数配置为返回success 。但是，该返回值不会传递给 SDK 的callResetPasswordFunction() ，因此您的客户端应用程序必须实现自己的逻辑来处理success状态。

useEmailPasswordAuth 钩子参考

useEmailPasswordAuth钩子提供了简化电子邮件/密码用户管理的方法。它还具有与身份验证相关的状态。有关详细信息，请参阅useEmailPasswordAuth参考文档。

您还可以查看useEmailPasswordAuth的@realm/react API 文档。

← 自定义用户数据 - React Native SDK

多用户应用程序 - React Native SDK →