Как зарегистрировать названия пакетов с помощью Android Developer Console API

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

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

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

Подготовка

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

  1. Доступ с правами администратора к проекту Google Cloud.
  2. Базовое понимание следующих концепций:

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

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

Начать

Чтобы получить доступ к Android Developer Console API, выполните следующие действия:

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

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

Как включить API в проекте Google Cloud

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

Выполните аутентификацию API

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

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

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

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

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

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

Как реализовать процесс OAuth 2.0 для веб-сервера

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

Вариант А (рекомендуется). Офлайн-доступ или автоматический доступ (непрерывная интеграция/непрерывная поставка и интеграция с сервером) Вариант Б. Кратковременный/интерактивный доступ
Этот подход позволяет автоматизированным процессам (например, конвейерам непрерывной интеграции и поставки) выполняться в фоновом режиме без участия человека.

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

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

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

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

Как зарегистрировать название пакета

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

Как зарегистрировать новое название пакета

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

Как зарегистрировать существующее название пакета

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

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

Основные требования

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

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

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

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

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

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

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

Рекомендации по интеграции Google Pay API

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

Установите четкий контекст авторизации OAuth

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

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

  • Название: "Свяжите аккаунт Android Developer Console".
  • Summary: "Manage package name registration for Android developer verification within [application-name]"
  • Кнопка действия: "Продолжить с аккаунтом Google" или "Войти с аккаунтом Google".
Диалоговое окно, иллюстрирующее контекст авторизации OAuth для связывания аккаунта.
Рисунок 1. Установите связь с аккаунтом Android Developer Console.

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

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

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

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

  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, чтобы связать выбранный ключ с названием пакета, и проверьте возвращенный объект state в ответе AndroidPackageKey:
    • Если state – это DRAFT, требуется подтвердить право собственности на ключ (см. раздел Как подтвердить право собственности на ключ).
    • Если state – IN_REVIEW, то проверка права собственности на ключ и обоснование были пропущены автоматически. Это связано с тем, что название пакета новое или разработчик уже подтвердил право собственности на этот ключ для другого названия пакета в том же аккаунте разработчика.
Форма для регистрации названия пакета и выбора ключа подписи.
Рисунок 5. Процесс регистрации названия пакета и выбора ключа.

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

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

Если метод CreateAndroidPackageKey возвращает объект AndroidPackageKey, в котором для поля state задано значение DRAFT (это происходит, когда ключ регистрируется для существующего названия пакета и ещё не подтвержден для другого названия пакета в том же аккаунте разработчика), разработчики должны подтвердить право собственности на закрытый ключ подписи. Чтобы подтвердить право собственности, необходимо отправить подписанный APK-файл, содержащий сгенерированный API файл verificationToken.

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

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

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

Если для ключа задано значение true параметра registrationJustificationRequired (соответствует значению REQUIRED параметра justificationRequirement для известного ключа) и VerifyAndroidPackageKeyOwnership переводит ключ в состояние OWNERSHIP_VERIFIED, то для регистрации этого ключа вместе с названием пакета разработчикам необходимо предоставить подробное бизнес-обоснование.

Отправьте обоснование, вызвав метод API JustifyAndroidPackageKeyRegistration. Убедитесь, что в пользовательском интерфейсе вашего приложения есть специальная область ввода текста, где разработчик может указать обоснование. Также сообщите ему, что без обоснования отправить запрос на регистрацию ключа нельзя. Google проверяет обоснование. Это может занять до 24 часов. После одобрения регистрация названия пакета будет завершена.

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

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

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

Соблюдайте правила фирменного оформления

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

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

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

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

Чтобы избежать путаницы с APK-файлами и наборами App Bundle, используйте термин "название пакета", а не просто "пакет".

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

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

Аутентификация OAuth 2.0 в Android Developer Console выполняется с помощью сервисов идентификации Google. Чтобы соблюдать правила фирменного оформления сервисов идентификации Google, на кнопке авторизации необходимо использовать призыв к действию "Продолжить с аккаунтом Google" или "Войти с аккаунтом Google". Этот текст является обязательным и не может быть изменен, поскольку он гарантирует, что пользователи понимают, что они используют свои учетные данные Google для авторизации вашего приложения для доступа к их аккаунту Google.

Поддерживайте индивидуальность и целостность бренда

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

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

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