如需使用 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 添加到应用,请按以下步骤操作:
在应用的
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。在
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 包含以下五项您应当了解的重要变更,将大大提高您的登录成功率:
- 当您的游戏启动时,系统会自动触发登录。您可以使用
GamesSignInClient.isAuthenticated()
获取自动登录尝试的结果,而不是使用 GoogleSignIn SDK 的GoogleSignInClient
执行登录。 - 客户端工厂类不再需要传入
GoogleSignInAccount
对象。无法请求额外的 OAuth 范围(系统会自动请求GAMES_LITE
)。 - 现在,在 Play 游戏服务 SDK 中使用
GamesSignInClient.requestServerSideAccess()
提供身份验证令牌。 - 已移除退出方法,我们不再需要使用游戏内按钮来登录或退出 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);
}
移除登录和退出调用
如果您未指定额外的作用域,那么迁移用例应该非常简单。
移除使用 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(). } });
移除对退出的所有调用,因为帐号管理现在包含在操作系统和 Play 游戏应用的设置中。
如果玩家已成功登录,请从游戏中移除 Play 游戏登录按钮。如果用户在游戏启动时选择不登录,您可以选择继续显示一个带有“Play 游戏”图标的按钮,并使用
GamesSignInClient.signIn()
触发登录流程。验证用户已登录后,您可以检索玩家 ID 以识别用户。
PlayGames.getPlayersClient(activity).getCurrentPlayer().addOnCompleteListener(mTask -> { // Get PlayerID with mTask.getResult().getPlayerId() } );
如果不再使用 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