Руководство разработчика по API для проверки приложений в App Store

API App Store Review позволяет сторонним магазинам приложений, зарегистрированным в Google Play через программу Third-party app store on Play, предоставлять необходимую информацию о приложениях, размещенных в их магазине. Это включает метаданные приложений, описания, APK-файлы и заявления о соответствии политике.

Полный список конечных точек, методов и схем ресурсов см. в справочнике API для отзывов в App Store .

Прежде чем начать

Прежде чем отправлять запросы к API отзывов в App Store, необходимо выполнить основное руководство по началу работы , чтобы настроить доступ к API, учетные данные сервиса и проект Google Cloud. API отзывов в App Store ожидает не более 300 запросов в минуту на один магазин приложений.

Проектирование и архитектура API

API для отзывов в App Store работает по принципу атомарных снимков . Вместо транзакционных сессий вы загружаете файлы по отдельности, а затем фиксируете все состояние одним атомарным вызовом:

  1. Вы загружаете отдельные файлы и ресурсы (APK-файлы, изображения и файлы политик) в отдельных прямых запросах.
  2. Вы кэшируете возвращаемые идентификаторы для этих файлов.
  3. Для атомарной фиксации всего состояния размещенного приложения необходимо отправить единственный, заключительный запрос UpdateAppStoreHostedApp .

1. Регистрация

Для регистрации размещенного приложения вызовите метод createappstorehostedapp , указав имя пакета приложения и имя пакета вашего магазина. Подробную информацию о схемах запроса и ответа см. в справочнике API.

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

Декларации политики

При отправке или обновлении информации о приложении с помощью 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 для стороннего магазина приложений.

Чтобы контролировать доступность приложения после его добавления в репозиторий, вызовите метод ` updateappstorehostedapppublishstatus для обновления его состояния:

  • Отмена публикации приложения : Чтобы сделать размещенное приложение недоступным, установите поле publishState в значение APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED .
  • Повторная публикация приложения : Чтобы сделать ранее неопубликованное приложение снова доступным без изменения описаний или повторной загрузки ресурсов, установите поле publishState в APP_STORE_APP_PUBLISH_STATE_PUBLISHED .