Guia para desenvolvedores da API App Store Review

A API App Store Review permite que app stores de terceiros registradas no Google Play pelo programa para app stores de terceiros no Google Play forneçam os detalhes necessários para apps hospedados na loja. Isso inclui metadados do app, páginas de detalhes, binários de APK e declarações de conformidade com a política.

Confira uma lista completa de endpoints, métodos e esquemas de recursos na Referência da API App Store Review.

Antes de começar

Você precisa concluir o Guia de iniciação principal para configurar o acesso à API, as credenciais de serviço e o projeto na nuvem do Google Cloud antes de fazer chamadas para a API App Store Review. A API App Store Review espera no máximo 300 solicitações por minuto e por app store.

Design e arquitetura da API

A API App Store Review opera em um padrão de snapshot atômico. Em vez de usar sessões transacionais, faça upload dos arquivos individualmente e confirme o estado total em uma única chamada atômica:

  1. Você faz upload de arquivos e recursos individuais (APKs, imagens e arquivos de política) em chamadas diretas separadas.
  2. Você armazena em cache os IDs retornados para esses arquivos.
  3. Você envia uma única solicitação UpdateAppStoreHostedApp final para confirmar atomicamente todo o estado do app hospedado.

1. Registro

Para registrar um app hospedado, chame o método createappstorehostedapp especificando o nome do pacote do app e o nome do pacote da sua loja. Para detalhes sobre os esquemas de solicitação e resposta, consulte a Referência da API.

2. Uploads de binários e recursos

Depois que o app hospedado for registrado, faça upload dos recursos dele usando os endpoints de upload especializados:

  • APKs: todos os binários de APK do app distribuídos ativamente (usando uploadapk).
  • Imagens: recursos de imagem, como o ícone do app e capturas de tela (usando uploadimage).
  • Políticas: (se relevante) documentação relacionada à política (usando uploadappstoreapppolicydeclarationfile).

Armazenamento em cache e reutilização de recursos

Para otimizar a largura de banda e o desempenho, não faça novo upload de recursos idênticos. Todos os tokens apkId, imageId e fileId retornados são persistentes. É possível armazenar em cache esses IDs no seu próprio banco de dados de back-end e reutilizá-los em atualizações subsequentes de apps hospedados. Por exemplo, se você estiver atualizando a descrição de um app hospedado, mas o ícone do app e as capturas de tela permanecerem inalterados, use os tokens imageId em cache na próxima chamada de atualização.

3. Reunir e confirmar

Depois de fazer upload de todos os recursos e recuperar os respectivos IDs, você precisa reunir o estado completo do app hospedado e confirmar usando o método updateappstorehostedapp. Esse método aceita uma representação completa e atômica dos detalhes do app hospedado, das páginas de detalhes do app localizadas, dos conjuntos de APKs ativos e das declarações de segurança.

Essa chamada substitui qualquer estado ativo anterior pelo novo estado descrito na solicitação.

Exemplo de corpo da solicitação

Confira a seguir um corpo de solicitação JSON realista e sintaticamente válido que ilustra todos os elementos principais:

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

Declarações de política

Ao enviar ou atualizar informações do app usando a API, inclua todas as declarações de política necessárias.

Requisitos da declaração

As declarações a seguir estão no escopo:

Obrigatório para todos os apps confirmarem se são necessárias declarações adicionais:

  1. Apps de saúde:: informe quais recursos de saúde o app usa para nos ajudar a entender quais requisitos da política de apps de saúde ele precisa atender.
  2. Recursos financeiros: os apps que oferecem recursos financeiros talvez precisem obedecer a determinados regulamentos em alguns países ou regiões. Envie dados precisos e atualizados sobre os recursos financeiros do app para que as equipes certas analisem seus detalhes.
  3. ID de publicidade: queremos saber se o app usa um ID de publicidade.
  4. Credenciais de teste (detalhes de login): se alguma parte do app for restrita com base em detalhes de login, assinaturas, local ou outras formas de autenticação, forneça instruções sobre como acessá-las.
  5. Política de Privacidade: um link para a Política de Privacidade do app e detalhes sobre ela.
  6. Público-alvo e conteúdo: é necessário informar a faixa etária do público-alvo do app e outras informações sobre o conteúdo. Isso nos ajuda a garantir que apps feitos para crianças sejam seguros e adequados a elas.
  7. Anúncios: é necessário informar se o app tem anúncios.

Obrigatório sob certas condições:

  1. Apps governamentais: informe se o app é para uso de um governo de qualquer tipo. Isso inclui governos nacionais, estaduais e municipais e autoridades locais. Assim garantimos a análise das informações pelas equipes certas. Se esta declaração não for preenchida, o app será considerado um app não governamental.
  2. Padrões de segurança infantil: obrigatórios para apps nas categorias "Social" ou "Encontros". Os apps nas categorias Social ou Encontros precisam fornecer padrões de segurança publicados e dados de contato para obedecer à nossa Política de padrões de segurança infantil
  3. Apps de notícias e revistas: obrigatório para apps na categoria "Notícias e revistas". Adicione detalhes sobre o app de notícias e revistas para oferecer mais transparência em relação às entidades por trás dele.

Estrutura da solicitação de API

As declarações de política são fornecidas na matriz policyDeclarations no corpo do UpdateAppStoreHostedAppRequest. Cada item nessa matriz é um objeto AppStoreAppPolicyDeclaration.

Objeto AppStoreAppPolicyDeclaration:

  • declarationId (string, obrigatório): o identificador exclusivo da declaração de política (por exemplo, POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • responses (matriz de PolicyResponse, obrigatório): uma lista de respostas às perguntas nessa declaração específica.

Objeto PolicyResponse:

  • questionId (string, obrigatório): o identificador exclusivo da pergunta específica que está sendo respondida (por exemplo, POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • value (obrigatório): a resposta em si, que pode ser um dos seguintes tipos:
    • booleanResponse: para perguntas com respostas Sim ou Não.
      • value (booleano)
    • stringResponse: para respostas em texto simples, incluindo URLs.
      • value (string)
    • singleChoiceResponse: quando apenas uma opção pode ser selecionada em uma lista.
      • value (string): o ID da opção de resposta escolhida.
    • multipleChoiceResponse: quando várias opções podem ser selecionadas.
      • values (matriz de strings): os IDs das opções de resposta escolhidas.
    • documentResponse: para perguntas que exigem o envio de um documento. Consulte Como processar uploads de documentos.
    • groupResponse: para conjuntos repetidos de perguntas aninhadas.
    • keyedGroupResponse: para conjuntos de perguntas aninhadas agrupadas por uma chave específica.

Para exemplos de snippets de declaração, consulte o guia detalhado.

Como processar uploads de documentos

Algumas perguntas sobre políticas exigem que você forneça documentos de apoio, como licenças para recursos financeiros. Não é possível incorporar documentos diretamente no UpdateAppStoreHostedAppRequest. Em vez disso, você precisa:

  1. Fazer upload do documento: use o endpoint UploadAppStoreAppPolicyDeclarationFile. Esta é uma solicitação de upload de mídia. O fileType precisa ser definido como DECLARATION_FILE_TYPE_DOCUMENT.

    • Endpoint: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • As respostas de upload bem-sucedido incluem um fileId.

  2. Referenciar o ID do documento: no PolicyResponse da pergunta sobre o documento, use o tipo documentResponse. Preencha o campo documentId com o fileId obtido na etapa de upload.

Objeto PolicyDocumentResponse:

  • documentId (string, obrigatório): o ID retornado do endpoint UploadAppStoreAppPolicyDeclarationFile.
  • expiryDate (data, opcional): a data de validade do documento, se aplicável.
  • nonExpiring (booleano, opcional): defina como true se o documento não expirar.

Exemplo de resposta do 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. Como controlar a disponibilidade

Depois que você confirmar o estado do app hospedado usando UpdateAppStoreHostedApp, o app será processado automaticamente e marcado como publicado por padrão no Google Play para a app store de terceiros.

Para controlar a disponibilidade do app depois que ele for confirmado, chame o método updateappstorehostedapppublishstatus para atualizar o estado dele:

  • Cancelar a publicação de um app: para tornar o app hospedado indisponível, defina o campo publishState como APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • Republicar um app: para disponibilizar novamente um app que não estava publicado sem modificar as páginas de detalhes do app ou fazer upload de recursos, defina o campo publishState como APP_STORE_APP_PUBLISH_STATE_PUBLISHED.