Penginstalan Inline Google Play (app store pihak ketiga)

Halaman ini menjelaskan cara app store pihak ketiga yang terdaftar dalam program Akses Katalog dapat mengintegrasikan penginstalan inline Google Play, sebuah fitur yang memungkinkan app store Android pihak ketiga di Amerika Serikat mengarahkan pengguna untuk mendownload aplikasi Google Play melalui Google Play dengan persyaratan yang sama seperti saat mendownload aplikasi langsung melalui Google Play Store.

Prasyarat

Sebelum mengintegrasikan API penginstalan inline di app store pihak ketiga, Anda harus menyelesaikan penyiapan berikut di Konsol Google Play:

  1. Mendaftar ke Program Akses Katalog Google Play: Ikuti petunjuk pendaftaran.
  2. Memilih ikut serta dalam Akses Katalog: Daftar ke program Akses Katalog melalui setelan Konsol Play Anda.
  3. Mengambil token pengiriman: Proses ekspor Katalog Aplikasi Google Play yang diberikan kepada Anda. Ekspor ini berisi catalog_token (token pengiriman) yang diperlukan untuk setiap aplikasi yang memenuhi syarat untuk Anda distribusikan.

Persyaratan

Agar antarmuka setengah halaman berhasil ditampilkan kepada pengguna, persyaratan berikut harus dipenuhi:

  • Pengguna harus berada di Amerika Serikat.
  • Versi Google Play minimum di perangkat harus 52.3.
  • Level API Android harus 24 atau yang lebih tinggi.
  • Anda harus memberikan catalog_token yang valid dan belum habis masa berlakunya untuk mengakses Google Play Store.

Memanggil penginstalan inline dari app store Anda

Untuk memanggil sheet setengah layar penginstalan inline, buat instance class Intent yang menargetkan URL deep link Google Play dan menyertakan catalog_token unik Anda.

Gunakan kode contoh berikut (Kotlin atau Java) sebagai panduan:

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
}

Parameter API penginstalan inline

Parameter berikut harus diteruskan di URL Intent Anda atau sebagai Tambahan Intent untuk mengizinkan penginstalan inline:

Kolom Jenis Lokasi Deskripsi Wajib
id String Kueri URL Nama paket aplikasi target yang akan diinstal. Ya
referrer String Kueri URL String pelacakan perujuk opsional. Tidak
overlay boolean Intent Extra Tetapkan ke true untuk meminta antarmuka panel bawah inline. Ya
callerId String Intent Extra Nama paket app store pihak ketiga yang disetujui. Ya
catalog_token String Intent Extra Token pengiriman unik yang diberikan dalam ekspor Akses Katalog Anda. Catatan: Token divalidasi untuk keaktualan, kecocokan paket target, dan kecocokan paket pemanggil. Ya

(Opsional) Inline Install Google Play dengan overlay status penginstalan

Untuk menampilkan overlay status penginstalan dengan alur penginstalan inline, Anda harus mengintegrasikan Penginstalan Inline Google Play dengan fitur Kemampuan Persisten menggunakan Google Play HSDP SDK.

Agar alur penginstalan inline dengan affordance persisten muncul:

  • Versi Google Play Store minimum perangkat target harus 52.6 atau yang lebih tinggi.
  • Level API Android harus 24 (Android M) atau yang lebih tinggi.
  • Lakukan integrasi dengan HSDP SDK versi 2.1.0 atau yang lebih tinggi.

Contoh integrasi

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);

Contoh penghentian pelacakan affordance

Memungkinkan aplikasi pemanggil berhenti melacak status penginstalan secara manual dan menutup overlay HPOA. Catatan: Tindakan ini tidak akan menutup sheet penginstalan HSDP itu sendiri, hanya affordance.

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
      }
    });

Status Affordance & UX

Fitur Inline Install Google Play dengan Affordance Persisten memiliki dua status visual:

  1. Status Penginstalan: Menampilkan thumbnail aplikasi target dan indikator progres penginstalan. Mengklik thumbnail akan meluncurkan kembali sheet penginstalan HSDP.
  2. Status Setelah Penginstalan: Menampilkan ikon aplikasi target dengan tindakan "Buka". Mengklik thumbnail akan membuka aplikasi yang baru diinstal.
Menginstal Pasca-penginstalan
Status Penginstalan (Diperluas)

Status Penginstalan (Diciutkan)
Status Pasca-penginstalan