Зарегистрируйте имена пакетов в API консоли разработчика Android.

API консоли разработчика Android — это общедоступный интерфейс, предназначенный для того, чтобы дистрибьюторы приложений и отдельные разработчики могли программно регистрировать имена пакетов в консоли разработчика Android.

Ваши возможности взаимодействия между серверами в качестве:

дистрибьютор приложений Индивидуальный разработчик
Зарегистрируйте имя пакета — ключ от имени разработчика, публикующего приложение в магазине. Зарегистрируйте имя пакета с ключом, управляемым магазином. Подтвердите владение ключом, связанным с именем пакета. Зарегистрируйте имя пакета — ключ в ваших рабочих процессах непрерывного развертывания. Подтвердите владение ключом, связанным с именем пакета.

Прежде чем начать

Прежде чем начать, вам необходимо:

  1. Административный доступ к проекту Google Cloud.
  2. Базовое понимание:

Вам также следует ознакомиться со следующими терминами:

Срок Определение
Учетная запись разработчика Представляет собой учетную запись в консоли разработчика Android, которая может владеть одним или несколькими именами пакетов. Она содержит состояние проверки ( NOT_VERIFIED или VERIFIED ).
Название пакета Конкретное имя пакета Android (например, com.example.app ) в учетной записи разработчика, которое может быть связано с одним или несколькими ключами. Оно содержит состояние регистрации ( DRAFT , IN_REVIEW , REGISTERED или PENDING_TRANSFER ).
Ключ Конкретный открытый сертификат/ключ, используемый для подписи имени пакета Android. Включает хеш SHA-256 и текущее состояние регистрации ( DRAFT , OWNERSHIP_VERIFIED , IN_REVIEW , REGISTERED или PENDING_TRANSFER ).

Начать

Для доступа к API консоли разработчика Android выполните следующие шаги:

Создайте проект в Google Cloud.

  1. Если у вас его еще нет , создайте учетную запись Google Cloud .
  2. Откройте консоль Google Cloud .
  3. Создайте проект в Google Cloud .

Включите API в своем проекте Google Cloud.

  1. Откройте консоль Google Cloud .
  2. В навигационном меню (☰) выберите API и сервисы > Библиотека .
  3. Выберите проект Google Cloud, в котором вы хотите включить API, из выпадающего меню проекта.
  4. Воспользуйтесь строкой поиска «API и сервисы» , чтобы выбрать «API консоли разработчика Android» .
  5. Включите API:
    1. Перейдите на страницу обзора API, выбрав его в результатах поиска.
    2. Нажмите синюю кнопку «Включить». Google Cloud активирует API для выбранного вами проекта, что обычно занимает всего несколько секунд. После активации вы сможете начать его использовать.

Аутентификация API

Для выполнения вызовов к API консоли разработчика Android необходимо аутентифицировать запросы с помощью OAuth 2.0.

Аутентификация с помощью OAuth 2.0

Для доступа к ресурсам учетной записи разработчика и именам пакетов API консоли разработчика Android требует аутентификации OAuth 2.0. Поскольку данные учетной записи разработчика привязаны к учетной записи Google пользователя, а не к проекту Google Cloud, учетные записи служб, федерация идентификации рабочих нагрузок и ключи API не могут использоваться для аутентификации запросов API.

Область действия OAuth 2.0

Для всех операций требуется следующая область действия:

Область действия OAuth 2.0 Описание
https://www.googleapis.com/auth/androiddeveloperconsole Просматривайте и управляйте именами пакетов и данными в своих учетных записях консоли разработчика Android.

Реализуйте протокол аутентификации веб-сервера OAuth 2.0.

Для интеграции с API консоли разработчика Android приложения должны использовать поток OAuth 2.0 Web Server . В зависимости от типа вашего приложения и потребностей в автоматизации вы можете выбрать одну из двух основных стратегий управления учетными данными:

Вариант A (рекомендуемый): Автономный / автоматизированный доступ (CI/CD и интеграция с сервером) Вариант B: Временный/интерактивный доступ
Эта стратегия позволяет автоматизированным процессам (например, конвейерам CI/CD) работать в фоновом режиме без вмешательства человека:

Одноразовая настройка согласия пользователя: Во время первоначальной настройки разработчик или владелец учетной записи выполняет одноразовую процедуру получения согласия в своем браузере. Ваше приложение запрашивает доступ в автономном режиме ( access_type=offline ) вместе с областью действия API. Google возвращает код авторизации , который ваше приложение обменивает на первоначальный токен доступа и долгосрочный токен обновления .

Выполнение в фоновом режиме: надежно сохраните refresh_token в вашей среде развертывания или менеджере секретов (например, в GitHub Actions Secrets, Google Secret Manager). Для последующих вызовов API ваш автоматизированный рабочий процесс будет использовать сохраненный refresh_token для получения нового кратковременного токена доступа по запросу, минуя любые запросы на ручной вход в систему или двухфакторную аутентификацию.		 Если вы предпочитаете избегать хранения долговременных токенов обновления в вашей среде или если ваше приложение работает в интерактивном пользовательском контексте:

Запрос подтверждения при выполнении: не запрашивайте доступ в автономном режиме и не сохраняйте токен обновления. При каждом запуске инструмента или приложения запрашивайте у пользователя аутентификацию, перенаправляя его на страницу согласия Google OAuth в браузере.

Кратковременный доступ: пользователь входит в систему и дает согласие, после чего приложение получает кратковременный токен доступа напрямую (или посредством обмена кодами авторизации). Этот токен доступа используется для выполнения вызовов API и удаляется после завершения работы. При последующих запусках пользователю потребуется повторная аутентификация.

Зарегистрируйте имя пакета

Регистрация имени пакета — это процесс сопоставления ключа с именем пакета. Способ регистрации ключа зависит от того, регистрируете ли вы ключ для нового или существующего имени пакета в Android.

Зарегистрируйте новое имя пакета

Для нового имени пакета, которое ранее не встречалось на Android, вы можете предоставить сертификат открытого ключа из пары ключей подписи приложения.

Зарегистрируйте существующее имя пакета

Для регистрации существующего имени пакета необходимо подтвердить владение известным закрытым ключом подписи. В отличие от новой регистрации, API возвращает список известных отпечатков открытых сертификатов, которые подходят для регистрации. Эти ключи можно использовать для прямой регистрации.

Если для регистрируемого ключа указано, что требуется обоснование, вы все равно можете его зарегистрировать, но помимо подтверждения права собственности, разработчик также должен предоставить обоснование использования имени пакета.

Основные правила участия

Список допустимых ключей определяется правилами допустимости имен пакетов, разработанными для минимизации совпадения имен пакетов (введенными в рамках проверки разработчиков Android).

В случаях, когда имя пакета используется несколькими разработчиками или имеет несколько ключей подписи, право на участие определяется следующим образом:

Сценарий Правила прямой регистрации Правило для других разработчиков
Владелец основного ключа Ключ, на долю которого приходится более 50% всех известных установок, имеет приоритет. Все остальные разработчики должны предоставить обоснование.
Более 50 установок Если ни один ключ не имеет более 50% установок, то все ключи с 50 и более установками имеют право на участие. Разработчики, у которых количество установок составляет менее 50, должны предоставить обоснование.
Менее 50 установок Если количество установленных ключей не достигнет порога в 50, любой ключ может быть использован в порядке очереди. После регистрации одного разработчика остальные должны предоставить обоснование.

Проверьте права собственности на ключ.

Для завершения проверки существующего имени пакета API предоставляет строку проверки. Эту строку проверки необходимо включить в новый файл с именем adi-registration.properties , расположенный в папке assets приложения. Затем необходимо подписать и загрузить APK-файл, используя закрытый ключ, соответствующий регистрируемому открытому ключу.

Обосновать регистрацию ключа

Если для регистрации ключа требуется обоснование, разработчики должны предоставить подробное обоснование с точки зрения бизнеса. Google рассматривает это обоснование, и одобрение регистрации имени пакета может занять до 24 часов.

лучшие практики пользовательского опыта

Для обеспечения бесшовной интеграции приложениям, использующим API консоли разработчика Android, рекомендуется следовать этим шаблонам.

Создайте четкий контекст авторизации OAuth.

Предоставление четкого контекста перед запросом авторизации OAuth помогает разработчикам понять, зачем необходим доступ к учетной записи. Для эффективного взаимодействия с пользователями необходимо представить ясное объяснение ожидаемой функциональности перед запуском экрана согласия OAuth.

Структурируйте контекст авторизации, используя следующий формат:

  • Заголовок: "Привяжите свою учетную запись в консоли разработчика Android"
  • Краткое описание: "Управление регистрацией имен пакетов для проверки разработчика Android в рамках [название приложения]"
  • Кнопка действия: кнопка «Продолжить с Google» или «Войти с Google».
Диалоговое окно, иллюстрирующее контекст авторизации OAuth для привязки учетной записи.
Рисунок 1. Макет диалогового окна контекста авторизации Clear OAuth.

Определите учетные записи разработчиков.

  1. Интегрируйте API-метод ListDeveloperAccounts для получения и отображения всех учетных записей разработчиков, которым был предоставлен доступ.
  2. Предоставьте разработчику средство выбора учетной записи, позволяющее выбрать предпочитаемую учетную запись.
  3. Выделите поле displayName учетной записи, используя номер учетной записи из поля name в качестве дополнительной информации.
  4. Отображение состояний проверки учетной записи ( verificationState ):
    • VERIFIED : Подтвердите личность разработчика с помощью визуального подтверждения (например, зеленой галочки).
    • NOT_VERIFIED : Указывает на то, что проверка не завершена, и ограничивает регистрацию пакетов для данной учетной записи. При желании можно добавить основную кнопку призыва к действию (CTA), которая при выборе учетной записи будет перенаправлять разработчиков в консоль разработчика Android.
В окне выбора учетной записи отображается имя учетной записи разработчика и состояние проверки.
Рисунок 2. Средство выбора учетных записей, отображающее учетные записи разработчиков и состояние проверки.

Если получен пустой ответ, поскольку к учетной записи Google не привязаны никакие учетные записи разработчиков, направьте разработчиков в консоль разработчика Android с помощью основной кнопки призыва к действию.

Управление именами пакетов

  1. Интегрируйте API-интерфейс ListAndroidPackages для получения всех имен пакетов, связанных с учетной записью разработчика. Предоставьте разработчикам централизованный интерфейс, например, список или таблицу, для эффективного мониторинга состояния их пакетов.
  2. Отображайте имя packageName рядом с его текущим статусом регистрации ( DRAFT , IN_REVIEW , REGISTERED или PENDING_TRANSFER ), используя отдельные визуальные индикаторы для каждого статуса. Если при создании было указано и сохранено «удобное для восприятия имя», вы можете дополнительно включить его в отображение.
Интерфейс, отображающий зарегистрированные названия пакетов и их статусы.
Рисунок 3. Интерфейс для управления именами пакетов и статусами регистрации.

Управление ключами

  1. Воспользуйтесь конечной точкой API ListAndroidPackageKeys , чтобы получить все ключи, связанные с именем пакета, предоставляя разработчикам структурированный обзор (например, в виде таблицы или списка) для отслеживания статуса их регистрации.
  2. Для каждого ключа необходимо отображать certificateFingerprintSha256 вместе с его состоянием регистрации ( DRAFT , OWNERSHIP_VERIFIED , IN_REVIEW , REGISTERED_ACTIVE или PENDING_TRANSFER ), используя различные визуальные индикаторы для различения состояний.
Список отпечатков пальцев сертификатов и основных штатов регистрации.
Рисунок 4. Обзор ключей и состояний их регистрации.
  1. Предоставьте разработчикам возможность регистрировать дополнительные ключи под существующим именем пакета, интегрировав метод API CreateAndroidPackageKey .

Зарегистрируйте имя пакета

  1. Используйте макет на основе форм, где разработчики вводят название своего пакета в текстовое поле, при условии, что эта информация еще не была получена вашим приложением (например, посредством предыдущего запроса).
  2. Вызовите метод API CreateAndroidPackage , чтобы зарегистрировать имя пакета в учетной записи разработчика, и вызовите метод API GetAndroidPackageRegistrationPolicy , чтобы определить применимые правила соответствия ключу .
  3. Исходя из заданной keySelectionStrategy для имени пакета, предложите разработчику выполнить одно из следующих действий:
    • Если keySelectionStrategy установлен в значение SELECT_KEY_FROM_LIST : разработчику предлагается выбрать ключ для регистрации из предоставленного списка knownKeys (содержащего отпечатки сертификатов SHA-256), например, с помощью переключателей. Этот процесс требует проверки принадлежности ключа (см. раздел «Проверка принадлежности ключа» ниже).
    • Если keySelectionStrategy установлен в USE_ANY_KEY : Предложите разработчику предоставить ключ напрямую. В этом случае проверка принадлежности ключа не требуется.
  4. Вызовите метод API CreateAndroidPackageKey , чтобы связать выбранный ключ с новым именем пакета.
Форма для регистрации названия пакета и выбора ключа подписи.
Рисунок 5. Схема регистрации имени пакета и выбора ключа.

В качестве альтернативы, ваше приложение может автоматически определять и извлекать имя пакета или ключ непосредственно из загруженного приложения.

Подтвердите принадлежность ключа.

Если keySelectionStrategy установлен в значение SELECT_KEY_FROM_LIST , разработчики должны подтвердить право собственности на свой закрытый ключ подписи. Подтверждение права собственности требует отправки подписанного APK-файла, содержащего сгенерированный API-интерфейсом verificationToken .

Для поддержки проверки прав собственности на ключ интегрируйте метод API VerifyAndroidPackageKeyOwnership и создайте следующие компоненты пользовательского интерфейса:

  • Компонент отображения токена: Отображает verificationToken на видном месте внутри блока кода, включая удобную кнопку «Скопировать в буфер обмена».
  • Инструкции для разработчика по настройке: Предоставьте подробные инструкции, указывающие разработчику на необходимость размещения файла adi-registration.properties , содержащего verificationToken в папке assets приложения.
  • Dropzone для отправки APK-файлов: Предоставьте специальную зону для загрузки файлов, куда можно будет получить подписанный APK-файл.
Зона для сброса и отображение токена для подтверждения принадлежности ключа.
Рисунок 6. Компоненты пользовательского интерфейса для проверки принадлежности ключа при загрузке подписанного APK-файла.

Обоснуйте регистрацию ключа.

Если для известного ключа поле justificationRequired установлено в REQUIRED , то для регистрации этого ключа вместе с именем пакета разработчикам необходимо предоставить подробное обоснование целесообразности проекта.

Submit this justification by calling the JustifyAndroidPackageKeyRegistration API method. Ensure your application's user interface features a dedicated text input area to collect the justification from the developer, and notify them that providing a rationale is required before submitting the key registration request. Google reviews the submitted justification, a process that can take up to 24 hours to approve before the package name registration is complete.

Автоматизация проверки ключей управления

Если ваше приложение управляет ключом подписи разработчика, разработчик не может вручную подписать APK-файл для проверки права собственности. Вместо этого вам необходимо автоматически выполнить вызов API VerifyAndroidPackageKeyOwnership от его имени.

Автоматическая обработка процесса включения токена и загрузки APK-файла позволяет вашему приложению исключить эти ручные действия. Обязательно сообщите разработчикам, что проверка принадлежности ключа осуществляется вашим приложением без проблем с использованием ключа, хранящегося в вашей системе.

Следуйте рекомендациям бренда.

Для поддержания доверия пользователей и обеспечения прозрачности все приложения, интегрирующиеся с API консоли разработчика Android, должны соответствовать следующим рекомендациям по фирменному стилю.

Терминология и использование заглавных букв

При упоминании продукта в материалах для пользователей или документации всегда используйте полное название Android Developer Console. Не используйте аббревиатуру "ADC".

Программу необходимо называть «Проверка разработчика Android». Во всех случаях следует придерживаться именно такого написания и регистра букв.

Чтобы избежать неоднозначности при работе с APK-файлами или AAB-архивами, используйте термин «имя пакета» вместо просто «пакет».

При описании процесса добавления имени пакета используйте фразу «зарегистрировать имя пакета» вместо «заявить права на имя пакета».

Используйте призыв к действию «Войти»

OAuth 2.0 authentication with Android Developer Console relies on Google Identity Services. To remain compliant with the Google Identity Services branding guidelines , you must use the "Continue with Google" or "Sign in with Google" call-to-action on the authorization button. This text is mandatory and cannot be modified, as it ensures users understand they are using their Google credentials to authorize your application to access their Google Account.

Сохранение фирменного стиля и целостности бренда.

При интеграции логотипа Android Developer Console в интерфейс вашего приложения необходимо соблюдать следующие требования для сохранения визуальной идентичности и целостности бренда:

  • Размещение и иерархия логотипа: Используйте только официальный, утвержденный логотип консоли разработчика Android. Логотип всегда должен оставаться второстепенным по отношению к основным элементам фирменного стиля вашего приложения, чтобы избежать ложного представления приложения как официального продукта Google.
Официальный логотип консоли разработчика Android. Нажмите, чтобы сохранить файл.
Рисунок 7. Официальный логотип консоли разработчика Android. Нажмите на изображение, чтобы сохранить файл.
  • Визуальный стиль и искажения: Изображение всегда должно отображаться с полностью сохраненным соотношением сторон. Ни в коем случае нельзя искажать, растягивать, переворачивать, обрезать, отражать или изменять компоненты логотипа. Не изменяйте официальную цветовую палитру, не меняйте цвета переднего и заднего плана, не применяйте тени, эффекты свечения или декоративные градиенты.
  • Ограничения по использованию: Не включайте элементы фирменной символики Google в собственные ресурсы приложения. Логотип консоли разработчика Android можно использовать только в контексте макета приложения для явного обозначения активной интеграции.

Дополнительные ресурсы