Registra nombres de paquetes con la API de Android Developer Console

La API de Android Developer Console es una interfaz pública diseñada para permitir que los distribuidores de apps y los desarrolladores individuales registren de manera programática los nombres de paquetes en Android Developer Console.

Tus capacidades de servidor a servidor como:

Distribuidor de apps Desarrollador individual
Registra un nombre de paquete: clave en nombre del desarrollador que publica una app en Play Store. Registra un nombre de paquete con una clave administrada por Play Store. Demuestra la propiedad de una clave asociada con un nombre de paquete. Registra un nombre de paquete: clave en tus flujos de trabajo de implementación continua. Demuestra la propiedad de una clave asociada con un nombre de paquete.

Antes de comenzar

Antes de comenzar, debes tener lo siguiente:

  1. Acceso administrativo a un proyecto de Google Cloud
  2. Conocimientos básicos de lo siguiente:

También debes conocer los siguientes términos:

Término Definición
Cuenta de desarrollador Representa una cuenta de Android Developer Console que puede tener uno o más nombres de paquetes. Contiene un estado de verificación (NOT_VERIFIED o VERIFIED).
Nombre del paquete Es un nombre de paquete específico de Android (por ejemplo, com.example.app) dentro de una cuenta de desarrollador, que se puede asociar con una o más claves. Contiene un estado de registro (DRAFT, IN_REVIEW, REGISTERED o PENDING_TRANSFER).
Clave Es el certificado o la clave pública específica que se usa para firmar un nombre de paquete de Android. Incluye el hash SHA-256 y el estado de registro actual (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED o PENDING_TRANSFER).

Comenzar

Completa los siguientes pasos para acceder a la API de Android Developer Console:

Crea un proyecto de Google Cloud

  1. Crea una cuenta de Google Cloud si aún no tienes una.
  2. Abre la consola de Google Cloud.
  3. Crea un proyecto de Google Cloud.

Habilita la API en tu proyecto de Google Cloud

  1. Abre la consola de Google Cloud.
  2. En el menú de navegación (☰), selecciona APIs y servicios > Biblioteca.
  3. Selecciona el proyecto de Google Cloud en el que deseas habilitar la API en el menú desplegable del proyecto.
  4. Usa la barra de búsqueda de APIs y servicios para seleccionar API de Android Developer Console.
  5. Habilita la API:
    1. Para ello, selecciona la API en los resultados de la búsqueda y navega a la página de descripción general.
    2. Haz clic en el botón azul Habilitar. Google Cloud activa la API para el proyecto seleccionado, lo que suele tardar solo un momento. Una vez habilitada, puedes comenzar a usarla.

Autentica la API

Para realizar llamadas a la API de Android Developer Console, debes autenticar tus solicitudes con OAuth 2.0.

Autentica con OAuth 2.0

La API de Android Developer Console requiere la autenticación de OAuth 2.0 para autorizar el acceso a los recursos de la cuenta de desarrollador y los nombres de paquetes. Debido a que los datos de la cuenta de desarrollador están vinculados a la Cuenta de Google de un usuario en lugar de a un proyecto de Google Cloud, no se pueden usar cuentas de servicio, la federación de identidad para cargas de trabajo ni claves de API para autenticar solicitudes a la API.

Permiso de OAuth 2.0

Se requiere el siguiente permiso para todas las operaciones:

Permiso de OAuth 2.0 Descripción
https://www.googleapis.com/auth/androiddeveloperconsole Ver y administrar los nombres de paquetes y los datos en tus cuentas de Android Developer Console

Implementa el flujo del servidor web de OAuth 2.0

Para integrarse con la API de Android Developer Console, las aplicaciones deben usar el flujo del servidor web de OAuth 2.0. Según el tipo de aplicación y las necesidades de automatización, puedes elegir entre dos estrategias principales de administración de credenciales:

Opción A (recomendada): Acceso sin conexión o automatizado (CI/CD y integración del servidor) Opción B: Acceso efímero o interactivo
Esta estrategia permite que los procesos automatizados (como las canalizaciones de CI/CD) se ejecuten en segundo plano sin intervención humana:

Configuración de consentimiento del usuario único: Durante la configuración inicial, un desarrollador o propietario de la cuenta completa un flujo de consentimiento único en su navegador. Tu aplicación solicita acceso sin conexión (access_type=offline) junto con el permiso de la API. Google muestra un código de autorización que tu aplicación intercambia por un token de acceso inicial y un token de actualización de larga duración.

Ejecución en segundo plano: Almacena de forma segura el refresh_token en tu entorno de implementación o administrador de secretos (por ejemplo, GitHub Actions Secrets, Google Secret Manager). Para las llamadas posteriores a la API, tu flujo de trabajo automatizado usa el token de actualización almacenado para obtener un token de acceso nuevo de corta duración a pedido, sin pasar por ningún acceso manual ni solicitudes de 2FA. 		Si prefieres evitar almacenar tokens de actualización de larga duración en tu entorno o si tu aplicación se ejecuta en un contexto de usuario interactivo:

Solicitud en la ejecución: No solicites acceso sin conexión ni almacenes un token de actualización. Cada vez que se ejecute la herramienta o la aplicación, solicita al usuario que se autentique redireccionándolo a la página de consentimiento de OAuth de Google en su navegador.

Acceso de corta duración: El usuario accede y da su consentimiento, y la aplicación recibe un token de acceso de corta duración directamente (o mediante el intercambio de códigos de autorización). Este token de acceso se usa para realizar llamadas a la API y se descarta después de la ejecución. Las ejecuciones futuras requieren que el usuario vuelva a autenticarse.

Registra un nombre de paquete

El registro del nombre del paquete es el proceso de asociar una clave a un nombre de paquete. La forma en que se registra una clave depende de si registras una clave en un nombre de paquete nuevo o existente en Android.

Registra un nombre de paquete nuevo

En el caso de un nombre de paquete nuevo que nunca se haya visto en Android, puedes proporcionar el certificado de clave pública del par de claves de firma de la app.

Registra un nombre de paquete existente

Para registrar un nombre de paquete existente, debes demostrar la propiedad de una clave de firma privada conocida. A diferencia del registro nuevo, la API muestra una lista de huellas digitales de certificados públicos conocidos que son aptos para el registro. Estas claves se pueden usar para hacer el registro directo.

Si la clave que registras aparece como "requiere justificación", puedes registrarla, pero, además de completar la prueba de propiedad, el desarrollador también debe enviar una justificación para usar el nombre del paquete.

Reglas de elegibilidad de claves

La lista de claves elegibles se determina según las reglas de elegibilidad de los nombres de paquetes, las cuales se introdujeron como parte de la verificación de desarrolladores de Android, y están diseñadas para minimizar el uso compartido del nombre del paquete.

En situaciones en las que varios desarrolladores usan el mismo nombre de paquete o este tiene varias claves de firma, la elegibilidad se determina de la siguiente manera:

Situación Regla para el registro directo Regla para otros desarrolladores
Titular de la mayoría de las claves Tiene prioridad la clave que representa más del 50% de las instalaciones conocidas totales. Todos los demás desarrolladores deben proporcionar una justificación.
Más de 50 instalaciones Si ninguna clave única tiene más del 50% de las instalaciones, todas las claves con 50 instalaciones o más serán elegibles. Los desarrolladores con claves que tengan menos de 50 instalaciones deben proporcionar una justificación.
Menos de 50 instalaciones Si ninguna clave cumple con el umbral de 50 instalaciones, se puede usar cualquiera, por orden de llegada. Una vez que un desarrollador se registra, los demás deben proporcionar una justificación.

Verifica la propiedad de la clave

Para completar la verificación de un nombre de paquete existente, la API proporciona una cadena de verificación. Esta cadena de verificación debe incluirse dentro de un archivo nuevo llamado adi-registration.properties en la carpeta de recursos de la app. Luego, debes firmar y subir el APK con la clave privada correspondiente a la clave pública que registras.

Justifica el registro de la clave

Si el registro de una clave requiere una justificación, los desarrolladores deben enviar una lógica comercial detallada. Google revisa esta justificación, y la aprobación para el registro del nombre del paquete puede tardar hasta 24 horas.

Prácticas recomendadas para la experiencia del usuario

Se recomienda que las aplicaciones que usan la API de Android Developer Console sigan estos patrones para garantizar una integración perfecta.

Establece un contexto de autorización de OAuth claro

Proporcionar un contexto explícito antes de solicitar la autorización de OAuth ayuda a los desarrolladores a comprender por qué se requiere el acceso a la cuenta. Para guiar a los usuarios de manera eficaz, presenta una explicación clara de la funcionalidad esperada antes de iniciar la pantalla de consentimiento de OAuth.

Estructura el contexto de autorización con el siguiente formato:

  • Título: "Vincula tu cuenta de Android Developer Console"
  • Resumen: "Administra el registro del nombre del paquete para la verificación de desarrolladores de Android en [nombre de la aplicación]"
  • Botón de acción: Botón "Continuar con Google" o "Acceder con Google"
Diálogo que ilustra el contexto de autorización de OAuth para vincular una cuenta.
Figura 1. Diseño claro del diálogo de contexto de autorización de OAuth

Identifica las cuentas de desarrollador

  1. Realiza la integración con el método de la API ListDeveloperAccounts para recuperar y enumerar todas las cuentas de desarrollador para las que se autorizó el acceso.
  2. Proporciona un selector de cuentas para permitir que el desarrollador elija su cuenta de desarrollador preferida.
  3. Destaca el displayName de la cuenta con el número de cuenta del campo name como información secundaria.
  4. Muestra los estados de verificación de la cuenta (verificationState):
    • VERIFIED: Confirma la identidad verificada del desarrollador con una señal visual positiva (p.ej., una marca de verificación verde).
    • NOT_VERIFIED: Indica que la verificación está incompleta y restringe el registro de paquetes para la cuenta. De manera opcional, proporciona un botón de CTA principal que dirija a los desarrolladores a Android Developer Console cuando seleccionen la cuenta.
Selector de cuentas que muestra el nombre de la cuenta de desarrollador y el estado de verificación.
Figura 2. Selector de cuentas que muestra las cuentas de desarrollador y el estado de verificación

Si se recibe una respuesta vacía porque no hay cuentas de desarrollador asociadas con la Cuenta de Google, guía a los desarrolladores a Android Developer Console con un botón de CTA principal.

Administra los nombres de paquetes

  1. Realiza la integración con el endpoint de API ListAndroidPackages para recuperar todos los nombres de paquetes asociados con la cuenta de desarrollador. Proporciona a los desarrolladores una interfaz centralizada, como una lista o una tabla, para supervisar sus estados de paquetes de manera eficaz.
  2. Muestra el packageName junto con su estado de registro actual (DRAFT, IN_REVIEW, REGISTERED o PENDING_TRANSFER) y aplica indicadores visuales distintos para cada estado. Si se proporcionó y guardó un "nombre descriptivo" durante la creación, puedes incluirlo de forma opcional en la pantalla.
Es una interfaz que muestra los nombres de los paquetes registrados y sus estados.
Figura 3. Interfaz para administrar nombres de paquetes y estados de registro

Administra claves

  1. Llama al extremo de la API ListAndroidPackageKeys para recuperar todas las claves vinculadas a un nombre de paquete y ofrecer a los desarrolladores una descripción general estructurada (como una tabla o una lista) para supervisar su estado de registro.
  2. Presenta el certificateFingerprintSha256 para cada clave junto con su estado de registro (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE o PENDING_TRANSFER) y usa indicadores visuales distintos para diferenciar los estados.
Es una lista de huellas digitales de certificados y estados de registro de claves.
Figura 4. Descripción general de las claves y sus estados de registro
  1. Para permitir que los desarrolladores registren claves adicionales con un nombre de paquete existente, realiza la integración con el método de la API CreateAndroidPackageKey.

Registra un nombre de paquete

  1. Usa un diseño basado en formularios en el que los desarrolladores ingresen el nombre del paquete en un campo de texto, siempre que tu aplicación no haya recopilado esta información (p.ej., a través de una solicitud anterior).
  2. Llama al método de la API CreateAndroidPackage para inscribir un nombre de paquete en la cuenta de desarrollador y llama al método de la API GetAndroidPackageRegistrationPolicy para determinar las reglas de elegibilidad de claves aplicables.
  3. Según el keySelectionStrategy designado para el nombre del paquete, solicita al desarrollador que realice una de las siguientes acciones:
    • Si keySelectionStrategy está configurado como SELECT_KEY_FROM_LIST, haz que el desarrollador elija una clave para el registro de la lista knownKeys proporcionada (que contiene huellas digitales de certificados SHA-256), por ejemplo, con botones de selección. Este flujo requiere la verificación de la propiedad de la clave (consulta Verifica la propiedad de una clave a continuación).
    • Si keySelectionStrategy está configurado como USE_ANY_KEY, solicita al desarrollador que proporcione una clave directamente. En este caso, no es necesaria la verificación de la propiedad de la clave.
  4. Llama al método de la API CreateAndroidPackageKey para asociar la clave elegida con el nombre del paquete nuevo.
Formulario para registrar el nombre del paquete y seleccionar la clave de firma.
Figura 5. Flujo para registrar un nombre de paquete y seleccionar una clave

Como alternativa, tu aplicación puede detectar y extraer automáticamente el nombre o la clave del paquete directamente de una app subida.

Verifica la propiedad de una clave

Cuando keySelectionStrategy está configurado como SELECT_KEY_FROM_LIST, los desarrolladores deben demostrar la propiedad de su clave de firma privada. La prueba de propiedad requiere el envío de un APK firmado que incorpore el verificationToken generado por la API.

Para admitir la verificación de la propiedad de la clave, integra el método de la API VerifyAndroidPackageKeyOwnership y crea los siguientes componentes de la interfaz de usuario:

  • Componente de visualización de tokens: Muestra el verificationToken de forma destacada dentro de un bloque de fragmento de código, incluido un botón útil de "Copiar al portapapeles".
  • Instrucciones de configuración para desarrolladores: Proporciona instrucciones detalladas que dirijan al desarrollador para colocar un archivo adi-registration.properties que contenga el verificationToken en la carpeta de recursos de la app.
  • Zona de entrega de envío de APK: Ofrece una zona de entrega de carga de archivos dedicada para recibir el APK firmado.
Zona de entrega y visualización de tokens para verificar la propiedad de la clave.
Figura 6. Componentes de la IU para verificar la propiedad de la clave con la carga de APK firmado

Justifica el registro de una clave

Cuando una clave conocida tiene su campo justificationRequired configurado como REQUIRED, el registro de esa clave junto con el nombre del paquete requiere que los desarrolladores envíen una lógica comercial detallada.

Para enviar esta justificación, llama al método de la API JustifyAndroidPackageKeyRegistration. Asegúrate de que la interfaz de usuario de tu aplicación incluya un área de entrada de texto dedicada para recopilar la justificación del desarrollador y notifícale que es necesario proporcionar una lógica antes de enviar la solicitud de registro de la clave. Google revisa la justificación enviada, un proceso que puede tardar hasta 24 horas en aprobarse antes de que se complete el registro del nombre del paquete.

Automatiza la verificación de claves para claves administradas

Si tu aplicación administra la clave de firma de un desarrollador, este no puede firmar manualmente un APK para la verificación de la propiedad. En su lugar, debes ejecutar automáticamente la llamada a la API VerifyAndroidPackageKeyOwnership en su nombre.

Al controlar automáticamente la inclusión de tokens y el proceso de carga de APK, tu aplicación quita estos pasos manuales. Asegúrate de notificar a los desarrolladores que tu aplicación administra sin problemas la verificación de la propiedad de la clave con la clave almacenada en tu sistema.

Sigue los lineamientos de la marca

Para mantener la confianza del usuario y garantizar la transparencia, todas las aplicaciones que se integran con la API de Android Developer Console deben cumplir con los siguientes lineamientos de la marca.

Terminología y uso de mayúsculas

Cuando hagas referencia al producto en materiales o documentación orientados al usuario, usa siempre el nombre completo Android Developer Console. No uses la abreviatura "ADC".

El programa debe denominarse verificación de desarrolladores de Android. Sigue este uso exacto de mayúsculas y ortografía en todos los contextos.

Para evitar la ambigüedad con los APKs o los AABs, usa el término "nombre de paquete" específicamente en lugar de solo "paquete".

Cuando describas el proceso de agregar un nombre de paquete, usa la frase "registrar un nombre de paquete" en lugar de "reclamar un nombre de paquete".

Usa el llamado a la acción "Acceder"

La autenticación de OAuth 2.0 con Android Developer Console se basa en los Servicios de identidad de Google. Para seguir cumpliendo con los lineamientos de la marca de Google Identity Services, debes usar el llamado a la acción "Continuar con Google" o "Acceder con Google" en el botón de autorización. Este texto es obligatorio y no se puede modificar, ya que garantiza que los usuarios comprendan que usan sus credenciales de Google para autorizar que tu aplicación acceda a su Cuenta de Google.

Mantén la identidad y la integridad de la marca

Cuando integres el logotipo de Android Developer Console en la interfaz de tu aplicación, debes seguir estas especificaciones para preservar la identidad visual y la integridad de la marca:

  • Ubicación y jerarquía del logotipo: Usa solo el logotipo oficial y aprobado de Android Developer Console. El logotipo siempre debe ser secundario con respecto a los elementos principales de la marca de tu aplicación para evitar que se represente de forma incorrecta como un producto oficial de Google.
Logotipo oficial de Android Developer Console. Haz clic para guardar el archivo.
Figura 7. Logotipo oficial de Android Developer Console Haz clic en la imagen para guardar el archivo.
  • Estilo visual y distorsiones: El recurso siempre debe renderizarse con su relación de aspecto completamente restringida. Nunca debes distorsionar, alargar, inclinar, recortar, voltear ni modificar los componentes del logotipo. No alteres la paleta de colores oficial, no intercambies los colores del primer plano o del fondo, ni apliques sombras paralelas, efectos de brillo o degradados decorativos.
  • Restricciones de uso: No incorpores ningún elemento de la marca propiedad de Google en los recursos de tu aplicación. El recurso del logotipo de Android Developer Console solo se puede usar dentro del contexto del diseño de la aplicación para indicar explícitamente una integración activa.

Recursos adicionales