راهنمای توسعه‌دهندگان API برای بررسی اپ استور

API بررسی اپ استور به اپ استورهای شخص ثالث ثبت‌شده در گوگل پلی از طریق برنامه‌ی اپ استور شخص ثالث در پلی اجازه می‌دهد تا جزئیات مورد نیاز برای اپ‌های میزبانی‌شده در فروشگاه خود را ارائه دهند. این شامل فراداده‌های اپ، فهرست‌ها، فایل‌های باینری APK و اعلامیه‌های انطباق با سیاست‌ها می‌شود.

برای فهرست کاملی از نقاط پایانی، روش‌ها و طرحواره‌های منابع، به مرجع API نقد و بررسی اپ استور مراجعه کنید.

قبل از شروع

قبل از اینکه بتوانید با API بررسی اپ استور تماس برقرار کنید، باید راهنمای شروع به کار اصلی را برای تنظیم دسترسی به API، اعتبارنامه‌های سرویس و پروژه Google Cloud خود تکمیل کنید. API بررسی اپ استور حداکثر ۳۰۰ درخواست در دقیقه برای هر اپ استور را انتظار دارد.

طراحی و معماری API

API بررسی اپ استور بر اساس یک الگوی لحظه‌ای اتمیک عمل می‌کند. به جای استفاده از جلسات تراکنشی، فایل‌ها را به صورت جداگانه آپلود می‌کنید و سپس وضعیت کامل را در یک فراخوانی اتمیک ثبت می‌کنید:

  1. شما فایل‌ها و دارایی‌های تکی (APKها، تصاویر و فایل‌های سیاست) را در فراخوانی‌های جداگانه و مستقیم آپلود می‌کنید.
  2. شما شناسه‌های برگردانده شده برای آن فایل‌ها را ذخیره می‌کنید.
  3. شما یک درخواست نهایی و واحد UpdateAppStoreHostedApp ارسال می‌کنید تا کل وضعیت برنامه میزبانی‌شده به صورت خودکار ثبت شود.

۱. ثبت نام

برای ثبت یک برنامه میزبانی‌شده، متد createappstorehostedapp را فراخوانی کنید و نام بسته برنامه و نام بسته فروشگاه خود را مشخص کنید. برای جزئیات بیشتر در مورد طرحواره‌های درخواست و پاسخ، به مرجع API مراجعه کنید.

۲. آپلود فایل‌های باینری و فایل‌های باینری

پس از ثبت برنامه میزبانی شده، باید فایل‌های آن را با استفاده از نقاط پایانی آپلود تخصصی آپلود کنید:

  • APKها : همه فایل‌های باینری APK فعال توزیع‌شده از برنامه (با استفاده از uploadapk ).
  • تصاویر : تصاویر، مانند آیکون برنامه و اسکرین‌شات‌ها (با استفاده از uploadimage ).
  • سیاست‌ها : (در صورت لزوم) مستندات مربوط به سیاست‌ها (با استفاده از uploadappstoreapppolicydeclarationfile ).

ذخیره سازی و استفاده مجدد از دارایی ها

برای بهینه‌سازی پهنای باند و عملکرد، فایل‌های یکسان را دوباره آپلود نکنید . همه توکن‌های apkId ، imageId و fileId بازگردانده شده پایدار هستند. می‌توانید این شناسه‌ها را در پایگاه داده backend خود ذخیره کنید و در به‌روزرسانی‌های بعدی برنامه میزبانی شده از آنها استفاده مجدد کنید. به عنوان مثال، اگر توضیحات یک برنامه میزبانی شده را به‌روزرسانی می‌کنید اما آیکون و تصاویر برنامه بدون تغییر باقی می‌مانند، از توکن‌های imageId ذخیره شده در فراخوانی به‌روزرسانی بعدی خود استفاده کنید.

۳. اسمبل و کامیت کنید

پس از آپلود موفقیت‌آمیز تمام دارایی‌ها و بازیابی شناسه‌های مربوطه، باید وضعیت کامل برنامه میزبانی‌شده را جمع‌آوری کرده و با استفاده از متد 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. شناسه تبلیغاتی: به ما کمک کنید تا بفهمیم آیا برنامه از شناسه تبلیغاتی استفاده می‌کند یا خیر.
  4. آزمایش اطلاعات ورود (جزئیات ورود): اگر هر بخشی از برنامه بر اساس جزئیات ورود، عضویت‌ها، موقعیت مکانی یا سایر اشکال احراز هویت محدود شده است، دستورالعمل‌هایی در مورد نحوه دسترسی به آنها ارائه دهید.
  5. سیاست حفظ حریم خصوصی: پیوندی به سیاست حفظ حریم خصوصی برنامه و جزئیات آن.
  6. مخاطب هدف و محتوا: شما باید گروه سنی هدف برنامه و سایر اطلاعات مربوط به محتوای آن را به ما اطلاع دهید. این امر به ما کمک می‌کند تا از ایمن و مناسب بودن برنامه‌های طراحی شده برای کودکان اطمینان حاصل کنیم.
  7. تبلیغات: شما باید به ما اطلاع دهید که آیا برنامه حاوی تبلیغات است یا خیر.

به صورت مشروط لازم است:

  1. برنامه‌های دولتی: اگر برنامه برای استفاده توسط هر نوع دولتی است، به ما اطلاع دهید. این شامل دولت‌های ملی، ایالتی و شهری و مقامات محلی می‌شود. این به ما کمک می‌کند تا مطمئن شویم که تیم‌های مربوطه درخواست را بررسی می‌کنند. اگر این اظهارنامه تکمیل نشود، برنامه دولتی تلقی نخواهد شد.
  2. استانداردهای ایمنی کودک: برای برنامه‌هایی که در دسته‌های «اجتماعی» یا «دوست‌یابی» قرار دارند، الزامی است. برنامه‌های موجود در دسته‌های اجتماعی یا دوست‌یابی باید استانداردهای ایمنی منتشر شده و اطلاعات تماس را برای مطابقت با سیاست استانداردهای ایمنی کودک ما ارائه دهند.
  3. برنامه‌های خبری و مجله‌ای: برای برنامه‌های موجود در دسته «اخبار و مجلات» الزامی است. جزئیاتی درباره برنامه خبری و مجله‌ای اضافه کنید تا شفافیت در مورد نهادهای پشت برنامه ارائه شود.

ساختار درخواست API

اعلان‌های سیاست (Policy Declarations) در آرایه policyDeclarations در بدنه UpdateAppStoreHostedAppRequest ارائه می‌شوند. هر آیتم در این آرایه یک شیء AppStoreAppPolicyDeclaration است.

شیء AppStoreAppPolicyDeclaration :

  • declarationId (رشته، الزامی): شناسه منحصر به فرد برای اعلان سیاست (مثلاً، POLICY_DECLARATION_ID_FINANCE ، POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT ).
  • responses (Array of 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 (boolean، اختیاری): اگر سند منقضی نشود، روی 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
    }
  }
}

۴. کنترل در دسترس بودن

زمانی که وضعیت برنامه میزبانی‌شده را با استفاده از UpdateAppStoreHostedApp ثبت می‌کنید، برنامه به‌طور خودکار پردازش شده و به‌طور پیش‌فرض به‌عنوان منتشرشده در گوگل پلی برای فروشگاه برنامه شخص ثالث علامت‌گذاری می‌شود .

برای کنترل در دسترس بودن برنامه پس از ثبت، متد updateappstorehostedapppublishstatus را برای به‌روزرسانی وضعیت آن فراخوانی کنید:

  • لغو انتشار یک برنامه : برای اینکه برنامه میزبانی‌شده از دسترس خارج شود، فیلد publishState را روی APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED تنظیم کنید.
  • انتشار مجدد یک برنامه : برای اینکه یک برنامه منتشر نشده قبلی را بدون تغییر لیست‌ها یا آپلود مجدد دارایی‌ها، دوباره در دسترس قرار دهید، فیلد publishState را روی APP_STORE_APP_PUBLISH_STATE_PUBLISHED تنظیم کنید.