為 Android 遊戲的 Play 遊戲服務進行疑難排解

本頁提供的疑難排解說明可協助您解決運用 Google Play 遊戲服務開發 Android 遊戲時可能遇到的問題。

記錄

您可以使用 adb shell 指令在裝置上開啟詳細記錄，藉此為遊戲問題進行疑難排解。使用 Logcat 即可檢視 Google Play 遊戲服務記錄訊息。

啟用記錄功能

如何啟用測試裝置的記錄功能：

將裝置連線至已安裝 Android SDK 的電腦。
開啟終端機並執行下列指令：
```
adb shell setprop log.tag.Games VERBOSE
```
在裝置上執行遊戲並重現您想偵錯的問題。
檢視記錄：
```
adb logcat
```

停用記錄

若要停用裝置上的 Play 遊戲服務詳細記錄功能，並回復原本的記錄行為，請執行以下指令：

adb shell setprop log.tag.Games INFO

無法登入

如果您無法讓玩家登入遊戲，首先請確實按照建立用戶端 ID 與設定遊戲服務的指示進行。如果登入錯誤的問題仍未解決，請檢查下列項目，確保您的遊戲設定正確。

檢查中繼資料標記

您的 AndroidManifest.xml 內必須含有遊戲的中繼資料標記。驗證中繼資料標記是否設定正確的方法如下：

開啟 AndroidManifest.xml 並確認其中含有 meta-data 標記，如下所示：

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

找到 @string/app_id 資源的定義。用來定義資源的 XML 檔案通常位於 res/xml 目錄，例如 res/xml/strings.xml 或 res/xml/ids.xml。
確認 @string/app_id 資源的值與您應用程式的數字 ID 相符。此資源的值須全部由數字組成。例如：
```
<string name="app_id">123456789012</string>
```

檢查套件名稱

您遊戲的套件名稱必須與用戶端 ID 的套件名稱相符。確認套件名稱的方法如下：

開啟 AndroidManifest.xml 並確認遊戲套件名稱是否正確。套件名稱為 manifest 標記中 package 屬性的值。
建立用戶端 ID 時請確認您提供的套件名稱。如要在 Google Play 管理中心中確認套件名稱，請前往 Play 管理中心並按一下與您遊戲相應的項目。
前往「Linked Apps」(連結的應用程式) 分頁標籤檢查用戶端 ID 清單。此清單中應有一個 Android 已連結的應用程式，其套件名稱與您 AndroidManifest.xml 中的套件名稱相符。如果套件名稱不符，請以正確的套件名稱建立新的用戶端 ID，並再次嘗試登入。

檢查憑證指紋

您用來簽署遊戲的憑證必須與您用戶端 ID 相關聯的憑證指紋相符。如要驗證憑證，請先檢查憑證的 SHA1 指紋，如下所示：

找到您的憑證檔案並取得其 SHA1 指紋。如需取得 SHA1 指紋，請執行以下指令：
```
keytool -exportcert -alias your-key-name -keystore /path/to/your/keystore/file -list -v
```
記下輸出內容中標示為 SHA1: 的十六進位數列。此數字即為憑證的指紋。

接著，檢查您的建構工具是否使用這個憑證：

透過您的建構工具產生遊戲的 APK，並使用想驗證的憑證簽署 APK。將產生的 APK 複製到臨時的目錄。
在該臨時目錄內執行以下指令，以便解壓縮 APK。
```
unzip YourGame.apk
```
使用 RSA 憑證檔案產生私密金鑰：
```
keytool -printcert -file META-INF/CERT.RSA
```
您也可以使用 DSA 憑證檔案產生私密金鑰：
```
keytool -printcert -file META-INF/CERT.DSA
```
找到標示為 SHA1: 的行，並記下其中的十六進位數列。

此數列應該與您在上一個步驟中取得的憑證指紋相符。如果數字不相符，代表您的建構工具或系統並非設定使用憑證簽署應用程式。如果遇到這種情況，請參閱建構環境的說明文件，瞭解如何正確設定憑證，然後再次嘗試登入。

接著，檢查憑證指紋是否與您在用戶端 ID 中設定的指紋相符。確認的方法如下：

開啟 Play 管理中心，然後前往您的遊戲。
在「Game Details」(遊戲詳細資料) 頁面中，往下捲動到底端並按一下連結，前往已連結的 Google Cloud Platform 專案。
選取專案。
點選左側欄的「APIs & auth」(API 和驗證)。查看系統顯示的 API 清單，並確認 Google Play 遊戲服務 API 的狀態是「ON」(開啟)。
點選左側欄的「Registered apps」(註冊應用程式)。
展開 OAuth 2.0 用戶端 ID 區段，然後記下憑證指紋 (SHA1)。

如果這個指紋與您在前幾個步驟中取得的憑證指紋不相符，那麼您必須以正確的憑證指紋建立新的用戶端 ID。建立新用戶端 ID 時須使用 Play 管理中心，無法透過 Google Cloud Platform 專案建立。

檢查是否已啟用測試帳戶

在發布遊戲前，您透過 Play 管理中心建立遊戲時所用的帳戶也必須啟用為測試人員。若要檢查設定是否正確，請按照以下方式操作：

開啟 Play 管理中心，然後前往您的遊戲。
開啟「Testing」(測試) 分頁標籤。
檢查您嘗試用來登入的帳戶是否在測試人員清單中。

如果您嘗試登入的帳戶不在清單中，請將其加入清單中，稍待幾分鐘後再次嘗試登入。

Proguard 問題

如果您使用 Proguard 而且模糊 APK 會顯示錯誤訊息，請檢查 AndroidManifest.xml 內的目標 API 級別，並確實將其設為 17 以上。

其他造成設定問題的原因

檢查其他造成錯誤的常見原因：

如果您已經發布遊戲，請檢查是否也已經發布遊戲設定 (您可能會在發布應用程式時忘了發布遊戲設定)。您可以前往 Google Play 管理中心並前往應用程式，然後勾選遊戲名稱旁邊的方塊，表示已經發布完畢。如果顯示其他狀態，例如「Ready to Publish」(可供發布) 或「Ready to Test」(可供測試)，請按一下方塊後點選「Publish Game」(發布遊戲)。
如果無法發布遊戲，請看啟用「This app is preferred for new installations」(進行全新安裝時偏好使用此應用程式) 選項的是否只有一個用戶端 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...
        }
    }