随着 Google 登录 API 的弃用,我们将在 2026 年移除 games v1 SDK。2025 年 2 月之后,您将无法在 Google Play 上发布新集成 games v1 SDK 的游戏。我们建议您改用 games v2 SDK。
虽然现有的使用旧版 games v1 集成的游戏仍可运行数年,但我们鼓励您从 2025 年 6 月开始迁移到 v2。
本指南介绍如何使用 Play 游戏服务 v1 SDK。有关最新 SDK 版本的信息,请参阅v2 文档。
为了访问 Google Play 游戏服务功能,您的游戏需要提供已登录玩家的账号。如果玩家未经过身份验证,您的游戏在调用 Google Play 游戏服务 API 时可能会遇到错误。本文档介绍如何在游戏中实现无缝的登录体验。
实现玩家登录
的 GoogleSignInClient
类是检索当前登录玩家账号的主要入口点,如果玩家尚未在该设备上使用您的应用登录过,也可以用于让玩家登录。
要创建登录客户端,请按以下步骤操作
通过
GoogleSignInOptions
对象创建登录客户端,如以下代码段所示。在用于配置登录的GoogleSignInOptions.Builder
中,您必须指定GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN
。GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
如果您想使用
SnapshotsClient
,则将.requestScopes(Games.SCOPE_GAMES_SNAPSHOTS)
添加到您的GoogleSignInOptions.Builder
中,如以下代码段所示GoogleSignInOptions signInOptions = new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN) .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS) .build();
调用
GoogleSignIn.getClient()
方法,并传入您在之前步骤中配置的选项。如果调用成功,Google 登录 API 将返回GoogleSignInClient
的实例。
检查玩家是否已登录
您可以使用 GoogleSignIn.getLastSignedInAccount()
检查当前设备上是否已有一个账号登录,并使用 GoogleSignIn.hasPermissions()
检查此账号是否已获得所需的权限。如果两个条件都为 true(即 getLastSignedInAccount()
返回非 null 值且 hasPermissions()
返回 true
),即使设备处于离线状态,您也可以安全地使用从 getLastSignedInAccount()
返回的账号。
执行静默登录
您可以调用 silentSignIn()
来检索当前登录的玩家账号,如果玩家已在其他设备上成功登录到您的应用,则尝试让玩家在不显示用户界面的情况下登录。
的 silentSignIn()
方法返回一个 Task<GoogleSignInAccount>
。任务完成后,您可以将之前声明的 GoogleSignInAccount
字段设置为任务返回的登录账号,或设置为 null
,表示没有登录用户。
如果静默登录尝试失败,您可以选择性地发送登录 intent 以显示登录用户界面,如执行交互式登录中所述。
由于活动不在前台时已登录玩家的状态可能会改变,因此我们建议从活动的 onResume()
方法中调用 silentSignIn()
。
要静默登录,请按照以下步骤操作
- 在
GoogleSignInClient
上调用silentSignIn()
方法以启动静默登录流程。如果静默登录成功,此调用将返回一个Task<GoogleSignInAccount>
对象,其中包含一个GoogleSignInAccount
。 - 通过重写
OnCompleteListener
处理玩家登录的成功或失败。- 如果登录任务成功,通过调用
getResult()
获取GoogleSignInAccount
对象。 - 如果登录不成功,您可以发送一个登录 intent 以启动交互式登录流程。有关您可以使用的其他回调监听器的列表,请参阅 Tasks API 开发者指南和
Task
API 参考。
- 如果登录任务成功,通过调用
以下代码段展示了您的应用如何执行静默登录
private void signInSilently() { GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN; GoogleSignInAccount account = GoogleSignIn.getLastSignedInAccount(this); if (GoogleSignIn.hasPermissions(account, signInOptions.getScopeArray())) { // Already signed in. // The signed in account is stored in the 'account' variable. GoogleSignInAccount signedInAccount = account; } else { // Haven't been signed-in before. Try the silent sign-in first. GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOptions); signInClient .silentSignIn() .addOnCompleteListener( this, new OnCompleteListener<GoogleSignInAccount>() { @Override public void onComplete(@NonNull Task<GoogleSignInAccount> task) { if (task.isSuccessful()) { // The signed in account is stored in the task's result. GoogleSignInAccount signedInAccount = task.getResult(); } else { // Player will need to sign-in explicitly using via UI. // See [sign-in best practices](http://developers.google.com/games/services/checklist) for guidance on how and when to implement Interactive Sign-in, // and [Performing Interactive Sign-in](http://developers.google.com/games/services/android/signin#performing_interactive_sign-in) for details on how to implement // Interactive Sign-in. } } }); } } @Override protected void onResume() { super.onResume(); signInSilently(); }
如果静默登录尝试失败,您可以调用 getException()
获取一个包含详细状态码的 ApiException
。状态码为 CommonStatusCodes.SIGN_IN_REQUIRED
表示玩家需要执行明确的操作才能登录。在这种情况下,您的应用应按照下一节所述启动交互式登录流程。
执行交互式登录
若要通过玩家互动进行登录,您的应用需要启动登录 intent。如果成功,Google 登录 API 会显示一个用户界面,提示玩家输入其凭据以进行登录。此方法可简化您的应用开发,因为登录 activity 会代表您的应用处理需要更新 Google Play 服务或显示同意提示等情况。结果将通过 onActivityResult
回调返回。
要执行交互式登录,请按照以下步骤操作
在
GoogleSignInClient
上调用getSigninIntent()
以获取登录 intent,然后调用startActivity()
并传入该 intent。以下代码段展示了您的应用如何启动交互式登录流程private void startSignInIntent() { GoogleSignInClient signInClient = GoogleSignIn.getClient(this, GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN); Intent intent = signInClient.getSignInIntent(); startActivityForResult(intent, RC_SIGN_IN); }
在
onActivityResult()
回调中,处理返回 intent 的结果。- 如果登录结果成功,从
GoogleSignInResult
中获取GoogleSignInAccount
对象。 - 如果登录失败,您应该处理登录错误(例如,在提示框中显示错误消息)。以下代码段展示了您的应用如何处理玩家登录结果
@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode == RC_SIGN_IN) { GoogleSignInResult result = Auth.GoogleSignInApi.getSignInResultFromIntent(data); if (result.isSuccess()) { // The signed in account is stored in the result. GoogleSignInAccount signedInAccount = result.getSignInAccount(); } else { String message = result.getStatus().getStatusMessage(); if (message == null || message.isEmpty()) { message = getString(R.string.signin_other_error); } new AlertDialog.Builder(this).setMessage(message) .setNeutralButton(android.R.string.ok, null).show(); } } }
- 如果登录结果成功,从
检索玩家信息
Google 登录 API 返回的 GoogleSignInAccount
不包含任何玩家信息。如果您的游戏使用玩家信息,例如玩家的显示名和玩家 ID,您可以按照以下步骤检索此信息。
- 通过调用
getPlayersClient()
方法并传入GoogleSignInAccount
作为参数,获取PlayersClient
对象。 - 使用
PlayersClient
方法异步加载包含玩家信息的Player
对象。例如,您可以调用getCurrentPlayer()
来加载当前登录的玩家。如果任务返回带有SIGN_IN_REQUIRED
状态码的ApiException
,这表明玩家需要重新进行身份验证。为此,请调用GoogleSignInClient.getSignInIntent()
以进行交互式玩家登录。 - 如果任务成功返回
Player
对象,则可以调用Player
对象的方法来检索特定的玩家详细信息(例如,getDisplayName()
或getPlayerId()
)。
提供登录按钮
要在您的游戏中提供标准的 Google 登录按钮,您可以使用以下任一方法
- 在主 activity 布局中包含一个
com.google.android.gms.common.SignInButton
;或 - 根据 Google 登录品牌指南设计自定义登录按钮。
当用户点击登录按钮时,您的游戏应通过发送登录 intent 来启动登录流程,如执行交互式登录中所述。
此代码段展示了如何在您的 activity 的 onCreate()
方法中添加登录按钮。
@Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_sign_in); findViewById(R.id.sign_in_button).setOnClickListener(this); findViewById(R.id.sign_out_button).setOnClickListener(this); }
以下代码段展示了当用户点击登录按钮时,您如何发送登录 intent。
@Override public void onClick(View view) { if (view.getId() == R.id.sign_in_button) { // start the asynchronous sign in flow startSignInIntent(); } else if (view.getId() == R.id.sign_out_button) { // sign out. signOut(); // show sign-in button, hide the sign-out button findViewById(R.id.sign_in_button).setVisibility(View.VISIBLE); findViewById(R.id.sign_out_button).setVisibility(View.GONE); } }
显示游戏弹窗
您可以使用 GamesClient
类在游戏中显示弹出视图。例如,您的游戏可以显示“欢迎回来”或“成就已解锁”弹出窗口。要允许 Google Play 游戏服务在游戏视图中启动弹出窗口,请调用 setViewForPopups()
方法。您还可以通过调用 setGravityForPopups()
进一步自定义弹出窗口在屏幕上的位置。
玩家退出登录
通过在 GoogleSignInClient
上调用 signOut()
方法进行退出登录。
private void signOut() { GoogleSignInClient signInClient = GoogleSignIn.getClient(this, GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN); signInClient.signOut().addOnCompleteListener(this, new OnCompleteListener<Void>() { @Override public void onComplete(@NonNull Task<Void> task) { // at this point, the user is signed out. } }); }