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.

Suas capacidades de servidor para servidor como:

Distribuidor de apps	Desenvolvedor individual
Registre um nome de pacote e uma chave em nome do desenvolvedor que está publicando um app na loja. Registre um nome de pacote com uma chave gerenciada pela loja. Comprove a propriedade de uma chave associada a um nome de pacote.	Registre um nome de pacote e uma chave nos seus fluxos de trabalho de implantação contínua. Comprove 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. Um conhecimento básico de:
   • APIs RESTful
   • Estrutura do APK
   • Assinatura de apps Android
   • Geração de resumos SHA-256

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. Ela 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ífico usado para assinar um nome de pacote Android. Inclui o hash SHA-256 e o estado de registro atual (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED ou PENDING_TRANSFER).

Primeiros passos

Conclua as etapas a seguir para acessar a API Android Developer Console:

Criar um projeto do Google Cloud

1. Crie uma conta do Google Cloud se ainda não tiver uma.
2. Abra o Console do Google Cloud.
3. Crie um projeto na nuvem 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 do projeto.
4. Use a barra de pesquisa APIs e serviços para selecionar 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 ativada, você pode começar a usá-la.

Autenticar a API

Para fazer chamadas para a API Android Developer Console, você precisa autenticar suas solicitações usando o OAuth 2.0.

Autenticar com o OAuth 2.0

A API Android Developer Console exige a 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 a uma Conta do Google do 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 OAuth 2.0

Para fazer a integração com a 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, você pode escolher entre duas estratégias principais de gerenciamento de credenciais:

Opção A (recomendada): acesso off-line / automatizado (integração de CI/CD e 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 de consentimento do usuário único: Durante a configuração inicial, um desenvolvedor ou proprietário da conta conclui um fluxo de consentimento único no navegador. O aplicativo solicita acesso off-line (access_type=offline) junto com o escopo da API. O Google retorna um código de autorização, que o 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 chamadas de API subsequentes, 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ções 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 ao usuário para 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. Execuções futuras exigem que o usuário faça a autenticação novamente.

Registrar um nome de pacote

O registro do nome do pacote é o processo de associação de uma chave a um nome de pacote. A forma como uma chave é registrada depende de você estar 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, você pode 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 sã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 concluir a comprovação de propriedade, o desenvolvedor também precisará enviar uma justificativa para usar o nome do pacote.

Regras de qualificação de chaves

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 fornecer 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 fornecer 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 um registro de 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 de autorização OAuth claro

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

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

• Título : "Vincular sua conta do Android Developer Console"
• Resumo : "Gerenciar o registro do nome do pacote para a verificação de desenvolvedor Android em [nome do aplicativo]"
• Botão de ação:botão "Continuar com o Google" ou "Fazer login com o Google"

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 para as quais o acesso foi autorizado.
2. Forneça um seletor de contas para permitir que o desenvolvedor escolha a conta de desenvolvedor preferida.
3. Destaque o displayName da conta, usando o número da conta do campo name como informação secundária.
4. Mostre os estados de verificação de conta (verificationState):
   • VERIFIED: confirme a identidade de desenvolvedor verificada com uma dica visual positiva (por exemplo, uma marca de seleção verde).
   • NOT_VERIFIED: indique que a verificação está incompleta e restrinja o registro de pacotes para a conta. Opcionalmente, forneça um botão de CTA principal direcionando os desenvolvedores para o Android Developer Console ao selecionar a conta.

Se uma resposta vazia for recebida porque nenhuma conta de desenvolvedor está associada à Conta do Google, oriente os desenvolvedores para o Android Developer Console usando um botão de CTA principal.

Gerenciar nomes de pacotes

1. Faça a integração com o endpoint de API ListAndroidPackages para recuperar todos os nomes de pacotes associados à conta de desenvolvedor. Forneça aos desenvolvedores uma interface centralizada, como uma lista ou tabela, para monitorar os estados dos pacotes de maneira eficaz.
2. Mostre o packageName junto com o status de registro atual (DRAFT, IN_REVIEW, REGISTERED ou PENDING_TRANSFER), aplicando indicadores visuais distintos para cada status. Se um "nome amigável" foi fornecido e salvo durante a criação, você poderá incluí-lo na tela.

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 de registro.
2. Apresente o certificateFingerprintSha256 para cada chave junto com o estado de registro (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE ou PENDING_TRANSFER), usando indicadores visuais distintos para diferenciar os estados.

1. Permita que os desenvolvedores registrem outras chaves em um nome de pacote atual fazendo a integração com o método de API CreateAndroidPackageKey.

Registrar um nome de pacote

1. Use um layout baseado em formulário em que os desenvolvedores inserem o nome do pacote em um campo de texto, desde que essas informações ainda não tenham sido coletadas pelo aplicativo (por exemplo, por meio de uma solicitação anterior).
2. Chame o método de API CreateAndroidPackage para inscrever um nome de pacote na conta de desenvolvedor e chame o método de API GetAndroidPackageRegistrationPolicy para determinar as regras de qualificação de chave aplicáveis.
3. Com base na keySelectionStrategy designada 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 ao desenvolvedor para escolher uma chave para registro na lista knownKeys fornecida (que contém impressões digitais de certificados SHA-256), como o uso de botões de opção. Esse fluxo exige a verificação da propriedade da chave (consulte Verificar a propriedade de uma chave abaixo).
   • Se keySelectionStrategy estiver definido como USE_ANY_KEY: peça ao desenvolvedor para fornecer uma chave diretamente. A verificação da 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.

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

Verificar a propriedade de uma chave

Quando keySelectionStrategy está definido como SELECT_KEY_FROM_LIST, os desenvolvedores precisam comprovar a propriedade da chave de assinatura privada. A comprovação de propriedade exige o envio de um APK assinado que incorpore o verificationToken gerado pela API.

Para oferecer suporte à verificação da 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 dentro de um bloco de snippet de código, incluindo um botão "Copiar para a área de transferência".
• Instruções de configuração do desenvolvedor:forneça instruções detalhadas orientando o desenvolvedor a colocar um arquivo adi-registration.properties contendo o verificationToken na pasta de recursos do app.
• Zona de entrega de envio de APK:ofereça uma zona de entrega de upload de arquivo dedicada para receber o APK assinado.

Justificar o registro de uma chave

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

Envie essa justificativa chamando o método de API JustifyAndroidPackageKeyRegistration. Garanta que a interface do usuário do aplicativo tenha uma área de entrada de texto dedicada para coletar a justificativa do desenvolvedor e notifique-o de que é necessá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 dele.

Ao processar a inclusão de tokens e o upload de APK automaticamente, o aplicativo remove essas etapas manuais. Notifique os desenvolvedores de que a verificação da propriedade da chave é gerenciada de maneira integrada pelo aplicativo usando a chave armazenada no sistema.

Seguir as diretrizes de marca

Para manter a confiança do usuário e garantir a transparência, todos os aplicativos que fazem a integração com a API Android Developer Console precisam obedecer às seguintes diretrizes de marca.

Terminologia e capitalização

Ao referenciar o produto em materiais ou documentação voltados ao usuário, sempre use o nome completo Android Developer Console. Não use a abreviatura "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 ambiguidades 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 chamada para ação "Fazer login"

A autenticação OAuth 2.0 com o Android Developer Console depende dos Serviços de identidade do Google. Para permanecer em conformidade com as diretrizes de marca dos Serviços de Identificação do Google, você precisa usar a chamada para ação "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, já que garante que os usuários entendam que estão usando as credenciais do Google para autorizar o aplicativo a acessar a Conta do Google.

Manter a identidade e a integridade da marca

Ao integrar o logotipo do Android Developer Console à interface do 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 permanecer secundário aos elementos de marca principais do seu aplicativo para evitar a representação incorreta do aplicativo como um produto oficial do Google.

• Estilo visual e distorções:o recurso precisa sempre ser renderizado com a proporção totalmente restrita. Você nunca deve distorcer, esticar, inclinar, cortar, inverter ou modificar os componentes do logotipo. Não altere a paleta de cores oficial, troque as cores de primeiro ou segundo plano nem aplique sombras, efeitos de brilho ou gradientes decorativos.
• Restrições de uso:não incorpore elementos de marca de propriedade do Google aos recursos do 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

• Verificar o status de registro do app com a API Android Developer ID Status
• Registrar no Android Developer Console
• Registrar no Google Play Console
• Assinar o app