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 forma programática los nombres de los paquetes en Android Developer Console.

Tus capacidades de servidor a servidor como:

Distribuidor de la app	Desarrollador individual
Registra una clave de nombre de paquete en nombre del desarrollador que publica una app en la tienda. Registra un nombre de paquete con una clave administrada por la tienda. Demostrar la propiedad de una clave asociada con un nombre de paquete	Registra un nombre de paquete y una clave en tus flujos de trabajo de implementación continua. Demostrar la propiedad de una clave asociada con un nombre de paquete

Antes de comenzar

Antes de comenzar, debes tener lo siguiente:

1. Acceso de administrador a un proyecto de Google Cloud
2. Conocimientos básicos sobre lo siguiente:
   • API de RESTful
   • Estructura de APK
   • Firma de apps para Android
   • Genera resúmenes SHA-256

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 de Android específico (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íficos que se usan 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

Sigue estos 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 Google Cloud Console
3. Crea un proyecto de Google Cloud

Habilita la API en tu proyecto de Google Cloud

1. Abre Google Cloud Console
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 la API de Android Developer Console.
5. Habilita la API:
   1. Para navegar a la página de resumen de la API, selecciónala en los resultados de la búsqueda.
   2. Haz clic en el botón azul Habilitar. Google Cloud activa la API para el proyecto que seleccionaste, lo que suele tardar solo un momento. Una vez que lo habilites, podrás comenzar a usarlo.

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 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, las cuentas de servicio, la federación de identidades para cargas de trabajo y las claves de API no se pueden usar 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 y datos de paquetes 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 la 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 única del consentimiento del usuario: 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 devuelve 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 a la API posteriores, tu flujo de trabajo automatizado usa el token de actualización almacenado para obtener un token de acceso de corta duración nuevo a pedido, lo que evita cualquier acceso manual o mensaje 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, haz lo siguiente: 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 aplicación, solicita al usuario que se autentique redireccionándolo a la página de consentimiento de Google OAuth en su navegador. Acceso de corta duración: El usuario accede y otorga su consentimiento, y la aplicación recibe un token de acceso de corta duración directamente (o mediante el intercambio de código 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.

Cómo registrar 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 la registras con un nombre de paquete nuevo o existente en Android.

Cómo registrar 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 devuelve una lista de huellas digitales de certificados públicos conocidas que son aptas 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 de todos modos, 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 clave

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 en un archivo nuevo llamado adi-registration.properties dentro de 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 estás registrando.

Justifica el registro de claves

Si el registro de una clave requiere una justificación, los desarrolladores deben enviar una justificación comercial detallada. Google revisa esta justificación, y la aprobación del 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 claro de autorización de OAuth

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 lanzar 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 de nombres de paquetes para la verificación de desarrolladores de Android en [application-name]"
• Botón de acción: Botón "Continuar con Google" o "Acceder con Google"

Identifica las cuentas de desarrollador

1. Realiza la integración con el método de la API de ListDeveloperAccounts para recuperar y enumerar todas las cuentas de desarrollador para las que se autorizó el acceso.
2. Proporciona un selector de cuentas para que el desarrollador pueda elegir su cuenta de desarrollador preferida.
3. Destaca el displayName de la cuenta y usa 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 un indicador visual positivo (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.

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 nombres de paquetes

1. Realiza la integración con el endpoint de API de 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 los estados de sus 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.

Administrar claves

1. Llama al endpoint de API de ListAndroidPackageKeys para recuperar todas las claves vinculadas a un nombre de paquete, lo que ofrece a los desarrolladores una descripción general estructurada (como una tabla o lista) para supervisar su estado de registro.
2. Presenta el certificateFingerprintSha256 de 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.

1. Permite que los desarrolladores registren claves adicionales con un nombre de paquete existente integrando el método de la API de CreateAndroidPackageKey.

Cómo registrar 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 un mensaje anterior).
2. Llama al método de la API de CreateAndroidPackage para inscribir un nombre de paquete en la cuenta de desarrollador y llama al método de la API de GetAndroidPackageRegistrationPolicy para determinar las reglas de elegibilidad de claves aplicables.
3. Según el keySelectionStrategy designado para el nombre del paquete, pídele al desarrollador que realice una de las siguientes acciones:
   • Si keySelectionStrategy se establece en SELECT_KEY_FROM_LIST, haz que el desarrollador elija una clave para el registro de la lista knownKeys proporcionada (que contiene huellas digitales del certificado 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 se establece en USE_ANY_KEY, se le solicita al desarrollador que proporcione una clave directamente. En este caso, no se necesita la verificación de la propiedad de la clave.
4. Llama al método de la API de CreateAndroidPackageKey para asociar la clave elegida con el nombre del paquete nuevo.

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

Verifica la propiedad de una clave

Cuando keySelectionStrategy se establece en SELECT_KEY_FROM_LIST, los desarrolladores deben demostrar la propiedad de su clave de firma privada. Para comprobar la propiedad, se debe enviar un APK firmado que incorpore el verificationToken generado por la API.

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

• Componente de visualización del token: Muestra el verificationToken de forma destacada dentro de un bloque de fragmento de código, incluido un botón práctico para copiarlo al portapapeles.
• Instrucciones de configuración para desarrolladores: Proporciona instrucciones detalladas que indiquen al desarrollador que coloque un archivo adi-registration.properties que contenga el verificationToken en la carpeta de recursos de la app.
• Zona de entrega para el envío de APK: Ofrece una zona de entrega dedicada para subir archivos y recibir el APK firmado.

Justifica el registro de una clave

Cuando una clave conocida tiene su campo justificationRequired establecido en REQUIRED, registrar esa clave junto con el nombre del paquete requiere que los desarrolladores envíen una justificación comercial exhaustiva.

Envía esta justificación llamando 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 notificarle que debe proporcionar una justificación 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 las claves administradas

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

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

Sigue los lineamientos de la marca

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

Terminología y uso de mayúsculas

Cuando hagas referencia al producto en materiales o documentación para el 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 ambigüedades con los APK o AAB, usa el término "nombre del 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 desarrollo 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 están usando sus credenciales de Google para autorizar a tu aplicación a acceder a su Cuenta de Google.

Mantener la identidad y la integridad de la marca

Cuando integres el logotipo de Android Developer Console en la interfaz de tu aplicación, deberás 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 de marca principales de tu aplicación para evitar que se la represente de forma errónea como un producto oficial de Google.

• Estilo visual y distorsiones: El recurso siempre se debe renderizar con su relación de aspecto completamente restringida. Nunca debes distorsionar, estirar, sesgar, recortar, voltear ni modificar los componentes del logotipo. No alteres la paleta de colores oficial, no intercambies los colores de primer plano o de fondo, ni apliques sombras paralelas, efectos de brillo o degradados decorativos.
• Restricciones de uso: No incorpores ningún elemento de desarrollo de la marca 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 de forma explícita una integración activa.

Recursos adicionales

• Referencia de la API de Android Developer Console
• Verifica el estado de registro de la app con la API de Android Developer ID Status
• Cómo registrarse en Android Developer Console
• Regístrate en Google Play Console
• Firma la app