Guía para desarrolladores sobre la API de App Store Review

La API de App Store Review permite que las tiendas de apps de terceros registradas en Google Play a través del Programa de tiendas de apps de terceros en Play proporcionen los detalles requeridos para las apps que tienen alojadas. Esto incluye los metadatos de la app, las fichas, los objetos binarios del APK y las declaraciones de cumplimiento de políticas.

Para obtener una lista completa de los endpoints, los métodos y los esquemas de recursos, consulta la referencia de la API de App Store Review.

Antes de comenzar

Debes completar la Guía de introducción principal para configurar tu acceso a la API, las credenciales de servicio y el proyecto de Google Cloud antes de poder realizar llamadas a la API de App Store Review. La API de App Store Review espera un máximo de 300 solicitudes por minuto por tienda de aplicaciones.

Diseño y arquitectura de la API

La API de App Store Review funciona con un patrón de instantánea atómica. En lugar de usar sesiones por transacción, sube los archivos de forma individual y, luego, confirma el estado completo en una sola llamada atómica:

  1. Subes archivos y recursos individuales (APKs, imágenes y archivos de políticas) en llamadas directas independientes.
  2. Almacenas en caché los IDs devueltos para esos archivos.
  3. Envías una sola solicitud final de UpdateAppStoreHostedApp para confirmar de forma atómica todo el estado de la app alojada.

1. Registro

Para registrar una app alojada, llama al método createappstorehostedapp y especifica el nombre del paquete de la app y el nombre del paquete de tu tienda. Para obtener detalles sobre los esquemas de solicitud y respuesta, consulta la referencia de la API.

2. Cargas de recursos y objetos binarios

Una vez que se registre la app alojada, debes subir sus recursos con los endpoints de carga especializados:

  • APKs: Son todos los objetos binarios de APK de la app que se distribuyen de forma activa (con uploadapk).
  • Imágenes: Son recursos de imagen, como el ícono de la app y las capturas de pantalla (con uploadimage).
  • Políticas (si corresponde): Es la documentación relacionada con las políticas (con uploadappstoreapppolicydeclarationfile).

Almacenamiento en caché y reutilización de recursos

Para optimizar el ancho de banda y el rendimiento, no vuelvas a subir recursos idénticos. Todos los tokens apkId, imageId y fileId devueltos son persistentes. Puedes almacenar en caché estos IDs en tu propia base de datos de backend y volver a usarlos en las actualizaciones posteriores de la app alojada. Por ejemplo, si actualizas la descripción de una app alojada, pero el ícono de la app y las capturas de pantalla no cambian, usa los tokens de imageId almacenados en caché en tu próxima llamada de actualización.

3. Organización y confirmación

Después de subir correctamente todos los recursos y de recuperar sus respectivos IDs, debes organizar el estado completo de la app alojada y confirmarlo con el método updateappstorehostedapp. Este método acepta una representación completa y atómica de los detalles de la app alojada, las fichas de Play Store localizadas, los conjuntos de APKs activos y las declaraciones de seguridad.

Esta llamada reemplaza cualquier estado activo anterior por el nuevo estado que se describe en la solicitud.

Ejemplo de cuerpo de la solicitud

A continuación, se muestra un cuerpo de solicitud en formato JSON realista y válido sintácticamente que ilustra todos los elementos clave:

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

Declaraciones de políticas

Cuando envíes o actualices la información de la app con la API, debes incluir las declaraciones de políticas obligatorias.

Requisitos de declaraciones

Las siguientes declaraciones están dentro del alcance:

Obligatorio para todas las apps (para confirmar si se necesitan declaraciones adicionales):

  1. Apps de salud: Indícanos qué funciones de salud usa la app para ayudarnos a comprender qué requisitos de la política sobre Aplicaciones de salud debe cumplir.
  2. Funciones financieras: Es posible que las apps que proporcionan funciones financieras deban cumplir con ciertas reglamentaciones en algunos países o regiones. Envía detalles precisos y actualizados de las funciones financieras de la app para ayudarnos a garantizar que los equipos adecuados revisen la solicitud.
  3. ID de publicidad: Ayúdanos a comprender si la app usa un ID de publicidad.
  4. Credenciales de prueba (detalles de acceso): Si alguna parte de la app está restringida en función de detalles de acceso, membresías, ubicación o cualquier otra forma de autenticación, proporciona instrucciones sobre cómo acceder a ella.
  5. Política de privacidad: Proporciona detalles sobre la política de privacidad de la app y un vínculo a ella.
  6. Público objetivo y contenido: Debes indicarnos la edad de los usuarios objetivo de la app y más información sobre el contenido que incluye. De esta manera, nos aseguramos de que las apps diseñadas para niños sean seguras y adecuadas.
  7. Anuncios: Debes indicarnos si la app contiene anuncios.

Condicionalmente obligatorio:

  1. Apps gubernamentales: Indícanos si la app se diseñó para que la use alguna organización gubernamental. Esto incluye Gobiernos nacionales, estatales y municipales, y autoridades locales. Esto nos ayuda a asegurarnos de que los equipos adecuados revisen el envío. Si no se completa esta declaración, se considerará que la app no es gubernamental.
  2. Estándares de la seguridad de los niños: Se requieren para las apps de las categorías "Social" o "De citas". Las apps sociales o de citas deben proporcionar estándares de seguridad publicados y datos de contacto para cumplir con nuestra política de Estándares de la Seguridad de los Niños.
  3. Apps de noticias y revistas: Se requieren para las apps de la categoría "Noticias y revistas". Agrega detalles sobre la app de noticias y revistas para brindar transparencia sobre las entidades que la respaldan.

Estructura de la solicitud a la API

Las declaraciones de políticas se proporcionan dentro del array policyDeclarations en el cuerpo de UpdateAppStoreHostedAppRequest. Cada elemento de este array es un objeto AppStoreAppPolicyDeclaration.

Objeto AppStoreAppPolicyDeclaration:

  • declarationId (cadena, obligatorio): Es el identificador único de la declaración de política (p. ej., POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • responses (array de PolicyResponse, obligatorio): Es una lista de respuestas a las preguntas de esa declaración específica.

Objeto PolicyResponse:

  • questionId (cadena, obligatorio): Es el identificador único de la pregunta específica que se responde (p. ej., POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • value (obligatorio): Es la respuesta en sí, que puede ser de uno de los siguientes tipos:
    • booleanResponse: Para preguntas del tipo sí o no
      • value (booleano)
    • stringResponse: Para respuestas de texto sin formato, incluidas las URLs
      • value (cadena)
    • singleChoiceResponse: Cuando solo se puede seleccionar una opción de una lista
      • value (cadena): Es el ID de la opción de respuesta elegida
    • multipleChoiceResponse: Cuando se pueden seleccionar múltiples opciones
      • values (array de cadena): Son los IDs de las opciones de respuesta elegidas
    • documentResponse: Para preguntas que requieren la carga de un documento; consulta Cómo controlar las cargas de documentos
    • groupResponse: Para conjuntos repetidos de preguntas anidadas
    • keyedGroupResponse: Para conjuntos de preguntas anidadas agrupadas por una clave específica

Para ver ejemplos de fragmentos para la declaración, consulta la guía detallada.

Cómo controlar las cargas de documentos

Algunas preguntas sobre políticas requieren que proporciones documentos complementarios (p. ej., licencias para las funciones financieras). Los documentos no se pueden incorporar directamente en UpdateAppStoreHostedAppRequest. En su lugar, debes hacer lo siguiente:

  1. Sube el documento: Usa el endpoint UploadAppStoreAppPolicyDeclarationFile. Esta es una solicitud de carga de contenido multimedia. El valor de fileType debe establecerse en DECLARATION_FILE_TYPE_DOCUMENT.

    • Endpoint: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • Las respuestas de carga exitosa incluirán un fileId.

  2. Haz referencia al ID del documento: En el campo PolicyResponse de la pregunta del documento, usa el tipo documentResponse. Completa el campo documentId con el fileId que obtuviste en el paso de carga.

Objeto PolicyDocumentResponse:

  • documentId (cadena, obligatorio): Es el ID que se devuelve del endpoint UploadAppStoreAppPolicyDeclarationFile.
  • expiryDate (fecha, opcional): Es la fecha de vencimiento del documento, si corresponde.
  • nonExpiring (booleano, opcional): Se establece en true si el documento no vence.

Ejemplo de respuesta de documento:

// 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. Cómo controlar la disponibilidad

Una vez que confirmes el estado de la app alojada con UpdateAppStoreHostedApp, Google Play procesará automáticamente la app y la marcará como publicada de forma predeterminada en la tienda de apps de terceros.

Para controlar la disponibilidad de la app después de que se haya confirmado, llama al método updateappstorehostedapppublishstatus para actualizar su estado:

  • Cómo anular la publicación de una app: Para que la app alojada no esté disponible, establece el campo publishState en APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • Cómo volver a publicar una app: Para que una app que se había dejado de publicar vuelva a estar disponible sin modificar las fichas ni volver a subir los recursos, establece el campo publishState en APP_STORE_APP_PUBLISH_STATE_PUBLISHED.