Android 游戏的登录功能

如需使用 Google Play 游戏服务功能，您的游戏需要提供已登录玩家的帐号。本文档介绍了如何在游戏中实现无缝登录体验。

Play 游戏服务 v2 SDK 引入了多项改进，包括增加了登录游戏的用户数量以及简化了开发工作：

  • 针对用户的改进：
    • 选择默认帐号后，用户便可登录帐号，而无需与提示互动。
    • 用户不必再下载 Play 游戏应用即可通过 Play 游戏服务登录或创建新帐号。
    • 用户现在可以通过单个页面管理多个游戏的 Play 游戏服务帐号。
  • 针对开发者的改进：
    • 游戏启动时会自动触发登录，帐号管理处理也将包含在操作系统设置中，因此客户端代码不再需要处理登录或退出流程。

新客户端集成

本部分介绍了如何与 Play 游戏服务登录 v2 进行新的客户端集成。

添加依赖项

将 Play 游戏服务 SDK 依赖项添加到应用的根级 build.gradle 文件中。如果您使用的是 Gradle，则可以按如下方式添加或更新依赖项：

dependencies {
 implementation "com.google.android.gms:play-services-games-v2:+"
}

定义项目 ID

如需将 Play 游戏服务 SDK 项目 ID 添加到应用，请按以下步骤操作：

  1. 在应用的 AndroidManifest.xml 文件中，将以下 <meta-data> 元素和属性添加到 <application> 元素：

    <manifest>
  <application>
    <meta-data android:name="com.google.android.gms.games.APP_ID"
               android:value="@string/game_services_project_id"/>
  </application>
</manifest>

    使用游戏的游戏服务项目 ID 作为值来定义字符串资源引用 @string/game_services_project_id。您可以在 Google Play 管理中心的“配置”页面中的游戏名称下找到游戏服务项目 ID。

  2. 在 res/values/strings.xml 文件中，添加字符串资源引用，并将项目 ID 设置为值。在 Google Play 管理中心内，您可以在配置页面中的游戏名称下找到项目 ID。例如：

    <!-- res/values/strings.xml -->
<resources>
  <!-- Replace 0000000000 with your game’s project id. Example value shown above.  -->
  <string translatable="false"  name="game_services_project_id"> 0000000000 </string>
</resources>

初始化 SDK

在 Application 类的 onCreate(..) 回调中初始化 Play 游戏 SDK。

import com.google.android.gms.games.PlayGamesSdk;

...

@Override
public void onCreate(){
  super.onCreate();
  PlayGamesSdk.initialize(this);
}

获取登录结果

游戏在启动时始终会尝试让用户登录。如需对用户进行身份验证，您必须先验证用户是否已成功登录，然后获取其玩家 ID。

如需验证登录尝试，请调用 GamesSignInClient.isAuthenticated() 并使用 addOnCompleteListener 检索结果。例如：

GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(getActivity());

gamesSignInClient.isAuthenticated().addOnCompleteListener(isAuthenticatedTask -> {
  boolean isAuthenticated =
    (isAuthenticatedTask.isSuccessful() &&
     isAuthenticatedTask.getResult().isAuthenticated());

  if (isAuthenticated) {
    // Continue with Play Games Services
  } else {
    // Disable your integration with Play Games Services or show a
    // login button to ask  players to sign-in. Clicking it should
    // call GamesSignInClient.signIn().
  }
});

如果用户在游戏启动时选择不登录，您可以选择继续显示一个带有“Play 游戏”图标的按钮，这样当用户按下该按钮时，系统便会尝试通过调用 GamesSignInClient.signIn() 来重新让用户登录。

验证用户已登录后，您可以检索玩家 ID 以识别用户。例如：

PlayGames.getPlayersClient(activity).getCurrentPlayer().addOnCompleteListener(mTask -> {
    // Get PlayerID with mTask.getResult().getPlayerId()
  }
);

迁移至 Play 游戏服务登录 v2

本部分介绍了如何将客户端代码从 Play 游戏服务 v1 迁移到 Play 游戏服务 v2。

新的 SDK 包含以下五项您应当了解的重要变更，将大大提高您的登录成功率：

  1. 当您的游戏启动时，系统会自动触发登录。您可以使用 GamesSignInClient.isAuthenticated() 获取自动登录尝试的结果，而不是使用 GoogleSignIn SDK 的 GoogleSignInClient 执行登录。
  2. 客户端工厂类不再需要传入 GoogleSignInAccount 对象。无法请求额外的 OAuth 范围（系统会自动请求 GAMES_LITE）。
  3. 现在，在 Play 游戏服务 SDK 中使用 GamesSignInClient.requestServerSideAccess() 提供身份验证令牌。
  4. 已移除退出方法，我们不再需要使用游戏内按钮来登录或退出 Play 游戏服务。

此外，由于游戏启动时的自动登录，您的游戏会出现额外登录。因此，您应查看配额管理，确保您的游戏不会超过登录请求配额。

以新的 SDK Maven 制品库为目标

如果您使用的是 Gradle 构建系统，为了做到这一点，您可以在模块的 build.gradle 文件中将依赖项更改为 com.google.android.gms:play-services-games-v2:+ 工件。例如：

dependencies {
 implementation "com.google.android.gms:play-services-games-v2:+"
}

初始化 SDK

在 Application 类的 onCreate(..) 回调中初始化 Play 游戏 SDK。例如：

import com.google.android.gms.games.PlayGamesSdk;

...

@Override
public void onCreate(){
  super.onCreate();
  PlayGamesSdk.initialize(this);
}

移除登录和退出调用

如果您未指定额外的作用域，那么迁移用例应该非常简单。

  1. 移除使用 GoogleSignIn API 进行的登录调用。登录将始终在游戏启动时执行。请使用 GamesSignInClient.isAuthenticated() 监听自动登录尝试的结果。

    GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(getActivity());

gamesSignInClient.isAuthenticated().addOnCompleteListener(isAuthenticatedTask -> {
  boolean isAuthenticated =
    (isAuthenticatedTask.isSuccessful() &&
     isAuthenticatedTask.getResult().isAuthenticated());

  if (isAuthenticated) {
    // Continue with Play Games Services
  } else {
    // Disable your integration with Play Games Services or show a
    // login button to ask  players to sign-in. Clicking it should
    // call GamesSignInClient.signIn().
  }
});

  2. 移除对退出的所有调用，因为帐号管理现在包含在操作系统和 Play 游戏应用的设置中。

  3. 如果玩家已成功登录，请从游戏中移除 Play 游戏登录按钮。如果用户在游戏启动时选择不登录，您可以选择继续显示一个带有“Play 游戏”图标的按钮，并使用 GamesSignInClient.signIn() 触发登录流程。

  4. 验证用户已登录后，您可以检索玩家 ID 以识别用户。

    PlayGames.getPlayersClient(activity).getCurrentPlayer().addOnCompleteListener(mTask -> {
    // Get PlayerID with mTask.getResult().getPlayerId()
  }
);

  5. 如果不再使用 GoogleSignIn API，请移除其依赖项。

更新客户端类名称

创建客户端（例如 LeaderboardsClient 或 AchievementsClient）时，请使用 PlayGames.getFooClient()，而不是 Games.getFooClient()。

请求服务器端访问

请求服务器端访问时，请使用 GamesSignInClient.requestServerSideAccess()，而不是 GoogleSignInAccount.getServerAuthCode()。

GamesSignInClient gamesSignInClient = PlayGames.getGamesSignInClient(this);
gamesSignInClient
  .requestServerSideAccess(OAUTH_2_WEB_CLIENT_ID,
                           /*forceRefreshToken=*/ false)
  .addOnCompleteListener( task -> {
    if (task.isSuccessful()) {
      String serverAuthToken = task.getResult();
      // Send authentication code to the backend game server to be
      // exchanged for an access token and used to verify the
      // player via the Play Games Services REST APIs.
    } else {
      // Failed to retrieve authentication code.
    }
});

移除额外的作用域

对于 Play 游戏服务 v2，您无法请求任何额外的作用域。如果您仍然需要请求额外的作用域，我们建议您结合使用 Google Sign In SDK 和 Play 游戏服务。

从 GoogleApiClient 迁移

对于较旧的现有集成，您的游戏可能依赖于 Play 游戏服务 SDK 的 GoogleApiClient API 变体。此 API 已于 2017 年底被废弃，取而代之的是“无连接”客户端。如需迁移，您可以将 GoogleApiClient 类替换为“无连接”等效类。然后，您还必须按照上述指南将游戏从 v1 迁移到 v2。下面将常见类一一对应起来：

com.google.android.gms.games.achievement.Achievements ->
    com.google.android.gms.games.AchievementsClient

com.google.android.gms.games.leaderboard.Leaderboard ->
    com.google.android.gms.games.LeaderboardsClient

com.google.android.gms.games.snapshot.Snapshots ->
    com.google.android.gms.games.SnapshotsClient

com.google.android.gms.games.stats.PlayerStats ->
    com.google.android.gms.games.PlayerStatsClient

com.google.android.gms.games.Players ->
    com.google.android.gms.games.PlayersClient

com.google.android.gms.games.GamesStatusCodes ->
    com.google.android.gms.games.GamesClientStatusCodes