App Store Review API 開發人員指南

透過 App Store Review API，在 Google Play 註冊的第三方應用程式商店 (透過「Play 第三方應用程式商店」計畫) 可以提供商店中應用程式的必要詳細資料。包括應用程式中繼資料、商店資訊、APK 二進位檔和政策遵循聲明。

如需端點、方法和資源結構定義的完整清單，請參閱 App Store 審查 API 參考資料。

事前準備

如要呼叫 App Store Review API，您必須先完成主要的入門指南，設定 API 存取權、服務憑證和 Google Cloud 雲端專案。每個應用程式商店每分鐘最多可發出 300 個要求。

API 設計與架構

App Store Review API 採用原子快照模式運作。您不必使用交易工作階段，而是個別上傳檔案，然後在單一不可分割的呼叫中提交完整狀態：

  1. 您可以在個別的直接呼叫中，上傳個別檔案和素材資源 (APK、圖片和政策檔案)。
  2. 您會快取這些檔案傳回的 ID。
  3. 您會提交單一最終UpdateAppStoreHostedApp要求，以不可分割的形式提交整個代管應用程式狀態。

1. 註冊

如要註冊代管應用程式，請呼叫 createappstorehostedapp 方法，並指定應用程式的套件名稱和商店的套件名稱。如要瞭解要求和回應結構定義的詳細資料，請參閱 API 參考資料。

2. 上傳二進位檔和資產

註冊代管應用程式後，您必須使用專用的上傳端點上傳資產：

資產快取和重複使用

為盡量節省頻寬並提升效能，請勿重複上傳相同資產。 所有傳回的 apkId、imageId 和 fileId 權杖都會持續存在。您可以將這些 ID 緩存在自己的後端資料庫中，並在後續的代管應用程式更新中重複使用。舉例來說，如果您要更新代管應用程式的說明，但應用程式圖示和螢幕截圖維持不變，請在下一次更新呼叫中使用快取 imageId 權杖。

3. 組裝並提交

成功上傳所有資產並擷取各自的 ID 後，您必須組裝完整的代管應用程式狀態，並使用 updateappstorehostedapp 方法提交。這個方法會接受代管應用程式詳細資料、本地化商店資訊、有效 APK 套件和安全聲明等完整原子表示法。

這項呼叫會將先前任何有效狀態，替換為要求中說明的新狀態。

要求主體範例

以下是實際且語法有效的 JSON 要求主體，說明所有重要元素：

{
  "appStorePackageName": "com.example.thirdparty.store",
  "packageName": "com.example.hostedapp.game",
  "appDetails": {
    "developerName": "Adventure Games Studio Ltd.",
    "contactEmail": "support@adventuregames.example.com",
    "developerWebsite": "https://adventuregames.example.com"
  },
  "activeLocalizedStoreListings": [
    {
      "languageCode": "en-US",
      "appName": "Super Quest Legends",
      "shortDescription": "An epic fantasy RPG adventure.",
      "fullDescription": "Super Quest Legends is an immersive action RPG featuring real-time battles, customizable classes, and a deep fantasy narrative. Journey through a magical realm, fight epic bosses, and team up with friends in dungeon raids.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ],
      "videoLink": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    },
    {
      "languageCode": "es-ES",
      "appName": "Super Quest Leyendas",
      "shortDescription": "Una aventura épica de RPG fantástico.",
      "fullDescription": "Super Quest Leyendas es un RPG de acción inmersivo con batallas en tiempo real, clases personalizables y una profunda narrativa de fantasía. Viaja a través de un reino mágico, lucha contra jefes épicos y únete a amigos en incursiones.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ]
    }
  ],
  "activeApks": {
    "activeApkSets": [
      {
        "baseApkId": "554433"
      },
      {
        "baseApkId": "990011"
      }
    ]
  },
  "policyDeclarations": [
    {
      "declarationId": "POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS",
          "multipleChoiceResponse": {
            "values": [
              "POLICY_RESPONSE_CHOICE_ID_TAC_AGE_EIGHTEEN_AND_ABOVE"
            ]
          }
        },
        // ... other responses for TAC
      ]
    },
    {
      "declarationId": "POLICY_DECLARATION_ID_ADVERTISING_ID",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_AD_ID_IS_USED",
          "booleanResponse": {
            "value": false
          }
        }
        // ... other responses for AD_ID
      ]
    }
    // ... other declarations
  ]
}

政策聲明

使用 API 提交或更新應用程式資訊時，請務必納入所有必要的政策聲明。

聲明規定

以下聲明屬於適用範圍：

所有應用程式都必須完成這項步驟，確認是否需要額外聲明：

  1. 健康應用程式：請說明應用程式使用的健康功能，協助我們瞭解該應用程式必須符合健康應用程式政策中的哪些規定。
  2. 金融功能：提供金融功能的應用程式可能需要遵守某些國家/地區的特定法規。請提交有關應用程式金融功能的最新正確資訊，以利我們確保由合適團隊審查您提交的內容。
  3. 廣告 ID：請協助我們瞭解應用程式是否使用廣告 ID。
  4. 測試憑證 (登入詳細資料)：如果應用程式的部分內容須提供登入詳細資料、會員身分、位置資訊或其他驗證方式才可存取，請說明存取方式。
  5. 隱私權政策：應用程式隱私權政策的連結和詳細資料。
  6. 目標對象和內容：您必須將應用程式的目標年齡層告訴我們，並提供有關其內容的其他資訊。這有助於確保專為兒童設計的應用程式提供安全且適當的內容。
  7. 廣告：您必須聲明應用程式是否含有廣告。

必要 (有條件)：

  1. 政府應用程式：請指明應用程式是否由任何類型的政府機構使用，比如國家、州/省和市級政府及地方主管機關。這有助於我們確保由合適的團隊審查您提交的內容。如果未填寫這份聲明，系統會將應用程式視為非政府應用程式。
  2. 兒童安全標準：「社交」或「約會交友」類別的應用程式必須遵守這項規定。社交或約會交友類別的應用程式必須公開安全標準並提供聯絡資訊，遵守兒童安全標準政策。
  3. 新聞與雜誌應用程式：「新聞與雜誌」類別的應用程式必須完成這項聲明。新增有關新聞與雜誌應用程式的詳細資料，協助使用者瞭解背後的營運實體。

API 要求結構

政策聲明會提供在 UpdateAppStoreHostedAppRequest 主體的 policyDeclarations 陣列中。這個陣列中的每個項目都是 AppStoreAppPolicyDeclaration 物件。

AppStoreAppPolicyDeclaration 物件：

  • declarationId (字串，必填)：政策聲明的專屬 ID (例如 POLICY_DECLARATION_ID_FINANCE、POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT)。
  • responses (PolicyResponse 陣列，必要)：特定聲明中問題的答案清單。

PolicyResponse 物件：

  • questionId (字串，必填)：要回答的特定問題專屬 ID (例如 POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES、POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS)。
  • value (必填)：答案本身，可以是下列其中一種型別：
    • booleanResponse：適用於「是」或「否」問題。
      • value (布林值)
    • stringResponse：純文字答案，包括網址。
      • value (字串)
    • singleChoiceResponse：只能從清單中選取一個選項時。
      • value (字串)：所選回應選項的 ID。
    • multipleChoiceResponse：可選取多個選項。
      • values (字串陣列)：所選回應選項的 ID。
    • documentResponse：需要上傳文件的問題。請參閱「處理文件上傳作業」。
    • groupResponse：適用於重複的巢狀問題集。
    • keyedGroupResponse：針對依特定鍵分組的巢狀問題集。

如需宣告的範例程式碼片段，請參閱詳細指南。

處理文件上傳作業

部分政策問題需要您提供佐證文件 (例如金融功能執照)。文件無法直接嵌入 UpdateAppStoreHostedAppRequest。請改用下列做法：

  1. 上傳文件：使用 UploadAppStoreAppPolicyDeclarationFile 端點。這是媒體上傳要求。fileType 應設為 DECLARATION_FILE_TYPE_DOCUMENT。

    • 端點： POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • 成功上傳的回應會包含 fileId。

  2. 參照文件 ID：在文件問題的 PolicyResponse 中，使用 documentResponse 型別。使用上傳步驟取得的 fileId 填入 documentId 欄位。

PolicyDocumentResponse 物件：

  • documentId (字串，必要)：從 UploadAppStoreAppPolicyDeclarationFile 端點傳回的 ID。
  • expiryDate (日期，選填)：文件的到期日 (如適用)。
  • nonExpiring (布林值，選用)：如果文件不會過期，請設為 true。

文件回應範例：

// Inside a PolicyResponse object
{
  "questionId": "POLICY_QUESTION_ID_FINANCE_CRYPTO_US_FINCEN_LICENSE", // Example ID
  "documentResponse": {
    "documentId": "123456789", // The fileId from upload
    "expiryDate": {
      "year": 2027,
      "month": 6,
      "day": 1
    }
  }
}

4. 控管播放地區

使用 UpdateAppStoreHostedApp 提交代管應用程式狀態後，Google Play 會自動處理應用程式，並預設標示為已發布至第三方應用程式商店。

如要在應用程式提交後控管其適用情形，請呼叫 updateappstorehostedapppublishstatus 方法來更新應用程式狀態：

  • 取消發布應用程式：如要停用代管應用程式，請將 publishState 欄位設為 APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED。
  • 重新發布應用程式：如要讓先前取消發布的應用程式再次上架，但不想修改資訊或重新上傳資產，請將 publishState 欄位設為 APP_STORE_APP_PUBLISH_STATE_PUBLISHED。