电子邮箱/密码用户 — Flutter SDK
借助 Atlas App Services 的电子邮件/密码身份验证提供程序，您可以注册新帐户、确认电子邮件地址以及从客户端代码重置用户密码。
警告
版本 0.5.0 破坏性变更 (breaking change)
Realm Flutter SDK 版本 0.5.0 包括对电子邮件/密码身份验证的破坏性变更 (breaking change)。此更改修复了一个错误，即在 SDK 的早期版本中，unicode 空字符 \u0000被附加到密码末尾。
因此，一旦将应用程序升级到使用 >0.5.0 的版本，用户必须重置密码或创建新帐户。 更新到 >0.5.0 后，以前的密码将不再有效。
开始之前
在开始编写客户端代码之前，您应该了解Atlas App Services提供的不同电子邮件/密码身份验证流程，并为您的应用程序配置后端实施。 Atlas App Services有多种方法可以确认电子邮件/密码用户身份和重置用户密码。 详细了解、启用和配置Atlas App Services电子邮件/密码身份验证。
注册用户
创建新的 EmailPasswordAuthProvider 实例，并以
App实例作为参数。调用 EmailPasswordAuthProvider.registerUser() ，将用户的电子邮件和密码作为参数传递。
EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app); await authProvider.registerUser("lisa@example.com", "myStr0ngPassw0rd");
注意
注册用户并不意味着该用户也会登录。 您必须单独登录用户。
登录用户
通过调用 Credentials.emailPassword() 创建电子邮件/密码档案以及用户的电子邮件和密码。
将生成的档案传递给
app.logIn。
final emailPwCredentials = Credentials.emailPassword("lisa@example.com", "myStr0ngPassw0rd"); await app.logIn(emailPwCredentials);
确认新用户的电子邮件地址
注册新的电子邮件/密码用户后，您必须确认电子邮件地址，除非您将Atlas App Services配置为自动确认用户。
自定义确认函数
如果您将Atlas App Services配置为使用自定义函数进行电子邮件地址确认，请使用自定义函数流程的逻辑处理用户确认。 用户注册时， Atlas App Services后端会调用自定义函数。
发送确认电子邮件
如果您将Atlas App Services配置为使用电子邮件处理用户确认，则只需发送确认电子邮件。
要确认新创建的用户，请将确认token 和tokenId 传递给 EmailPasswordAuthProvider.confirmUser() 。这些内容包含在用户注册时发送到其电子邮件地址的电子邮件中。
EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app); await authProvider.confirmUser(token, tokenId);
重试用户确认
SDK 提供了重新发送用户确认电子邮件或重试自定义确认的方法。
重试用户确认函数
如果您已将Atlas App Services后端配置为重试自定义用户确认功能，请使用此用户确认方法。
要重试确认函数，请将注册时使用的电子邮件传递给 EmailPasswordAuthProvider.retryCustomConfirmationFunction()。
EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app); await authProvider.retryCustomConfirmationFunction("lisa@example.com");
重新发送用户确认电子邮件
如果您已将Atlas App Services后端配置为重新发送确认电子邮件，请使用此用户确认方法。 每个 URL 中的确认令牌会在30分钟后过期。 如果用户没有在该期限内点击链接并确认，则必须请求新的确认电子邮件。
要重新发送确认电子邮件，请将注册时使用的电子邮件传递给 EmailPasswordAuthProvider.resendUserConfirmation()。
EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app); await authProvider.resendUserConfirmation("lisa@example.com");
重置用户密码
重置用户密码是一个多步骤的过程。
在客户端应用程序中，您为用户提供一个用于重置密码的用户界面。 然后，您的 App Services App 可以发送电子邮件或运行自定义函数来确认用户的身份。
确认用户身份后，即可完成密码重置请求。
密码重置完成后，用户可以使用新密码登录。
要选择在您的应用中使用哪种方法，请配置Atlas App Services身份验证密码重置行为。
调用重置函数
当您将应用程序配置为 运行密码重置函数 时，您可以定义在调用 EmailPasswordAuthProvider.callResetPasswordFunction() 时应运行的函数 。此函数可以接受用户名、密码和任意数量的其他参数。 您可以使用这些参数指定用户应传递以成功完成密码重置的详细信息，例如安全问题答案或其他挑战。
如果要定义自己的密码重置流程，您可能更愿意使用自定义密码重置函数。 例如，您可以从特定域发送自定义密码重置电子邮件。 或者，您可以使用电子邮件以外的服务来确认用户的身份。
在 App Services 端，您可以定义在调用此方法时运行的自定义密码重置函数。 该函数可以返回三种可能的状态之一：
failpendingsuccess
SDK 将fail状态视为错误。 SDK callResetPasswordFunction()不接受返回值，因此它不会向客户端返回pending或success状态。
服务器端待处理案例
如果您希望用户采取一些额外步骤来确认其身份，您的Atlas App Services密码重置函数可能会返回 pending。 但是，该返回值不会传递给 SDK 的callResetPasswordFunction() ，因此您的客户端应用程序必须实现自己的逻辑来处理pending状态。
您的服务器端函数可能会使用自定义电子邮件提供商发送电子邮件。 或者，您也可以使用短信，通过短信确认用户的身份。
您可以在Atlas App Services密码重置函数上下文中使用 token 和 tokenId。 如果您通过Atlas App Services密码重置功能传递此信息，则可以使用特定于平台的深度链接或通用链接将这些值传递回您的应用程序。 然后，客户端应用程序可以调用 EmailPasswordAuthProvider.completeResetPassword 以完成密码重置流程。
// The password reset function takes any number of // arguments. final args = []; EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app); await authProvider.callResetPasswordFunction( "lisa@example.com", "n3wSt0ngP4ssw0rd!", functionArgs: args); // ... Later... // Token and tokenId are parameters you can access // in the App Services function context. You could send // this to the user via email, SMS, or some other method. final token = "someToken"; final tokenId = "someTokenId"; await authProvider.completeResetPassword( "n3wSt0ngP4ssw0rd!", token, tokenId);
服务器端成功案例
如果Atlas App Services密码重置函数在函数内进行了额外验证，或者如果您在尝试重置密码之前已验证用户身份，则可以将Atlas App Services函数配置为返回 success。 但是，该返回值不会传递给 SDK 的callResetPasswordFunction() ，因此您的客户端应用程序必须实现自己的逻辑来处理success状态。
调用本示例中的函数会执行整个密码重置过程。
// The password reset function takes any number of // arguments. You might ask the user to provide answers to // security questions, for example, to verify the user // should be able to complete the password reset. final args = [ "Snowball II", "Springfield Elementary School", "Bouvier" ]; EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app); await authProvider.callResetPasswordFunction( "lisa@example.com", "n3wSt0ngP4ssw0rd!", functionArgs: args);
发送密码重置电子邮件
要发送密码重置电子邮件以确认用户身份，您必须将应用配置为发送密码重置电子邮件。
要发送密码重置电子邮件，请将注册时使用的电子邮件传递给 EmailPasswordAuthProvider.resetPassword()。
EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app); await authProvider.resetPassword("lisa@example.com");
密码重置电子邮件包含用两个值token和tokenId编码的 URL。 要完成密码重置流程，您可以在客户端或通过调用后端的自定义函数来重置用户的密码。 要使用 SDK 完成密码重置，请将这些值传递给 EmailPasswordAuthProvider.completeResetPassword()。
如果用户在 30 分钟内没有访问密码重置电子邮件中的 URL， token和tokenId则会过期。 您必须再次开始密码重置过程。
EmailPasswordAuthProvider authProvider = EmailPasswordAuthProvider(app); await authProvider.completeResetPassword( "n3wSt0ngP4ssw0rd!", token, tokenId);
注意
要访问密码重置电子邮件中发送的 token和 值，您可以使用包含tokenId 深层链接 的 自定义密码重置电子邮件 。