继 Google 登录 API 弃用后,我们将在 2026 年移除 games v1 SDK。2025 年 2 月之后,您将无法在 Google Play 上发布新集成了 games v1 SDK 的作品。我们建议您改为使用 games v2 SDK。
虽然现有集成 games v1 的作品在未来几年内将继续运行,但我们建议您从 2025 年 6 月开始迁移到 v2。
本指南适用于使用 Play Games Services v1 SDK。有关最新 SDK 版本的信息,请参阅v2 文档。
本指南介绍了如何在 Android 应用中使用成就 API 来解锁和显示游戏中的成就。这些 API 位于 com.google.android.gms.games
和 com.google.android.gms.games.achievements
软件包中。
准备工作
如果您尚未进行,建议您先查看成就游戏概念。
开始使用成就 API 编写代码之前
- 按照设置 Google Play 服务 SDK 指南中的说明,安装和设置您的应用以使用 Google Play 游戏服务。
- 按照Google Play 管理中心指南中的说明,定义您希望游戏解锁或显示的成就。
- 在Android 示例页面中下载和查看成就代码示例。
- 熟悉质量核对清单中描述的建议。
获取成就客户端
要开始使用成就 API,您的游戏必须先获取一个 AchievementsClient
对象。您可以通过调用 Games.getAchievementClient()
方法并传入 Activity 和当前玩家的 GoogleSignInAccount
来执行此操作。如需了解如何检索玩家账号信息,请参阅Android 游戏中的登录。
解锁成就
要解锁成就,请调用 AchievementsClient.unlock()
方法并传入成就 ID。
以下代码段显示了应用如何解锁成就
Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this)) .unlock(getString(R.string.my_achievement_id));
如果该成就是增量类型(即需要执行多个步骤才能解锁),请改为调用 AchievementsClient.increment()
。
以下代码段展示了应用如何递增玩家的成就进度
Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this)) .increment(getString(R.string.my_achievement_id), 1);
您无需编写额外的代码来解锁成就;Google Play 游戏服务会在成就达到所需的步骤数后自动解锁。
一种好的做法是在 strings.xml
文件中定义成就 ID,以便您的游戏可以通过资源 ID 引用这些成就。在调用以更新和加载成就时,请务必遵循这些最佳实践,以免超出 API 配额。
显示成就
要显示玩家的成就,请调用 AchievementsClient.getAchievementsIntent()
以获取一个 Intent
,用于创建默认的成就用户界面。然后,您的游戏可以通过调用 startActivityForResult
显示该界面。
以下代码段显示了应用如何显示默认的成就用户界面。在此代码段中,RC_ACHIEVEMENT_UI
是一个任意整数,游戏将其用作请求代码。
private static final int RC_ACHIEVEMENT_UI = 9003; private void showAchievements() { Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this)) .getAchievementsIntent() .addOnSuccessListener(new OnSuccessListener<Intent>() { @Override public void onSuccess(Intent intent) { startActivityForResult(intent, RC_ACHIEVEMENT_UI); } }); }
下面显示了默认成就界面的示例。
