คู่มือนักพัฒนาซอฟต์แวร์ App Store Review API

App Store Review API ช่วยให้ App Store ของบุคคลที่สามที่ลงทะเบียนใน Google Play ผ่านโปรแกรม App Store ของบุคคลที่สามใน Google Play สามารถระบุรายละเอียดที่จำเป็นสำหรับแอปที่โฮสต์ใน Store ของตนได้ ซึ่งรวมถึงข้อมูลเมตาของแอป ข้อมูลสินค้าใน Store, ไบนารี APK และการประกาศการปฏิบัติตามนโยบาย

ดูรายการปลายทาง เมธอด และสคีมาทรัพยากรทั้งหมดได้ที่ เอกสารอ้างอิง App Store Review API

ก่อนที่คุณจะเริ่มต้น

คุณต้องทำ คู่มือเริ่มต้นใช้งานหลักให้เสร็จสมบูรณ์เพื่อตั้งค่าการเข้าถึง API , ข้อมูลเข้าสู่ระบบบริการ และโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google Cloud ก่อนที่จะเรียก App Store Review API ได้ App Store Review API คาดว่าจะได้รับคำขอไม่เกิน 300 รายการต่อนาทีต่อ App Store

การออกแบบและสถาปัตยกรรมของ API

App Store Review API ทำงานตามรูปแบบสแนปช็อตแบบอะตอมมิก โดยคุณจะอัปโหลดไฟล์ทีละไฟล์ แล้วคอมมิตสถานะที่สมบูรณ์ในคำขอแบบอะตอมมิกรายการเดียวแทนการใช้เซสชันการทำธุรกรรม

  1. คุณอัปโหลดไฟล์และชิ้นงานแต่ละรายการ (APK, รูปภาพ และไฟล์นโยบาย) ในคำขอแยกกันโดยตรง
  2. คุณแคชรหัสที่ส่งคืนสำหรับไฟล์เหล่านั้น
  3. คุณส่งคำขอรายการเดียวสุดท้าย UpdateAppStoreHostedApp เพื่อคอมมิตสถานะแอปที่โฮสต์ทั้งหมดแบบอะตอมมิก

1. การลงทะเบียน

หากต้องการลงทะเบียนแอปที่โฮสต์ ให้เรียก createappstorehostedapp เมธอด โดยระบุชื่อแพ็กเกจของแอปและชื่อแพ็กเกจของ Store ดูรายละเอียดเกี่ยวกับสคีมาคำขอและการตอบกลับได้ในเอกสารอ้างอิง API

2. การอัปโหลดไบนารีและชิ้นงาน

เมื่อลงทะเบียนแอปที่โฮสต์แล้ว คุณต้องอัปโหลดชิ้นงานของแอปโดยใช้ปลายทางการอัปโหลดเฉพาะดังนี้

  • APK: ไบนารี APK ทั้งหมดของแอปที่เผยแพร่อยู่ (ใช้ uploadapk)
  • รูปภาพ: ชิ้นงานรูปภาพ เช่น ไอคอนแอปและภาพหน้าจอ (ใช้ uploadimage)
  • นโยบาย: (หากเกี่ยวข้อง) เอกสารประกอบที่เกี่ยวข้องกับนโยบาย (ใช้ uploadappstoreapppolicydeclarationfile)

การแคชและการนำชิ้นงานกลับมาใช้ซ้ำ

อย่าอัปโหลดชิ้นงานที่เหมือนกันซ้ำ เพื่อเพิ่มประสิทธิภาพแบนด์วิดท์และประสิทธิภาพ โทเค็น apkId, imageId และ fileId ทั้งหมดที่ส่งคืนจะยังคงอยู่ คุณสามารถแคชรหัสเหล่านี้ในฐานข้อมูลแบ็กเอนด์ของคุณเองและนำกลับมาใช้ซ้ำในการอัปเดตแอปที่โฮสต์ในภายหลังได้ เช่น หากคุณอัปเดตคำอธิบายของแอปที่โฮสต์ แต่ไอคอนแอปและภาพหน้าจอยังคงเหมือนเดิม ให้ใช้โทเค็น imageId ที่แคชไว้ในการเรียกอัปเดตครั้งถัดไป

3. ประกอบและคอมมิต

หลังจากอัปโหลดชิ้นงานทั้งหมดและดึงข้อมูลรหัสที่เกี่ยวข้องได้สำเร็จแล้ว คุณ ต้องประกอบสถานะแอปที่โฮสต์ทั้งหมดและคอมมิตโดยใช้ updateappstorehostedapp เมธอด เมธอดนี้ยอมรับการแสดงรายละเอียดแอปที่โฮสต์ ข้อมูลสินค้าใน Store ที่แปลเป็นภาษาท้องถิ่น ชุด 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. รหัสโฆษณา: ช่วยให้เราเข้าใจว่าแอปใช้รหัสโฆษณาหรือไม่
  4. ข้อมูลเข้าสู่ระบบสำหรับการทดสอบ (รายละเอียดการลงชื่อเข้าใช้): หากมีการจำกัดส่วนใดส่วนหนึ่งของแอปตามรายละเอียดการลงชื่อเข้าใช้ การเป็นสมาชิก สถานที่ หรือการตรวจสอบสิทธิ์รูปแบบอื่นๆ โปรดระบุวิธีการเข้าถึงส่วนดังกล่าว
  5. นโยบายความเป็นส่วนตัว: ลิงก์ไปยังนโยบายความเป็นส่วนตัวของแอปและรายละเอียดเกี่ยวกับนโยบายดังกล่าว
  6. กลุ่มเป้าหมายและเนื้อหา: คุณต้องแจ้งให้เราทราบถึงกลุ่มอายุเป้าหมายของแอปและข้อมูลอื่นๆ เกี่ยวกับเนื้อหาของแอป ซึ่งจะช่วยให้แน่ใจว่าแอปที่ออกแบบมาสำหรับเด็กนั้นมีความปลอดภัยและเหมาะสม
  7. โฆษณา: คุณต้องแจ้งให้เราทราบว่าแอปมีโฆษณาหรือไม่

ต้องระบุตามเงื่อนไข

  1. แอปของรัฐบาล: แจ้งให้เราทราบหากแอปของคุณเป็นแอปสําหรับใช้งานโดยรัฐบาลไม่ว่าหน่วยงานใด ซึ่งรวมถึงรัฐบาลแห่งชาติ รัฐบาลระดับรัฐและเมือง และหน่วยงานส่วนท้องถิ่น การทำเช่นนี้จะช่วยให้เรามั่นใจว่าทีมที่เหมาะสมจะเป็นผู้ตรวจสอบข้อมูลที่คุณส่งเข้ามา หากการประกาศนี้ไม่เสร็จสมบูรณ์ ระบบจะถือว่าแอปไม่ใช่แอปของรัฐบาล
  2. มาตรฐานความปลอดภัยของเด็ก: ต้องระบุสำหรับแอปในหมวดหมู่ "โซเชียล" หรือ "การหาคู่" แอปในหมวดหมู่โซเชียลหรือการหาคู่ต้องระบุมาตรฐานความปลอดภัยที่เผยแพร่ และข้อมูลติดต่อเพื่อให้เป็นไปตามนโยบายเกี่ยวกับมาตรฐานความปลอดภัยของเด็ก
  3. แอปข่าวและแอปนิตยสาร: ต้องระบุสำหรับแอปในหมวดหมู่ "ข่าวและนิตยสาร" เพิ่มรายละเอียดเกี่ยวกับแอปข่าวและแอปนิตยสารเพื่อให้มีความโปร่งใสเกี่ยวกับผู้ที่อยู่เบื้องหลังแอป

โครงสร้างคำขอ API

การประกาศนโยบายจะอยู่ในอาร์เรย์ policyDeclarations ใน เนื้อความของ UpdateAppStoreHostedAppRequest โดยแต่ละรายการในอาร์เรย์นี้จะเป็นออบเจ็กต์ AppStoreAppPolicyDeclaration

ออบเจ็กต์ AppStoreAppPolicyDeclaration

  • declarationId (สตริง, ต้องระบุ): ตัวระบุที่ไม่ซ้ำกันสำหรับการประกาศนโยบาย (เช่น POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT)
  • responses (อาร์เรย์ของ PolicyResponse, ต้องระบุ): รายการคำตอบสำหรับคำถามในการประกาศนั้นๆ

ออบเจ็กต์ PolicyResponse

  • questionId (สตริง, ต้องระบุ): ตัวระบุที่ไม่ซ้ำกันสำหรับคำถามเฉพาะที่กำลังตอบ (เช่น POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS)
  • value (ต้องระบุ): คำตอบเอง ซึ่งอาจเป็นประเภทใดประเภทหนึ่งต่อไปนี้
    • booleanResponse: สำหรับคำถามแบบใช่หรือไม่ใช่
      • value (บูลีน)
    • stringResponse: สำหรับคำตอบที่เป็นข้อความธรรมดา รวมถึง URL
      • value (สตริง)
    • singleChoiceResponse: เมื่อเลือกได้เพียงตัวเลือกเดียวจากรายการ
      • value (สตริง): รหัสของตัวเลือกคำตอบที่เลือก
    • multipleChoiceResponse: เมื่อเลือกได้หลายตัวเลือก
      • values (อาร์เรย์ของสตริง): รหัสของตัวเลือกคำตอบที่เลือก
    • documentResponse: สำหรับคำถามที่ต้องอัปโหลดเอกสาร ดู การจัดการการอัปโหลดเอกสาร
    • groupResponse: สำหรับชุดคำถามที่ซ้อนกันซึ่งทำซ้ำ
    • keyedGroupResponse: สำหรับชุดคำถามที่ซ้อนกันซึ่งจัดกลุ่มตามคีย์ที่เฉพาะเจาะจง

ดูตัวอย่างข้อมูลโค้ดสำหรับการประกาศได้ใน คู่มือโดยละเอียด

การจัดการการอัปโหลดเอกสาร

คำถามเกี่ยวกับนโยบายบางข้อกำหนดให้คุณต้องส่งเอกสารประกอบ (เช่น ใบอนุญาตสำหรับฟีเจอร์ทางการเงิน) คุณไม่สามารถฝังเอกสารลงใน UpdateAppStoreHostedAppRequestได้โดยตรง แต่ต้องดำเนินการดังนี้

  1. อัปโหลดเอกสาร: ใช้ UploadAppStoreAppPolicyDeclarationFile ปลายทาง ซึ่งเป็นคำขออัปโหลดสื่อ คุณควรตั้งค่า fileType เป็น DECLARATION_FILE_TYPE_DOCUMENT

    • ปลายทาง: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • การตอบกลับการอัปโหลดที่สำเร็จจะมี fileId

  2. อ้างอิงรหัสเอกสาร: ใน PolicyResponse สำหรับคำถามเกี่ยวกับเอกสาร ให้ใช้ประเภท documentResponse ป้อนข้อมูลในช่อง documentId ด้วย fileId ที่ได้รับจากขั้นตอนการอัปโหลด

ออบเจ็กต์ PolicyDocumentResponse

  • documentId (สตริง, ต้องระบุ): รหัสที่ส่งคืนจาก UploadAppStoreAppPolicyDeclarationFile ปลายทาง
  • 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 สำหรับ App Store ของบุคคลที่สาม

หากต้องการควบคุมความพร้อมใช้งานของแอปหลังจากคอมมิตแล้ว ให้เรียก updateappstorehostedapppublishstatus เมธอดเพื่ออัปเดตสถานะของแอป

  • การยกเลิกการเผยแพร่แอป: หากต้องการทำให้แอปที่โฮสต์ไม่พร้อมใช้งาน ให้ตั้งค่า publishState ช่องเป็น APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED
  • การเผยแพร่แอปอีกครั้ง: หากต้องการทำให้แอปที่เคยยกเลิกการเผยแพร่พร้อมใช้งาน อีกครั้งโดยไม่ต้องแก้ไขข้อมูลสินค้าใน Store หรืออัปโหลดชิ้นงานใหม่ ให้ตั้งค่า publishState เป็น APP_STORE_APP_PUBLISH_STATE_PUBLISHED