Встроенная установка Google Play (сторонние магазины приложений)

На этой странице описано, как сторонние магазины приложений, зарегистрированные в программе доступа к каталогу, могут интегрировать быструю установку Google Play. Эта функция позволяет сторонним магазинам приложений для Android в США направлять пользователей на скачивание приложений из каталога Google Play через Google Play на тех же условиях, что при скачивании из Google Play напрямую.

Требования

Прежде чем интегрировать API встроенной установки в сторонний магазин приложений, выполните следующие действия в Google Play Console:

  1. Зарегистрируйтесь в программе доступа к каталогу Google Play. Следуйте инструкциям.
  2. Согласие на доступ к каталогу. Зарегистрируйтесь в программе доступа к каталогу в настройках Play Console.
  3. Получите токены доставки. Обработайте экспорт каталога приложений Google Play, который вам предоставлен. В экспортированном файле будут содержаться необходимые токены catalog_token для каждого приложения, которое вы можете распространять.

Требования

Чтобы интерфейс half-sheet успешно показывался пользователям, должны выполняться следующие требования:

  • Пользователь должен находиться в США.
  • Минимальная версия Google Play на устройстве – 52.3.
  • Уровень API Android должен быть не ниже 24.
  • Чтобы получить доступ к Google Play, предоставьте действительный catalog_token.

Вызов встроенных установок из магазина приложений

Чтобы вызвать полуэкран встроенной установки, создайте экземпляр класса Intent, который указывает на URL ссылки на контент в Google Play и содержит ваш уникальный catalog_token.

Используйте следующий образец кода (Kotlin или Java) в качестве руководства:

Kotlin

val intent = Intent(Intent.ACTION_VIEW)
val referrer = "<Your referrer string>"
val id = "<Package name of the app to be installed>"
val callerId = "<Package name of your third-party app store>"

// Retrieve the app-specific token from your processed catalog export
val catalogToken = getVerificationTokenByDocId(id)

intent.setPackage("com.android.vending")
val deepLinkUrl = "https://play.google.com/d?id=$id&referrer=$referrer"
intent.data = Uri.parse(deepLinkUrl)

// Set the required intent extras
intent.putExtra("overlay", true)
intent.putExtra("callerId", callerId)
intent.putExtra("catalog_token", catalogToken)

val packageManager = context.getPackageManager()
if (intent.resolveActivity(packageManager) != null) {
  startActivityForResult(intent, 0) // Call with a request code to receive ActivityResults
}

Java

Intent intent = new Intent(Intent.ACTION_VIEW);
String referrer = "<Your referrer string>";
String id = "<Package name of the app to be installed>";
String callerId = "<Package name of your third-party app store>";

// Retrieve the app-specific token from your processed catalog export
String catalogToken = getVerificationTokenByDocId(id);

intent.setPackage("com.android.vending");
String deepLinkUrl = "https://play.google.com/d?id=" + id + "&referrer=" + referrer;
intent.setData(Uri.parse(deepLinkUrl));

// Set the required intent extras
intent.putExtra("overlay", true);
intent.putExtra("callerId", callerId);
intent.putExtra("catalog_token", catalogToken);

PackageManager packageManager = context.getPackageManager();
if (intent.resolveActivity(packageManager) != null) {
  startActivityForResult(intent, 0); // Call with a request code to receive ActivityResults
}

Параметры Inline Install API

Чтобы разрешить встроенную установку, в URL намерения или в качестве дополнительных параметров намерения необходимо передать следующие параметры:

Поле Тип Местоположение Описание Обязательно
id String Запрос URL Название пакета целевого приложения, которое нужно установить. Да
referrer String Запрос URL Необязательная строка отслеживания URL перехода. Нет
overlay boolean Intent Extra Задайте значение true, чтобы запросить встроенный интерфейс в виде полустраницы. Да
callerId String Intent Extra Название пакета одобренного стороннего магазина приложений. Да
catalog_token String Intent Extra Уникальный токен доставки, указанный в экспортированном файле с доступом к каталогу. Примечание. Токены проверяются на актуальность, соответствие целевому пакету и соответствие пакету вызывающего абонента. Да

Встроенная установка Google Play с оверлеем статуса установки (необязательно)

Чтобы показывать оверлей со статусом установки, вам нужно интегрировать встроенную установку Google Play с функцией постоянного доступа, используя Google Play HSDP SDK.

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

  • На целевом устройстве должна быть установлена версия Google Play не ниже 52.6.
  • Уровень API Android должен быть не ниже 24 (Android M).
  • Интегрируйте HSDP SDK версии 2.1.0 или более поздней.

Пример интеграции

Kotlin

// Step 1: Initialize HSDP Service
// Note: Calling create(activity) automatically configures useServiceBasedHsdp = false
// (Activity Path) under the hood without requiring manual boolean flags.
val hsdpService = HsdpDeepLinkServiceFactory.create(activity)

// Step 2: Construct Extra Query Parameters with Catalog Token
val extraQueryParams = mapOf("catalog_token" to "YOUR_SECURE_CATALOG_TOKEN_VALUE")

// Step 3: Trigger Inline Install Flow
hsdpService.open(
    targetAppPackageName = "com.example.targetapp",
    referrer = "3pas_ad_campaign_123",
    listener = object : HsdpDeepLinkServiceListener {
        override fun onDeepLinkStarted() {
            // Inline details dialog started successfully
        }
        override fun onAffordanceStarted() {
            // HPOA persistent affordance UI attached
        }
        override fun onAffordanceEnded() {
            // Affordance UI detached
        }
        override fun onError(errorMessage: String) {
            // Handle error or fallback
        }
    },
    extraQueryParams = extraQueryParams
)

Java

// Step 1: Initialize HSDP Service
// Note: Calling create(activity) automatically configures useServiceBasedHsdp = false
// (Activity Path) under the hood without requiring manual boolean flags.
HsdpDeepLinkService hsdpService = HsdpDeepLinkServiceFactory.create(activity);

// Step 2: Construct Extra Query Parameters with Catalog Token
Map<String, String> extraQueryParams = new HashMap<>();
extraQueryParams.put("catalog_token", "YOUR_SECURE_CATALOG_TOKEN_VALUE");

// Step 3: Trigger Inline Install Flow
hsdpService.open(
    "com.example.targetapp",
    "3pas_ad_campaign_123",
    new HsdpDeepLinkServiceListener() {
      @Override
      public void onDeepLinkStarted() {
        // Inline details dialog started successfully
      }

      @Override
      public void onAffordanceStarted() {
        // HPOA persistent affordance UI attached
      }

      @Override
      public void onAffordanceEnded() {
        // Affordance UI detached
      }

      @Override
      public void onError(String errorMessage) {
        // Handle error or fallback
      }
    },
    extraQueryParams);

Пример остановки отслеживания доступности

Позволяет вызывающему приложению вручную прекратить отслеживание статуса установки и закрыть оверлей HPOA. Примечание. Это не закроет само окно установки HSDP, а только уберет кнопку.

Kotlin

// Stop tracking the installation state and dismiss the affordance overlay
hsdpService.stopAffordance(
    targetAppPackageName = "com.example.targetapp",
    listener = object : HsdpDeepLinkService.AffordanceListener {
        override fun onAffordanceStopped() {
            // Affordance overlay stopped successfully
        }
    }
)

Java

// Stop tracking the installation state and dismiss the affordance overlay
hsdpService.stopAffordance(
    "com.example.targetapp",
    new HsdpDeepLinkService.AffordanceListener() {
      @Override
      public void onAffordanceStopped() {
        // Affordance overlay stopped successfully
      }
    });

Состояния аффорданса и UX

У функции встроенной установки Google Play с постоянным элементом интерфейса есть два визуальных состояния:

  1. Установка. Показывается значок целевого приложения и индикатор выполнения установки. Если нажать на значок, откроется лист установки HSDP.
  2. Состояние после установки: Показывается значок приложения с кнопкой "Открыть". Нажмите на значок, чтобы открыть установленное приложение.
Установка После установки
Установка (развернуто)

Состояние установки (свернуто)
Состояние после установки