Panduan Developer App Store Review API

App Store Review API memungkinkan app store pihak ketiga yang terdaftar di Google Play melalui program App store pihak ketiga di Google Play untuk memberikan detail yang diperlukan bagi aplikasi yang dihosting di app store mereka. Hal ini mencakup metadata aplikasi, listingan, program biner APK, dan pernyataan kepatuhan terhadap kebijakan.

Untuk mengetahui daftar lengkap endpoint, metode, dan skema resource, lihat Referensi App Store Review API.

Sebelum Memulai

Anda harus menyelesaikan Panduan Memulai utama untuk menyiapkan akses API, kredensial layanan, dan project Google Cloud sebelum dapat melakukan panggilan ke App Store Review API. App Store Review API mendukung maksimal 300 permintaan per menit per app store.

Desain & Arsitektur API

App Store Review API beroperasi pada pola snapshot atomik. Alih-alih menggunakan sesi transaksional, Anda harus mengupload file satu per satu, lalu melakukan commit status lengkap dalam satu panggilan atomik:

  1. Anda harus mengupload file dan aset individual (APK, gambar, dan file kebijakan) dalam panggilan langsung yang terpisah.
  2. Anda harus meng-cache ID yang ditampilkan untuk file-file tersebut.
  3. Anda harus mengirimkan satu permintaan UpdateAppStoreHostedApp terakhir untuk melakukan commit status aplikasi yang dihosting secara atomik.

1. Pendaftaran

Untuk mendaftarkan aplikasi yang dihosting, panggil metode createappstorehostedapp dengan menentukan nama paket aplikasi dan nama paket app store Anda. Untuk mengetahui detail skema permintaan dan respons, lihat referensi API.

2. Upload program biner dan aset

Setelah aplikasi yang dihosting didaftarkan, Anda harus mengupload asetnya menggunakan endpoint upload khusus:

  • APK: Semua program biner APK aplikasi yang didistribusikan secara aktif (menggunakan uploadapk).
  • Gambar: Aset gambar, seperti ikon aplikasi dan screenshot (menggunakan uploadimage).
  • Kebijakan: (Jika relevan) Dokumentasi terkait kebijakan (menggunakan uploadappstoreapppolicydeclarationfile).

Melakukan Cache & Penggunaan Ulang Aset

Untuk mengoptimalkan bandwidth dan performa, jangan mengupload ulang aset yang identik. Semua token apkId, imageId, dan fileId yang ditampilkan bersifat persisten. Anda dapat meng-cache ID ini di database backend Anda sendiri dan menggunakannya kembali dalam update aplikasi yang dihosting berikutnya. Misalnya, jika Anda memperbarui deskripsi aplikasi yang dihosting, tetapi ikon aplikasi dan screenshot tetap tidak berubah, gunakan token imageId yang di-cache dalam permintaan update berikutnya.

3. Susun dan commit

Setelah semua aset berhasil diupload dan ID masing-masing diperoleh, Anda harus menyusun status aplikasi yang dihosting sepenuhnya dan melakukan commit menggunakan metode updateappstorehostedapp. Metode ini menerima representasi lengkap dan atomik dari detail aplikasi yang dihosting, listingan Google Play Store yang dilokalkan, set APK aktif, dan pernyataan keamanan.

Panggilan ini menggantikan status aktif sebelumnya dengan status baru yang dijelaskan dalam permintaan.

Contoh Isi Permintaan

Berikut adalah isi permintaan JSON yang realistis dan valid secara sintaksis yang menggambarkan semua elemen utama:

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

Pernyataan Kebijakan

Saat mengirimkan atau memperbarui informasi aplikasi menggunakan API, Anda harus menyertakan pernyataan kebijakan yang diperlukan.

Persyaratan Pernyataan

Pernyataan berikut termasuk dalam cakupan:

Diwajibkan untuk semua aplikasi guna mengonfirmasi apakah pernyataan tambahan diperlukan:

  1. Aplikasi Kesehatan: Beri tahu kami fitur kesehatan apa yang digunakan aplikasi agar kami dapat menentukan persyaratan mana yang harus dipenuhi aplikasi berdasarkan kebijakan Aplikasi kesehatan.
  2. Fitur Keuangan: Aplikasi yang menyediakan fitur keuangan mungkin harus mematuhi peraturan tertentu di beberapa negara atau wilayah. Kirimkan detail fitur keuangan yang akurat dan terbaru di aplikasi Anda untuk membantu kami memastikan tim yang tepat meninjau kiriman Anda.
  3. ID Iklan: Membantu kami memahami apakah aplikasi menggunakan ID iklan atau tidak.
  4. Kredensial Pengujian (Detail login): Jika ada bagian aplikasi yang dibatasi berdasarkan detail login, langganan, lokasi, atau bentuk autentikasi lainnya, berikan petunjuk cara mengaksesnya.
  5. Kebijakan Privasi: Link ke kebijakan privasi aplikasi beserta detailnya.
  6. Audiens Target dan Konten: Anda harus memberi tahu kami kelompok usia target aplikasi, dan informasi lainnya tentang konten aplikasi tersebut. Hal ini membantu memastikan bahwa aplikasi yang didesain untuk anak-anak terjamin aman dan sesuai.
  7. Iklan: Anda harus memberi tahu kami apakah aplikasi berisi iklan atau tidak.

Wajib Bersyarat:

  1. Aplikasi Pemerintah: Beri tahu kami apakah aplikasi akan digunakan oleh berbagai tingkat pemerintah. Pemerintah dalam hal ini termasuk pemerintah pusat, negara bagian, dan kota, serta otoritas setempat. Hal ini membantu kami untuk memastikan tim yang tepat meninjau kiriman Anda. Jika pernyataan ini tidak diselesaikan, aplikasi akan dianggap bukan aplikasi pemerintah.
  2. Standar Keselamatan Anak: Diwajibkan untuk aplikasi dalam kategori "Sosial" atau "Kencan". Aplikasi dalam kategori sosial atau kencan harus memberikan standar keselamatan yang dipublikasikan dan informasi kontak untuk mematuhi kebijakan standar keselamatan anak kami.
  3. Aplikasi Berita dan Majalah: Diwajibkan untuk aplikasi dalam kategori "Berita dan Majalah". Tambahkan detail tentang aplikasi berita dan majalah untuk memberikan transparansi terkait entitas yang menaungi aplikasi tersebut.

Struktur Permintaan API

Pernyataan kebijakan diberikan dalam array policyDeclarations pada isi UpdateAppStoreHostedAppRequest. Setiap item dalam array ini adalah objek AppStoreAppPolicyDeclaration.

Objek AppStoreAppPolicyDeclaration:

  • declarationId (string, Wajib): ID unik untuk deklarasi kebijakan (misalnya POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • responses (Array PolicyResponse, Wajib): Daftar jawaban untuk pertanyaan dalam pernyataan tertentu tersebut.

Objek PolicyResponse:

  • questionId (string, Wajib): ID unik untuk pertanyaan tertentu yang dijawab (misalnya, POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • value (Wajib): Jawaban itu sendiri, yang dapat berupa salah satu jenis berikut:
    • booleanResponse: Untuk pertanyaan Ya atau Tidak.
      • value (boolean)
    • stringResponse: Untuk jawaban teks biasa, termasuk URL.
      • value (string)
    • singleChoiceResponse: Jika hanya satu opsi yang dapat dipilih dari daftar.
      • value (string): ID pilihan respons yang dipilih.
    • multipleChoiceResponse: Jika beberapa opsi dapat dipilih.
      • values (Array string): ID pilihan respons yang dipilih.
    • documentResponse: Untuk pertanyaan yang memerlukan upload dokumen. Lihat Menangani Upload Dokumen.
    • groupResponse: Untuk mengulang kumpulan pertanyaan bertingkat.
    • keyedGroupResponse: Untuk kumpulan pertanyaan bertingkat yang dikelompokkan menurut kunci tertentu.

Untuk contoh cuplikan deklarasi, lihat panduan mendetail.

Menangani Upload Dokumen

Beberapa pertanyaan kebijakan mengharuskan Anda memberikan dokumen pendukung (misalnya, lisensi untuk Fitur Keuangan). Dokumen tidak dapat disematkan langsung di UpdateAppStoreHostedAppRequest. Sebagai gantinya, Anda harus:

  1. Mengupload Dokumen: Gunakan endpoint UploadAppStoreAppPolicyDeclarationFile. Ini adalah permintaan upload media. fileType harus disetel ke DECLARATION_FILE_TYPE_DOCUMENT.

    • Endpoint: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • Respons upload yang berhasil akan menyertakan fileId.

  2. Merujuk ID Dokumen: Dalam PolicyResponse untuk pertanyaan dokumen, gunakan jenis documentResponse. Isi kolom documentId dengan fileId yang diperoleh dari langkah upload.

Objek PolicyDocumentResponse:

  • documentId (string, Wajib): ID yang ditampilkan dari endpoint UploadAppStoreAppPolicyDeclarationFile.
  • expiryDate (Tanggal, Opsional): Tanggal habis masa berlaku dokumen, jika berlaku.
  • nonExpiring (boolean, Opsional): Setel ke true jika dokumen tidak berakhir.

Contoh Respons Dokumen:

// 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. Mengontrol ketersediaan

Setelah Anda melakukan commit status aplikasi yang dihosting menggunakan UpdateAppStoreHostedApp, aplikasi akan otomatis diproses dan ditandai sebagai dipublikasikan secara default di Google Play untuk app store pihak ketiga.

Untuk mengontrol ketersediaan aplikasi setelah melakukan commit, panggil metode updateappstorehostedapppublishstatus untuk memperbarui statusnya:

  • Membatalkan Publikasi Aplikasi: Agar aplikasi yang dihosting tidak tersedia, tetapkan kolom publishState ke APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • Mempublikasikan Ulang Aplikasi: Untuk membuat aplikasi yang sebelumnya tidak dipublikasikan tersedia lagi tanpa mengubah listingan atau mengupload ulang aset, tetapkan kolom publishState ke APP_STORE_APP_PUBLISH_STATE_PUBLISHED.