دليل المطوّرين لواجهة برمجة التطبيقات App Store Review API

تسمح واجهة برمجة التطبيقات App Store Review API لمتاجر التطبيقات الخارجية المسجّلة على Google Play من خلال برنامج "متجر التطبيقات الخارجية على Play" بتوفير التفاصيل المطلوبة للتطبيقات المستضافة على متجرها. ويشمل ذلك البيانات الوصفية للتطبيق وبطاقات بياناته وملفات APK الثنائية وبيانات الامتثال للسياسات.

للحصول على قائمة كاملة بنقاط النهاية والطُرق ومخططات الموارد، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات App Store Review API.

قبل البدء

عليك إكمال دليل البدء الرئيسي Getting Started Guide لإعداد إذن الوصول إلى واجهة برمجة التطبيقات وبيانات اعتماد الخدمة ومشروع على السحابة الإلكترونية Google Cloud قبل أن تتمكّن من إجراء طلبات إلى واجهة برمجة التطبيقات App Store Review API. تتوقّع واجهة برمجة التطبيقات App Store Review API ما لا يزيد عن 300 طلب في الدقيقة لكل متجر تطبيقات.

تصميم واجهة برمجة التطبيقات وبنيتها

تعمل واجهة برمجة التطبيقات App Store Review API على نمط اللقطة الذرية. بدلاً من استخدام الجلسات المستندة إلى المعاملات، يمكنك تحميل الملفات بشكل فردي ثم إرسال الحالة الكاملة في طلب واحد ذري:

  1. يمكنك تحميل الملفات ومواد العرض الفردية (ملفات APK والصور وملفات السياسات) في طلبات منفصلة ومباشرة.
  2. يمكنك تخزين المعرّفات التي يتم عرضها لهذه الملفات مؤقتًا.
  3. يمكنك إرسال طلب نهائي واحد UpdateAppStoreHostedApp لإرسال حالة التطبيق المستضاف بالكامل بشكل ذري.

1. التسجيل

لتسجيل تطبيق مستضاف، عليك استدعاء طريقة createappstorehostedapp مع تحديد اسم حزمة التطبيق واسم حزمة متجرك. للاطّلاع على تفاصيل مخططات الطلبات والاستجابات، يُرجى مراجعة مرجع واجهة برمجة التطبيقات.

2. تحميل الملفات الثنائية ومواد العرض

بعد تسجيل التطبيق المستضاف، عليك تحميل مواد عرضه باستخدام نقاط نهاية التحميل المتخصّصة:

  • ملفات APK: جميع ملفات APK الثنائية التي يتم توزيعها حاليًا للتطبيق (باستخدام uploadapk).
  • الصور: مواد عرض الصور، مثل رمز التطبيق ولقطات الشاشة (باستخدام uploadimage).
  • السياسات: (إذا كان ذلك منطبقًا) المستندات ذات الصلة بالسياسات (باستخدام uploadappstoreapppolicydeclarationfile)

تخزين مواد العرض مؤقتًا وإعادة استخدامها

لتحسين النطاق الترددي والأداء، لا تعِد تحميل مواد العرض المتطابقة. تكون جميع الرموز المميّزة التي يتم عرضها apkId وimageId وfileId دائمة. يمكنك تخزين هذه المعرّفات مؤقتًا في قاعدة البيانات الخلفية الخاصة بك وإعادة استخدامها في التعديلات اللاحقة للتطبيق المستضاف. على سبيل المثال، إذا كنت تعدّل وصف تطبيق مستضاف ولكن رمز التطبيق ولقطات الشاشة لم يتغيّرا، استخدِم الرموز المميّزة imageId المخزّنة مؤقتًا في طلب التعديل التالي.

3. التجميع والإرسال

بعد تحميل جميع مواد العرض بنجاح واسترداد المعرّفات الخاصة بها، عليك تجميع حالة التطبيق المستضاف الكاملة وإرسالها باستخدام الـ 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
  ]
}

بيانات السياسات

عند إرسال معلومات التطبيق أو تعديلها باستخدام واجهة برمجة التطبيقات، عليك تضمين أي بيانات سياسات مطلوبة.

متطلبات البيانات

البيانات التالية ضمن النطاق:

مطلوبة لجميع التطبيقات لتأكيد ما إذا كانت هناك بيانات إضافية مطلوبة:

  1. التطبيقات المتعلّقة بالصحة: يُرجى إعلامنا بالميزات المتعلّقة بالصحة في التطبيق لمساعدتنا في معرفة المتطلبات التي يجب أن يستوفيها التطبيق في سياسة التطبيقات المتعلّقة بالصحة.
  2. الميزات المالية: على مطوّري التطبيقات التي توفِّر ميزات مالية الالتزام باللوائح المفروضة في بعض البلدان أو المناطق. يُرجى إرسال تفاصيل دقيقة ومحدّثة عن الميزات المالية التي يوفّرها التطبيق لمساعدتنا في التأكّد من أنّ مراجعة التطبيق ستتم من خلال الفِرق المناسبة.
  3. المعرِّف الإعلاني: يُرجى مساعدتنا في معرفة ما إذا كان التطبيق يستخدم المعرِّف الإعلاني.
  4. بيانات اعتماد الاختبار (تفاصيل تسجيل الدخول): إذا كانت هناك قيود على الوصول إلى بعض الميزات استنادًا إلى تفاصيل تسجيل الدخول أو الاشتراكات أو الموقع الجغرافي أو غيرها من أشكال المصادقة، يجب توفير التعليمات اللازمة للوصول إلى هذه الميزات.
  5. سياسة الخصوصية: رابط إلى سياسة خصوصية التطبيق وتفاصيل عنها
  6. الجمهور المستهدَف والمحتوى: عليك إعلامنا بالفئة العمرية المستهدفة للتطبيق والمعلومات الأخرى الخاصة بمحتواه. يساعد ذلك على التأكّد من أنّ التطبيقات المصمَّمة للأطفال آمنة ومناسبة.
  7. الإعلانات: عليك إعلامنا بما إذا كان التطبيق يحتوي على إعلانات.

مطلوبة بشكل مشروط:

  1. التطبيقات الحكومية: يُرجى إعلامنا بما إذا كان التطبيق مخصَّصًا لأي جهة حكومية. ويشمل ذلك الحكومات الوطنية والهيئات الحكومية في الولايات والمدن والسلطات المحليّة. يساعدنا ذلك في ضمان خضوع التطبيق للمراجعة من قِبل الفِرق المناسبة. إذا لم يتم إكمال هذا البيان، سيتم اعتبار التطبيق غير حكومي.
  2. معايير سلامة الأطفال: مطلوبة للتطبيقات في فئتَي "التواصل الاجتماعي" أو "المواعدة" يجب أن تقدّم التطبيقات ضمن فئتَي "التواصل الاجتماعي" و"المواعدة" معايير السلامة المنشورة ومعلومات الاتصال للامتثال لـ سياسة معايير سلامة الأطفال.
  3. تطبيقات الأخبار والمجلات: مطلوبة للتطبيقات في فئة "الأخبار والمجلات" يجب إضافة تفاصيل عن تطبيق الأخبار والمجلات لضمان الشفافية بخصوص الجهات التي تدير تطبيقك.

بنية طلب واجهة برمجة التطبيقات

يتم تقديم بيانات السياسات ضمن مصفوفة 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 لمتجر التطبيقات الخارجية.

للتحكّم في مدى توفّر التطبيق بعد إرساله، عليك استدعاء طريقة updateappstorehostedapppublishstatus لتعديل حالته:

  • إلغاء نشر تطبيق: لجعل التطبيق المستضاف غير متاح، اضبط الحقل publishState على APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • إعادة نشر تطبيق: لجعل تطبيق غير منشور سابقًا متاحًا مرة أخرى بدون تعديل بطاقات البيانات أو إعادة تحميل مواد العرض، اضبط الـ publishState على APP_STORE_APP_PUBLISH_STATE_PUBLISHED.