Registrar nomes de pacotes com a API do Android Developer Console

A API Android Developer Console é uma interface pública projetada para permitir que distribuidores de apps e desenvolvedores individuais registrem nomes de pacotes de forma programática no Android Developer Console.

Seus recursos de servidor para servidor como:

Distribuidor de apps Desenvolvedor individual
Registrar um nome de pacote - chave em nome do desenvolvedor que está publicando um app na loja. Registrar um nome de pacote com uma chave gerenciada pela loja. Comprovar a propriedade de uma chave associada a um nome de pacote. Registrar um nome de pacote: fundamental nos fluxos de trabalho de implantação contínua. Comprovar a propriedade de uma chave associada a um nome de pacote.

Antes de começar

Antes de começar, você precisa ter:

  1. Acesso administrativo a um projeto do Google Cloud.
  2. Noções básicas sobre:

Você também precisa conhecer estes termos:

Termo Definição
Conta de desenvolvedor Representa uma conta do Android Developer Console que pode ter um ou mais nomes de pacotes. Ele contém um estado de verificação (NOT_VERIFIED ou VERIFIED).
Nome do pacote Um nome de pacote Android específico (por exemplo, com.example.app) em uma conta de desenvolvedor, que pode ser associado a uma ou mais chaves. Ele contém um estado de registro (DRAFT, IN_REVIEW, REGISTERED ou PENDING_TRANSFER).
Chave O certificado/chave pública específica usada para assinar um nome de pacote do Android. Inclui o hash SHA-256 e o estado de registro atual (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED ou PENDING_TRANSFER).

Primeiros passos

Siga estas etapas para acessar a API Android Developer Console:

Criar um projeto do Google Cloud

  1. Crie uma conta do Google Cloud, caso ainda não tenha uma.
  2. Abra o Console do Google Cloud.
  3. Crie um projeto do Google Cloud.

Ativar a API no projeto do Google Cloud

  1. Abra o Console do Google Cloud.
  2. No menu de navegação (☰), selecione APIs e serviços > Biblioteca.
  3. Selecione o projeto na nuvem do Google Cloud em que você quer ativar a API no menu suspenso de projetos.
  4. Use a barra de pesquisa de APIs e serviços para selecionar a API Android Developer Console.
  5. Ative a API:
    1. Acesse a página de visão geral da API selecionando-a nos resultados da pesquisa.
    2. Clique no botão azul "Ativar". O Google Cloud ativa a API para o projeto selecionado, o que geralmente leva apenas um momento. Depois de ativá-lo, você pode começar a usá-lo.

Autenticar a API

Para fazer chamadas para a API Android Developer Console, é necessário autenticar suas solicitações usando o OAuth 2.0.

Autenticar com o OAuth 2.0

A API Android Developer Console exige autenticação OAuth 2.0 para autorizar o acesso aos recursos da conta de desenvolvedor e aos nomes de pacotes. Como os dados da conta de desenvolvedor estão vinculados à Conta do Google de um usuário, e não a um projeto do Google Cloud, as contas de serviço, a federação de identidade da carga de trabalho e as chaves de API não podem ser usadas para autenticar solicitações de API.

Escopo do OAuth 2.0

O escopo a seguir é obrigatório para todas as operações:

Escopo do OAuth 2.0 Descrição
https://www.googleapis.com/auth/androiddeveloperconsole Ver e gerenciar nomes de pacotes e dados nas suas contas do Android Developer Console

Implementar o fluxo do servidor da Web do OAuth 2.0

Para se integrar à API Android Developer Console, os aplicativos precisam usar o fluxo do servidor da Web OAuth 2.0. Dependendo do tipo de aplicativo e das necessidades de automação, é possível escolher entre duas estratégias principais de gerenciamento de credenciais:

Opção A (recomendada): acesso off-line / automatizado (CI/CD e integração de servidor) Opção B: acesso efêmero / interativo
Essa estratégia permite que processos automatizados (como pipelines de CI/CD) sejam executados em segundo plano sem intervenção humana:

Configuração única do consentimento do usuário:durante a configuração inicial, um desenvolvedor ou proprietário da conta conclui um fluxo de consentimento único no navegador. Seu aplicativo solicita acesso off-line (access_type=offline) junto com o escopo da API. O Google retorna um código de autorização, que seu aplicativo troca por um token de acesso inicial e um token de atualização de longa duração.

Execução em segundo plano:armazene o refresh_token com segurança no ambiente de implantação ou no gerenciador de secrets (por exemplo, GitHub Actions Secrets, Google Secret Manager). Para as chamadas de API seguintes, o fluxo de trabalho automatizado usa o token de atualização armazenado para receber um novo token de acesso de curta duração sob demanda, ignorando qualquer login manual ou solicitação de 2FA. 		Se você preferir evitar o armazenamento de tokens de atualização de longa duração no seu ambiente ou se o aplicativo for executado em um contexto de usuário interativo:

Solicitação na execução:não solicite acesso off-line nem armazene um token de atualização. Sempre que a ferramenta ou o aplicativo for executado, peça para o usuário fazer a autenticação redirecionando-o para a página de consentimento do OAuth do Google no navegador.

Acesso de curta duração:o usuário faz login e dá consentimento, e o aplicativo recebe um token de acesso de curta duração diretamente (ou usando a troca de código de autorização). Esse token de acesso é usado para fazer chamadas de API e é descartado após a execução. As execuções futuras exigem que o usuário faça uma nova autenticação.

Registrar um nome de pacote

O registro do nome do pacote é o processo de associar uma chave a um nome de pacote. A forma como uma chave é registrada depende de se você está registrando uma chave para um nome de pacote novo ou atual no Android.

Registrar um novo nome de pacote

Para um nome de pacote que não existe no Android, basta fornecer o certificado de chave pública do par de chaves de assinatura do app.

Registrar um nome de pacote atual

Para registrar um nome de pacote que já existe, é necessário comprovar a propriedade de uma chave de assinatura privada conhecida. Ao contrário do novo registro, a API retorna uma lista de impressões digitais de certificados públicos conhecidos que estão qualificados para registro. Essas chaves podem ser usadas diretamente para registro.

Se a chave que você está registrando estiver listada como "requer justificativa", ainda será possível registrá-la, mas, além de comprovar a propriedade, o desenvolvedor também precisará enviar uma justificativa para usar o nome do pacote.

Principais regras de qualificação

A lista de chaves qualificadas é determinada por regras de qualificação de nome de pacote. Elas foram criadas para minimizar o compartilhamento de nomes e apresentadas como parte da verificação de desenvolvedores Android.

Quando um nome de pacote é usado por vários desenvolvedores ou tem várias chaves de assinatura, a qualificação é determinada da seguinte maneira:

Cenário Regra para registro direto Regra para outros desenvolvedores
Titular da chave majoritária A chave que representa mais de 50% do total de instalações conhecidas tem prioridade. Todos os outros desenvolvedores precisam fornecer uma justificativa.
Mais de 50 instalações Se nenhuma chave tiver mais de 50% das instalações, todas as chaves com 50 ou mais instalações vão se qualificar. Os desenvolvedores com chaves que têm menos de 50 instalações precisam enviar uma justificativa.
Menos de 50 instalações Se nenhuma chave atender ao limite de 50 instalações, qualquer chave poderá ser usada por ordem de chegada. Depois que um desenvolvedor se registrar, os outros precisarão enviar uma justificativa.

Verificar a propriedade da chave

Para concluir a verificação de um nome de pacote atual, a API fornece uma string de verificação. Essa string de verificação precisa ser incluída em um novo arquivo chamado adi-registration.properties na pasta de recursos do app. Em seguida, assine e faça upload do APK usando a chave privada correspondente à chave pública que você está registrando.

Justificar o registro da chave

Se o registro de uma chave exigir uma justificativa, os desenvolvedores precisarão enviar uma justificativa comercial detalhada. O Google analisa essa justificativa, e a aprovação do registro do nome do pacote pode levar até 24 horas.

Práticas recomendadas de experiência do usuário

Recomendamos que os aplicativos que usam a API Android Developer Console sigam esses padrões para garantir uma integração perfeita.

Estabelecer um contexto claro de autorização do OAuth

Fornecer um contexto explícito antes de solicitar a autorização do OAuth ajuda os desenvolvedores a entender por que o acesso à conta é necessário. Para orientar os usuários de forma eficaz, apresente uma explicação clara da funcionalidade esperada antes de iniciar a tela de permissão OAuth.

Estruture o contexto de autorização usando o seguinte formato:

  • Título: "Vincule sua conta do Android Developer Console"
  • Resumo: "Gerenciar o registro de nomes de pacotes para a verificação de desenvolvedor Android no [application-name]"
  • Botão de ação: "Continuar com o Google" ou "Fazer login com o Google"
Caixa de diálogo que ilustra o contexto de autorização do OAuth para vincular uma conta.
Figura 1. Vincule sua conta do Android Developer Console.

Identificar as contas de desenvolvedor

  1. Faça a integração com o método de API ListDeveloperAccounts para recuperar e listar todas as contas de desenvolvedor com acesso autorizado.
  2. Forneça um seletor de contas para que o desenvolvedor possa escolher a conta de desenvolvedor preferida.
  3. Destaque a conta displayName, usando o número da conta do campo name como informação secundária.
  4. Mostre os estados de verificação da conta (verificationState):
    • VERIFIED: confirme a identidade verificada do desenvolvedor com uma indicação visual positiva (por exemplo, uma marca de seleção verde).
    • NOT_VERIFIED: indica que a verificação está incompleta e restringe o registro de pacotes para a conta. Se quiser, forneça um botão de CTA principal que direcione os desenvolvedores ao Android Developer Console ao selecionar a conta.
Seletor de conta mostrando o nome da conta de desenvolvedor e o estado de verificação.
Figura 2. Seletor de contas mostrando as contas de desenvolvedor e o estado de verificação.

Se uma resposta vazia for recebida porque não há contas de desenvolvedor associadas à Conta do Google, oriente os desenvolvedores a acessar o Android Developer Console usando um botão de CTA principal.

Gerenciar nomes de pacotes

  1. Integre com o endpoint de API ListAndroidPackages para recuperar todos os nomes de pacotes associados à conta de desenvolvedor. Ofereça aos desenvolvedores uma interface centralizada, como uma lista ou tabela, para monitorar os estados dos pacotes de forma eficaz.
  2. Mostre o packageName ao lado do status de registro atual (DRAFT, IN_REVIEW, REGISTERED ou PENDING_TRANSFER), aplicando indicadores visuais diferentes para cada status. Se um "nome amigável" foi fornecido e salvo durante a criação, é possível incluí-lo na exibição.
Interface que mostra os nomes dos pacotes registrados e os status deles.
Figura 3. Interface para gerenciar nomes de pacotes e status de registro.

Gerenciar chaves

  1. Chame o endpoint de API ListAndroidPackageKeys para buscar todas as chaves vinculadas a um nome de pacote, oferecendo aos desenvolvedores uma visão geral estruturada (como uma tabela ou lista) para monitorar o status do registro.
  2. Apresente o certificateFingerprintSha256 de cada chave ao lado do estado de registro (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE ou PENDING_TRANSFER), usando indicadores visuais distintos para diferenciar os estados.
Lista de impressões digitais de certificados e estados de registro de chaves.
Figura 4. Visão geral das chaves e dos estados de registro delas.
  1. Permita que os desenvolvedores registrem outras chaves em um nome de pacote atual integrando-se ao método de API CreateAndroidPackageKey.

Registrar um nome de pacote

  1. Use um layout baseado em formulário em que os desenvolvedores insiram o nome do pacote em um campo de texto, desde que essas informações ainda não tenham sido coletadas pelo seu aplicativo (por exemplo, em uma solicitação anterior).
  2. Chame o método de API CreateAndroidPackage para registrar um nome de pacote na conta de desenvolvedor e chame o método de API GetAndroidPackageRegistrationPolicy para determinar as regras de qualificação de chaves aplicáveis.
  3. Com base no keySelectionStrategy designado para o nome do pacote, peça ao desenvolvedor para realizar uma das seguintes ações:
    • Se keySelectionStrategy estiver definido como SELECT_KEY_FROM_LIST: peça para o desenvolvedor escolher uma chave para registro na lista knownKeys fornecida (contendo impressões digitais do certificado SHA-256), por exemplo, usando botões de opção. Esse fluxo requer a verificação de propriedade da chave (consulte Verificar a propriedade de uma chave abaixo).
    • Se keySelectionStrategy estiver definido como USE_ANY_KEY: solicite que o desenvolvedor forneça uma chave diretamente. A verificação de propriedade da chave não é necessária nesse caso.
  4. Chame o método de API CreateAndroidPackageKey para associar a chave escolhida ao novo nome do pacote.
Formulário para registrar o nome do pacote e selecionar a chave de assinatura.
Figura 5. Fluxo para registrar um nome de pacote e selecionar uma chave.

Como alternativa, seu aplicativo pode detectar e extrair automaticamente o nome do pacote ou a chave diretamente de um app enviado.

Verificar a propriedade de uma chave

Quando keySelectionStrategy é definido como SELECT_KEY_FROM_LIST, os desenvolvedores precisam comprovar a propriedade da chave de assinatura privada. Para comprovar a propriedade, é necessário enviar um APK assinado que incorpore o verificationToken gerado pela API.

Para oferecer suporte à verificação de propriedade da chave, integre o método de API VerifyAndroidPackageKeyOwnership e crie os seguintes componentes da interface do usuário:

  • Componente de exibição de token:mostre o verificationToken em destaque em um bloco de snippet de código, incluindo um botão "Copiar para a área de transferência".
  • Instruções de configuração para desenvolvedores:forneça instruções detalhadas para que o desenvolvedor coloque um arquivo adi-registration.properties com o verificationToken na pasta de recursos do app.
  • Área de upload de APK:ofereça uma área dedicada para o upload de arquivos para receber o APK assinado.
Área de arrastar e soltar e exibição de token para verificar a propriedade da chave.
Figura 6. Componentes da interface para verificar a propriedade da chave com o upload do APK assinado.

Justificar o registro de uma chave

Quando uma chave conhecida tem o campo justificationRequired definido como REQUIRED, o registro dessa chave com o nome do pacote exige que os desenvolvedores enviem uma justificativa comercial detalhada.

Envie essa justificativa chamando o método de API JustifyAndroidPackageKeyRegistration. A interface do usuário do aplicativo precisa ter uma área dedicada para que o desenvolvedor insira a justificativa. Além disso, ele precisa ser notificado de que é obrigatório fornecer uma justificativa antes de enviar a solicitação de registro da chave. O Google analisa a justificativa enviada, um processo que pode levar até 24 horas para ser aprovado antes que o registro do nome do pacote seja concluído.

Automatizar a verificação de chaves gerenciadas

Se o aplicativo gerenciar a chave de assinatura de um desenvolvedor, ele não poderá assinar manualmente um APK para verificação de propriedade. Em vez disso, você precisa executar a chamada de API VerifyAndroidPackageKeyOwnership automaticamente em nome deles.

Ao lidar com o processo de inclusão de token e upload de APK automaticamente, seu aplicativo remove essas etapas manuais. Notifique os desenvolvedores de que a verificação de propriedade da chave é gerenciada de forma integrada pelo aplicativo usando a chave armazenada no sistema.

Seguir as diretrizes da marca

Para manter a confiança dos usuários e garantir a transparência, todos os aplicativos que se integram à API Android Developer Console precisam seguir as diretrizes de marca abaixo.

Terminologia e uso de letras maiúsculas

Ao mencionar o produto em materiais ou documentações voltados ao usuário, sempre use o nome completo Android Developer Console. Não use a abreviação "ADC".

O programa precisa ser chamado de verificação de desenvolvedor Android. Siga essa capitalização e ortografia exatas em todos os contextos.

Para evitar ambiguidade com APKs ou AABs, use o termo "nome do pacote" especificamente, em vez de apenas "pacote".

Ao descrever o processo de adição de um nome de pacote, use a frase "registrar um nome de pacote" em vez de "reivindicar um nome de pacote".

Usar a call-to-action "Fazer login"

A autenticação OAuth 2.0 com o Android Developer Console depende dos Serviços de Identificação do Google. Para manter a conformidade com as diretrizes de branding dos Serviços de Identificação do Google, use a call-to-action "Continuar com o Google" ou "Fazer login com o Google" no botão de autorização. Esse texto é obrigatório e não pode ser modificado, porque garante que os usuários entendam que estão usando as credenciais do Google para autorizar seu aplicativo a acessar a Conta do Google deles.

Manter a identidade e a integridade da marca

Ao integrar o logotipo do Android Developer Console à interface do seu aplicativo, siga estas especificações para preservar a identidade visual e a integridade da marca:

  • Posicionamento e hierarquia do logotipo:use apenas o logotipo oficial e aprovado do Android Developer Console. O logotipo precisa sempre ser secundário em relação aos elementos de branding principais do seu aplicativo para evitar que ele seja confundido com um produto oficial do Google.
Logotipo oficial do Android Developer Console. Clique para salvar o arquivo.
Figura 7. Logotipo oficial do Android Developer Console. Clique na imagem para salvar o arquivo.
  • Estilo visual e distorções:o recurso precisa sempre ser renderizado com a proporção totalmente restrita. Nunca distorça, estique, incline, corte, vire ou modifique os componentes do logotipo. Não altere a paleta de cores oficial, não troque as cores de primeiro plano ou de fundo nem aplique sombras projet., efeitos de brilho ou gradientes decorativos.
  • Restrições de uso:não incorpore elementos de marca do Google aos recursos do seu aplicativo. O recurso de logotipo do Android Developer Console só pode ser usado no contexto do layout do aplicativo para indicar explicitamente uma integração ativa.

Outros recursos