排查 Android 游戏中与 Play 游戏服务相关的问题

本页介绍了如何排查使用 Google Play 游戏服务开发 Android 游戏时可能遇到的问题。

日志记录

若要排查游戏存在的问题,您可以使用 adb shell 命令在设备上启用详细日志记录。然后,您可以使用 Logcat 查看 Google Play 游戏服务日志消息。

启用日志记录

若要在测试设备上启用日志记录,请执行以下操作:

  1. 将设备连接到已安装 Android SDK 的计算机。

  2. 打开终端并运行以下命令:

    adb shell setprop log.tag.Games VERBOSE
  3. 在设备上运行游戏,并重现您尝试调试的问题。

  4. 查看日志:

    adb logcat

停用日志记录

若要在设备上停用 Play 游戏服务的详细日志记录,并还原为原始日志记录行为,请运行以下命令:

adb shell setprop log.tag.Games INFO

无法登录

如果您无法让玩家登录游戏,请首先确保已按照相关说明创建客户端 ID配置游戏服务。如果仍然遇到登录错误,请检查以下各项,确保您的游戏设置正确。

检查元数据标记

您的 AndroidManifest.xml 必须包含游戏元数据标记。若要验证是否已正确设置元数据标记,请执行以下操作:

  1. 打开 AndroidManifest.xml 并验证它是否包含 meta-data 标记,如下所示:

    <meta-data android:name="com.google.android.gms.games.APP_ID"
        android:value="@string/app_id" />
    
  2. 找到 @string/app_id 资源的定义。此资源的定义通常位于 res/xml 目录中的 XML 文件内,例如 res/xml/strings.xmlres/xml/ids.xml

  3. 验证 @string/app_id 资源的值是否与应用的数字 ID 一致。此资源的值应仅包含数字。例如:

    <string name="app_id">123456789012</string>
    

检查软件包名称

游戏的软件包名称必须与客户端 ID 上的软件包名称一致。若要验证软件包名称,请执行以下操作:

  1. 打开 AndroidManifest.xml 并验证游戏的软件包名称是否正确无误。软件包名称是 manifest 标记中 package 属性的值。

  2. 验证您在创建客户端 ID 时提供的软件包名称。若要在 Google Play 管理中心内验证软件包名称,请进入 Play 管理中心,然后点击与您的游戏对应的条目。

  3. 转到已关联的应用标签页,然后检查客户端 ID 列表。此列表中应有一个已关联的 Android 应用,其软件包名称与 AndroidManifest.xml 中的软件包名称一致。如果不一致,请使用正确的软件包名称创建新的客户端 ID,然后再次尝试登录。

检查证书指纹

您用于为游戏签名的证书应与您的客户端 ID 所关联的证书指纹一致。若要验证这一点,请先检查证书的 SHA1 指纹,如下所示:

  1. 找到您的证书文件,并获取其 SHA1 指纹。若要获取 SHA1 指纹,请运行以下命令:

    keytool -exportcert -alias your-key-name -keystore /path/to/your/keystore/file -list -v
    
  2. 记下输出中带有 SHA1: 标签的十六进制数字序列。这便是您证书的指纹。

接下来,检查您的构建工具是否使用此证书:

  1. 在构建工具中生成游戏的 APK,并使用所需的证书为其签名。将生成的 APK 复制到临时目录。
  2. 在临时目录中,运行以下命令以解压缩 APK。

    unzip YourGame.apk
    
  3. 使用 RSA 证书文件生成私钥:

    keytool -printcert -file META-INF/CERT.RSA
    

    或者,您也可以使用 DSA 证书文件生成私钥:

    keytool -printcert -file META-INF/CERT.DSA
    
  4. 记下带有 SHA1: 标签的行上的十六进制数字序列。

    此数字序列应与上一步中的证书指纹一致。如果不一致,说明您的构建工具或系统没有配置为使用证书为应用签名。在这种情况下,请参阅您的构建环境对应的文档,确定如何正确配置,然后尝试重新登录。

接下来,检查证书指纹是否与客户端 ID 中配置的指纹一致。具体操作步骤如下:

  1. 打开 Play 管理中心,找到您的游戏。
  2. 游戏详情页面上,滚动到底部,然后点击指向关联的 Google Cloud Platform 项目的链接。
  3. 选择您的项目。
  4. 在左侧边栏中,选择 API 和身份验证。在显示的 API 列表中,确保 Google Play 游戏服务 API 的状态为启用
  5. 在左侧边栏中,选择已注册的应用
  6. 展开 OAuth 2.0 客户端 ID 部分,记下证书指纹 (SHA1)。

如果此指纹与上一步中的证书指纹不一致,您必须使用正确的证书指纹创建新的客户端 ID。您必须在 Play 管理中心内(而非 Google Cloud Platform 项目中)创建新的客户端 ID。

检查测试账号是否已启用

在发布游戏之前,您还必须启用用于在 Play 管理中心内创建游戏的账号作为测试账号。若要检查此项配置是否正确无误,请执行以下操作:

  1. 打开 Play 管理中心,找到您的游戏。
  2. 打开测试标签页。
  3. 检查您尝试登录的账号是否在测试账号列表中。

如果您尝试登录的账号未列出,请将其添加到列表中,然后等待几分钟,并尝试重新登录。

Proguard 问题

如果您使用的是 Proguard,并在经过混淆处理的 APK 中看到错误,请检查 AndroidManifest.xml 上的目标 API 级别。请务必将其设置为 17 或更高。

导致设置问题的其他原因

检查是否存在导致错误的其他常见原因:

  • 如果您的游戏已发布,请检查是否也发布了游戏设置(可能出现发布应用但未发布游戏设置的情况)。为此,请进入 Google Play 管理中心,找到您的应用,并检查游戏名称旁边的方框是否指示游戏已发布。如果指示游戏处于其他状态(例如“可以发布”或“可供测试”),请点击该方框并选择发布游戏
  • 如果您无法发布游戏,请检查是否只有一个客户端 ID 启用了此应用是新用户的安装首选选项。

匿名监听器

请勿使用匿名监听器。匿名监听器是监听器接口的实现,以内嵌方式定义,如下所示。

    ImageManager im = ...;

    // Anonymous listener -- dangerous:
    im.loadImage(new ImageManager.OnImageLoadedListener() {
        @Override
        public void onImageLoaded(Uri uri, Drawable drawable) {
            // ...code...
        }
    }

匿名监听器不可靠,因为 Play 游戏 SDK 会将其作为弱引用进行维护,这意味着垃圾回收器可能会在此类监听器被调用之前将其回收。因此,您应使用永久性对象(例如 Activity)实现监听器。

    public class MyActivity extends Activity
            implements ImageManager.OnImageLoadedListener {

        private void loadOurImages() {
            ImageManager im = ...;
            im.loadImage(this);
        }

        @Override
        public void onImageLoaded(Uri uri, Drawable drawable) {
            // ...code...
        }
    }