Hướng dẫn cho nhà phát triển App Store Review API

App Store Review API cho phép các cửa hàng ứng dụng bên thứ ba đã đăng ký trên Google Play thông qua chương trình Cửa hàng ứng dụng bên thứ ba trên Play cung cấp thông tin bắt buộc cho các ứng dụng được lưu trữ trên cửa hàng của họ. Trong đó có siêu dữ liệu ứng dụng, trang thông tin, tệp nhị phân APK và nội dung khai báo tuân thủ chính sách.

Để xem danh sách đầy đủ các điểm cuối, phương thức và giản đồ tài nguyên, hãy xem Tài liệu tham khảo về App Store Review API.

Trước khi bắt đầu

Bạn phải hoàn tất Hướng dẫn bắt đầu chính để thiết lập quyền truy cập API, thông tin xác thực dịch vụ và dự án trên đám mây của Google Cloud trước khi có thể thực hiện lệnh gọi đến App Store Review API. App Store Review API dự kiến sẽ nhận được tối đa 300 yêu cầu mỗi phút cho mỗi cửa hàng ứng dụng.

Thiết kế và cấu trúc API

App Store Review API hoạt động theo mẫu ảnh chụp nhanh nguyên tử. Thay vì sử dụng các phiên giao dịch, bạn tải từng tệp lên rồi xác nhận trạng thái hoàn tất trong một lệnh gọi duy nhất, nguyên tử:

  1. Bạn tải từng tệp và thành phần (APK, hình ảnh và tệp chính sách) lên trong các lệnh gọi riêng biệt, trực tiếp.
  2. Bạn lưu vào bộ nhớ đệm các mã nhận dạng được trả về cho những tệp đó.
  3. Bạn gửi một yêu cầu UpdateAppStoreHostedApp duy nhất, cuối cùng để xác nhận toàn bộ trạng thái ứng dụng được lưu trữ một cách tự động.

1. Đăng ký

Để đăng ký một ứng dụng được lưu trữ, hãy gọi phương thức createappstorehostedapp, chỉ định tên gói của ứng dụng và tên gói của cửa hàng. Để biết thông tin chi tiết về các giản đồ yêu cầu và phản hồi, hãy xem tài liệu tham khảo API.

2. Tải tệp nhị phân và thành phần lên

Sau khi đăng ký ứng dụng được lưu trữ, bạn phải tải các thành phần của ứng dụng lên bằng các điểm cuối tải lên chuyên biệt:

  • APK: Tất cả các tệp nhị phân APK đang được phân phối của ứng dụng (sử dụng uploadapk).
  • Hình ảnh: Thành phần hình ảnh, chẳng hạn như biểu tượng ứng dụng và ảnh chụp màn hình (sử dụng uploadimage).
  • Chính sách: (Nếu có liên quan) Tài liệu liên quan đến chính sách (sử dụng uploadappstoreapppolicydeclarationfile).

Lưu vào bộ nhớ đệm và sử dụng lại tài sản

Để tối ưu hoá băng thông và hiệu suất, đừng tải lại các thành phần giống hệt nhau. Tất cả mã thông báo apkId, imageId và fileId được trả về đều là mã thông báo liên tục. Bạn có thể lưu các mã nhận dạng này vào bộ nhớ đệm trong cơ sở dữ liệu phụ trợ của riêng mình và sử dụng lại trong các bản cập nhật ứng dụng được lưu trữ tiếp theo. Ví dụ: nếu bạn đang cập nhật nội dung mô tả của một ứng dụng được lưu trữ nhưng biểu tượng ứng dụng và ảnh chụp màn hình vẫn không thay đổi, hãy sử dụng các mã thông báo imageId được lưu vào bộ nhớ đệm trong lệnh gọi cập nhật tiếp theo.

3. Tập hợp và cam kết

Sau khi tải tất cả các thành phần lên thành công và truy xuất mã nhận dạng tương ứng của chúng, bạn phải tập hợp trạng thái đầy đủ của ứng dụng được lưu trữ và xác nhận bằng phương thức updateappstorehostedapp. Phương thức này chấp nhận một bản trình bày hoàn chỉnh, riêng lẻ về thông tin chi tiết của ứng dụng được lưu trữ, trang thông tin được bản địa hoá trên Cửa hàng Play, các nhóm APK đang hoạt động và các tuyên bố về an toàn.

Lệnh gọi này sẽ thay thế mọi trạng thái đang hoạt động trước đó bằng trạng thái mới được mô tả trong yêu cầu.

Ví dụ về nội dung yêu cầu

Sau đây là một nội dung yêu cầu JSON thực tế và hợp lệ về mặt cú pháp minh hoạ tất cả các phần tử khoá:

{
  "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
  ]
}

Khai báo tuân thủ chính sách

Khi gửi hoặc cập nhật thông tin ứng dụng bằng API, bạn phải đưa ra mọi tuyên bố bắt buộc theo chính sách.

Yêu cầu về khai báo

Các nội dung khai báo sau đây thuộc phạm vi áp dụng:

Tất cả ứng dụng đều phải xác nhận xem có cần khai báo thêm hay không:

  1. Ứng dụng sức khoẻ: Hãy cho chúng tôi biết ứng dụng của bạn dùng những tính năng nào về sức khoẻ để giúp chúng tôi nắm được các yêu cầu mà ứng dụng của bạn phải đáp ứng theo Chính sách về ứng dụng sức khoẻ.
  2. Tính năng tài chính: Ứng dụng cung cấp tính năng tài chính có thể phải tuân thủ một số quy định cụ thể tại một số quốc gia hoặc khu vực. Hãy gửi thông tin chính xác và mới nhất về các tính năng tài chính trong ứng dụng để giúp chúng tôi đảm bảo rằng nội dung bạn gửi được các nhóm phù hợp xem xét.
  3. Mã nhận dạng cho quảng cáo: Giúp chúng tôi biết liệu ứng dụng có sử dụng mã nhận dạng cho quảng cáo hay không.
  4. Thông tin đăng nhập để kiểm thử: Nếu ứng dụng của bạn có phần nào bị hạn chế dựa trên thông tin đăng nhập, gói thành viên, vị trí hoặc các hình thức xác thực khác, hãy cung cấp hướng dẫn về cách truy cập vào những phần đó.
  5. Chính sách quyền riêng tư: Đường liên kết đến và thông tin chi tiết về chính sách quyền riêng tư của ứng dụng.
  6. Đối tượng mục tiêu và nội dung: Bạn phải cho chúng tôi biết nhóm tuổi mà ứng dụng nhắm đến và các thông tin khác về nội dung trong ứng dụng. Việc này giúp đảm bảo rằng các ứng dụng dành cho trẻ em luôn an toàn và phù hợp.
  7. Quảng cáo: Bạn phải cho chúng tôi biết ứng dụng của bạn có chứa quảng cáo hay không.

Bắt buộc có điều kiện:

  1. Ứng dụng của chính phủ: Hãy cho chúng tôi biết ứng dụng của bạn có phải dành cho chính phủ (dưới hình thức bất kỳ) sử dụng hay không. Chính phủ ở đây bao gồm cả chính quyền quốc gia, tiểu bang và thành phố cũng như cơ quan quản lý tại địa phương. Thông tin này giúp chúng tôi đảm bảo rằng nội dung bạn gửi được các nhóm phù hợp xem xét. Nếu bạn chưa hoàn tất nội dung khai báo này, thì ứng dụng sẽ được coi là không phải ứng dụng của chính phủ.
  2. Tiêu chuẩn an toàn cho trẻ em: Bắt buộc đối với các ứng dụng thuộc danh mục "Mạng xã hội" hoặc "Hẹn hò". Các ứng dụng thuộc danh mục mạng xã hội hoặc hẹn hò phải cung cấp các tiêu chuẩn an toàn và thông tin liên hệ đã công bố nhằm tuân thủ chính sách về tiêu chuẩn an toàn cho trẻ em của chúng tôi.
  3. Ứng dụng Tin tức và tạp chí: Bắt buộc đối với ứng dụng thuộc danh mục "Tin tức và tạp chí". Thêm thông tin về ứng dụng tin tức và tạp chí để đảm bảo tính minh bạch về các pháp nhân chịu trách nhiệm cho ứng dụng đó.

Cấu trúc yêu cầu API

Thông tin khai báo tuân thủ chính sách được cung cấp trong mảng policyDeclarations trong nội dung của UpdateAppStoreHostedAppRequest. Mỗi mục trong mảng này là một đối tượng AppStoreAppPolicyDeclaration.

AppStoreAppPolicyDeclaration Đối tượng:

  • declarationId (chuỗi, Bắt buộc): Giá trị nhận dạng duy nhất cho nội dung khai báo chính sách (ví dụ: POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • responses (Mảng PolicyResponse, Bắt buộc): Danh sách các câu trả lời cho các câu hỏi trong nội dung khai báo cụ thể đó.

PolicyResponse Đối tượng:

  • questionId (chuỗi, Bắt buộc): Giá trị nhận dạng duy nhất cho câu hỏi cụ thể đang được trả lời (ví dụ: POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • value (Bắt buộc): Câu trả lời, có thể là một trong các loại sau:
    • booleanResponse: Đối với câu hỏi Có hoặc Không.
      • value (boolean)
    • stringResponse: Đối với câu trả lời bằng văn bản thuần tuý, bao gồm cả URL.
      • value (chuỗi)
    • singleChoiceResponse: Khi chỉ có thể chọn một lựa chọn trong danh sách.
      • value (chuỗi): Mã nhận dạng của lựa chọn phản hồi đã chọn.
    • multipleChoiceResponse: Khi bạn có thể chọn nhiều lựa chọn.
      • values (Mảng chuỗi): Mã nhận dạng của các lựa chọn phản hồi đã chọn.
    • documentResponse: Đối với những câu hỏi yêu cầu tải giấy tờ lên. Xem phần Xử lý việc tải tài liệu lên.
    • groupResponse: Đối với các nhóm câu hỏi lặp lại.
    • keyedGroupResponse: Đối với các tập hợp câu hỏi lồng nhau được nhóm theo một khoá cụ thể.

Để biết các đoạn mã ví dụ về khai báo, hãy tham khảo hướng dẫn chi tiết.

Xử lý việc tải tài liệu lên

Một số câu hỏi về chính sách yêu cầu bạn cung cấp giấy tờ hỗ trợ (ví dụ: giấy phép cho Tính năng tài chính). Bạn không thể nhúng trực tiếp tài liệu vào UpdateAppStoreHostedAppRequest. Thay vào đó, bạn phải:

  1. Tải tài liệu lên: Sử dụng điểm cuối UploadAppStoreAppPolicyDeclarationFile. Đây là yêu cầu tải nội dung nghe nhìn lên. Bạn nên đặt fileType thành DECLARATION_FILE_TYPE_DOCUMENT.

    • Điểm cuối: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • Phản hồi tải lên thành công sẽ bao gồm một fileId.

  2. Tham chiếu đến mã nhận dạng tài liệu: Trong PolicyResponse cho câu hỏi về tài liệu, hãy sử dụng loại documentResponse. Điền sẵn trường documentId bằng fileId thu được từ bước tải lên.

PolicyDocumentResponse Đối tượng:

  • documentId (chuỗi, Bắt buộc): Mã nhận dạng được trả về từ điểm cuối UploadAppStoreAppPolicyDeclarationFile.
  • expiryDate (Ngày, không bắt buộc): Ngày hết hạn của giấy tờ (nếu có).
  • nonExpiring (boolean, Không bắt buộc): Đặt thành true nếu giấy tờ không hết hạn.

Ví dụ về Phản hồi bằng tài liệu:

// 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. Kiểm soát phạm vi cung cấp

Sau khi bạn xác nhận trạng thái ứng dụng được lưu trữ bằng UpdateAppStoreHostedApp, theo mặc định, ứng dụng sẽ tự động được xử lý và được đánh dấu là đã xuất bản trong Google Play cho cửa hàng ứng dụng bên thứ ba.

Để kiểm soát phạm vi cung cấp ứng dụng sau khi ứng dụng được xác nhận, hãy gọi phương thức updateappstorehostedapppublishstatus để cập nhật trạng thái của ứng dụng:

  • Huỷ xuất bản ứng dụng: Để ứng dụng được lưu trữ không còn hoạt động, hãy đặt trường publishState thành APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • Phát hành lại ứng dụng: Để cung cấp lại một ứng dụng đã từng bị huỷ phát hành mà không cần sửa đổi trang thông tin hoặc tải lại thành phần, hãy đặt trường publishState thành APP_STORE_APP_PUBLISH_STATE_PUBLISHED.