Как зарегистрировать названия пакетов с помощью 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 в папке assets приложения. Затем подпишите и загрузите APK-файл, используя закрытый ключ, который соответствует регистрируемому открытому ключу.

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

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

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

Рекомендуем следовать этим шаблонам, чтобы обеспечить беспроблемную интеграцию.

Четко указывайте контекст авторизации OAuth

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

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

  • Название: "Свяжите аккаунт Android Developer Console".
  • Описание. Управление регистрацией названий пакетов для проверки разработчиков Android в приложении [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, чтобы связать выбранный ключ с новым названием пакета.
Форма для регистрации названия пакета и выбора ключа подписи.
Рисунок 5. Процесс регистрации названия пакета и выбора ключа.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы избежать путаницы с APK-файлами и наборами Android 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 можно использовать только в макете приложения, чтобы явно указать на активную интеграцию.

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