使用一键式登录客户端，向用户请求权限，以检索他们之前用于登录您的应用的凭据之一。这些凭据可以是 Google 帐号，也可以是他们使用 Chrome、Android 自动填充或 Smart Lock for Passwords 保存到 Google 的用户名-密码组合。
成功检索凭据后，您可以使用它们让用户轻松登录您的应用。
如果用户未保存任何凭据，则不会显示任何 UI，您可以提供正常的未登录体验。
我应该在哪里使用一键式登录？
如果您的应用要求用户登录，请在登录屏幕上显示一键式登录 UI。即使您已经有“使用 Google 登录”按钮，这样做也很有帮助：因为可以将一键式登录 UI 配置为仅显示用户之前用于登录的凭据，它可以提醒不经常登录的用户他们上次是如何登录的，并防止他们意外地在您的应用中创建新帐号。
如果登录对于您的应用是可选的，请考虑在任何通过登录增强体验的屏幕上使用一键式登录。例如，如果用户可以在未登录状态下浏览您的应用内容，但只有在登录后才能发表评论或将商品添加到购物车，那么这将是使用一键式登录的合理场景。
对于登录可选的应用，出于上述原因，也应在其登录屏幕上使用一键式登录。
开始之前
- 按照一键式登录入门中的说明，设置您的 Google API Console 项目和 Android 项目。
- 如果您支持基于密码的登录，请优化您的应用以进行自动填充（或使用 Smart Lock for Passwords），以便用户在登录后保存他们的密码凭据。
1. 配置一键式登录客户端
您可以将一键式登录客户端配置为使用保存的密码、保存的 Google 帐号或两者兼有来让用户登录。（建议支持两者，以便为新用户实现一键式帐号创建，并为尽可能多的回访用户实现自动或一键式登录。）
如果您的应用使用基于密码的登录，请使用 setPasswordRequestOptions() 启用密码凭据请求。
如果您的应用使用 Google 登录，请使用 setGoogleIdTokenRequestOptions() 启用和配置 Google ID 令牌请求。
将服务器客户端 ID 设置为您在 Google API Console 中创建的 ID。请注意，这是您的服务器的客户端 ID，而不是您的 Android 客户端 ID。
配置客户端以按授权帐号进行过滤。启用此选项后，一键式登录客户端仅提示用户使用他们过去已在您的应用中使用的 Google 帐号登录。这样做可以帮助用户成功登录，尤其是当他们不确定是否已经有帐号或使用了哪个 Google 帐号时，并防止用户意外地在您的应用中创建新帐号。
如果可能，您希望自动让用户登录，请使用
setAutoSelectEnabled()启用此功能。满足以下条件时可以进行自动登录：- 用户为您的应用恰好保存了一个凭据。也就是说，一个保存的密码或一个保存的 Google 帐号。
- 用户未在其Google 帐号设置中禁用自动登录。
虽然是可选的，但我们强烈建议您考虑使用一次性随机数 (nonce) 来提高登录安全性并避免重放攻击。使用setNonce在每个请求中包含一个一次性随机数。请参阅 SafetyNet 的获取一次性随机数部分，了解有关生成一次性随机数的建议和更多详细信息。
Java
public class YourActivity extends AppCompatActivity { // ... private SignInClient oneTapClient; private BeginSignInRequest signInRequest; @Override public void onCreate(@Nullable Bundle savedInstanceState, @Nullable PersistableBundle persistentState) { super.onCreate(savedInstanceState, persistentState); oneTapClient = Identity.getSignInClient(this); signInRequest = BeginSignInRequest.builder() .setPasswordRequestOptions(PasswordRequestOptions.builder() .setSupported(true) .build()) .setGoogleIdTokenRequestOptions(GoogleIdTokenRequestOptions.builder() .setSupported(true) // Your server's client ID, not your Android client ID. .setServerClientId(getString(R.string.default_web_client_id)) // Only show accounts previously used to sign in. .setFilterByAuthorizedAccounts(true) .build()) // Automatically sign in when exactly one credential is retrieved. .setAutoSelectEnabled(true) .build(); // ... } // ... }
Kotlin
class YourActivity : AppCompatActivity() { // ... private lateinit var oneTapClient: SignInClient private lateinit var signInRequest: BeginSignInRequest override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) oneTapClient = Identity.getSignInClient(this) signInRequest = BeginSignInRequest.builder() .setPasswordRequestOptions(BeginSignInRequest.PasswordRequestOptions.builder() .setSupported(true) .build()) .setGoogleIdTokenRequestOptions( BeginSignInRequest.GoogleIdTokenRequestOptions.builder() .setSupported(true) // Your server's client ID, not your Android client ID. .setServerClientId(getString(R.string.your_web_client_id)) // Only show accounts previously used to sign in. .setFilterByAuthorizedAccounts(true) .build()) // Automatically sign in when exactly one credential is retrieved. .setAutoSelectEnabled(true) .build() // ... } // ... }
2. 检查是否已登录用户
如果您的 Activity 可以由已登录或未登录的用户使用，请在显示一键式登录 UI 之前检查用户的状态。
您还应跟踪用户是否已经通过关闭提示或点击提示外部来拒绝使用一键式登录。这就像您 Activity 的一个布尔属性一样简单。（请参阅下面的停止显示一键式 UI。）
3. 显示一键式登录 UI
如果用户未登录且未曾拒绝使用一键式登录，请调用客户端对象的 beginSignIn() 方法，并为返回的 Task 附加监听器。应用通常在 Activity 的 onCreate() 方法中执行此操作，或者在使用单 Activity 架构时在屏幕转换后执行此操作。
如果用户有任何为您的应用保存的凭据，一键式客户端将调用成功监听器。在成功监听器中，从 Task 结果中获取 pending intent，并将其传递给 startIntentSenderForResult() 以启动一键式登录 UI。
如果用户没有保存任何凭据，一键式客户端将调用失败监听器。在这种情况下，无需采取任何操作：您可以继续显示应用的未登录体验。但是，如果您支持一键式注册，您可以在此处开始该流程，以获得无缝的帐户创建体验。请参阅一键创建新帐户。
Java
oneTapClient.beginSignIn(signUpRequest)
.addOnSuccessListener(this, new OnSuccessListener<BeginSignInResult>() {
@Override
public void onSuccess(BeginSignInResult result) {
try {
startIntentSenderForResult(
result.getPendingIntent().getIntentSender(), REQ_ONE_TAP,
null, 0, 0, 0);
} catch (IntentSender.SendIntentException e) {
Log.e(TAG, "Couldn't start One Tap UI: " + e.getLocalizedMessage());
}
}
})
.addOnFailureListener(this, new OnFailureListener() {
@Override
public void onFailure(@NonNull Exception e) {
// No saved credentials found. Launch the One Tap sign-up flow, or
// do nothing and continue presenting the signed-out UI.
Log.d(TAG, e.getLocalizedMessage());
}
});
Kotlin
oneTapClient.beginSignIn(signInRequest)
.addOnSuccessListener(this) { result ->
try {
startIntentSenderForResult(
result.pendingIntent.intentSender, REQ_ONE_TAP,
null, 0, 0, 0, null)
} catch (e: IntentSender.SendIntentException) {
Log.e(TAG, "Couldn't start One Tap UI: ${e.localizedMessage}")
}
}
.addOnFailureListener(this) { e ->
// No saved credentials found. Launch the One Tap sign-up flow, or
// do nothing and continue presenting the signed-out UI.
Log.d(TAG, e.localizedMessage)
}
4. 处理用户的响应
用户对一键式登录提示的响应将通过您 Activity 的 onActivityResult() 方法报告给您的应用。如果用户选择登录，结果将是一个保存的凭据。如果用户通过关闭一键式 UI 或点击 UI 外部拒绝登录，结果将返回代码 RESULT_CANCELED。您的应用需要处理这两种可能性。
使用检索到的凭据登录
如果用户选择与您的应用共享凭据，您可以通过将 onActivityResult() 中的 intent 数据传递给一键式客户端的 getSignInCredentialFromIntent() 方法来检索它们。如果用户与您的应用共享了 Google 帐号凭据，凭据将具有一个非空的 googleIdToken 属性；如果用户共享了保存的密码，则具有一个非空的 password 属性。
使用凭据向您的应用后端进行身份验证。
- 如果检索到用户名和密码对，请使用它们登录，就像用户手动提供它们一样。
如果检索到 Google 帐号凭据，请使用 ID 令牌向您的后端进行身份验证。如果您选择使用一次性随机数来帮助避免重放攻击，请在后端服务器上检查响应值。请参阅使用 ID 令牌通过后端进行身份验证。
Java
public class YourActivity extends AppCompatActivity { // ... private static final int REQ_ONE_TAP = 2; // Can be any integer unique to the Activity. private boolean showOneTapUI = true; // ... @Override protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) { super.onActivityResult(requestCode, resultCode, data); switch (requestCode) { case REQ_ONE_TAP: try { SignInCredential credential = oneTapClient.getSignInCredentialFromIntent(data); String idToken = credential.getGoogleIdToken(); String username = credential.getId(); String password = credential.getPassword(); if (idToken != null) { // Got an ID token from Google. Use it to authenticate // with your backend. Log.d(TAG, "Got ID token."); } else if (password != null) { // Got a saved username and password. Use them to authenticate // with your backend. Log.d(TAG, "Got password."); } } catch (ApiException e) { // ... } break; } } }
Kotlin
class YourActivity : AppCompatActivity() { // ... private val REQ_ONE_TAP = 2 // Can be any integer unique to the Activity private var showOneTapUI = true // ... override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) when (requestCode) { REQ_ONE_TAP -> { try { val credential = oneTapClient.getSignInCredentialFromIntent(data) val idToken = credential.googleIdToken val username = credential.id val password = credential.password when { idToken != null -> { // Got an ID token from Google. Use it to authenticate // with your backend. Log.d(TAG, "Got ID token.") } password != null -> { // Got a saved username and password. Use them to authenticate // with your backend. Log.d(TAG, "Got password.") } else -> { // Shouldn't happen. Log.d(TAG, "No ID token or password!") } } } catch (e: ApiException) { // ... } } } } // ... }
停止显示一键式 UI
如果用户拒绝登录，对 getSignInCredentialFromIntent() 的调用将抛出 ApiException，状态码为 CommonStatusCodes.CANCELED。发生这种情况时，您应该暂时禁用一键式登录 UI，以免重复提示惹恼用户。以下示例通过在 Activity 上设置一个属性来实现此目的，该属性用于确定是否向用户提供一键式登录；但是，您也可以将一个值保存到 SharedPreferences 或使用其他方法。
实施您自己的一键式登录提示速率限制非常重要。如果您不这样做，并且用户连续取消多次提示，则一键式客户端在接下来的 24 小时内不会向用户显示提示。
Java
public class YourActivity extends AppCompatActivity { // ... private static final int REQ_ONE_TAP = 2; // Can be any integer unique to the Activity. private boolean showOneTapUI = true; // ... @Override protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) { super.onActivityResult(requestCode, resultCode, data); switch (requestCode) { case REQ_ONE_TAP: try { // ... } catch (ApiException e) { switch (e.getStatusCode()) { case CommonStatusCodes.CANCELED: Log.d(TAG, "One-tap dialog was closed."); // Don't re-prompt the user. showOneTapUI = false; break; case CommonStatusCodes.NETWORK_ERROR: Log.d(TAG, "One-tap encountered a network error."); // Try again or just ignore. break; default: Log.d(TAG, "Couldn't get credential from result." + e.getLocalizedMessage()); break; } } break; } } }
Kotlin
class YourActivity : AppCompatActivity() { // ... private val REQ_ONE_TAP = 2 // Can be any integer unique to the Activity private var showOneTapUI = true // ... override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) when (requestCode) { REQ_ONE_TAP -> { try { // ... } catch (e: ApiException) { when (e.statusCode) { CommonStatusCodes.CANCELED -> { Log.d(TAG, "One-tap dialog was closed.") // Don't re-prompt the user. showOneTapUI = false } CommonStatusCodes.NETWORK_ERROR -> { Log.d(TAG, "One-tap encountered a network error.") // Try again or just ignore. } else -> { Log.d(TAG, "Couldn't get credential from result." + " (${e.localizedMessage})") } } } } } } // ... }
5. 处理退出登录
当用户退出您的应用时，调用一键式客户端的 signOut() 方法。调用 signOut() 会禁用自动登录，直到用户再次登录。
即使您不使用自动登录，此步骤也很重要，因为它能确保当用户退出您的应用时，您使用的任何 Play 服务 API 的身份验证状态也会被重置。
后续步骤
如果您配置了一键式客户端以检索 Google 凭据，您的应用现在可以获取代表用户 Google 帐号的 Google ID 令牌。了解如何在后端使用这些令牌。
如果您支持 Google 登录，您还可以使用一键式客户端为您的应用添加无缝的帐户创建流程。