Google Play 인라인 설치 (서드 파티 앱 스토어)

이 페이지에서는 카탈로그 액세스 프로그램에 등록된 서드 파티 앱 스토어가 Google Play 인라인 설치를 통합하는 방법을 설명합니다. 인라인 설치는 서드 파티 미국 Android 앱 스토어가 Google Play 스토어를 통해 직접 이루어지는 다른 다운로드와 동일한 조건으로 Google Play를 통해 Play 앱 다운로드로 사용자를 안내할 수 있는 기능입니다.

기본 요건

서드 파티 앱 스토어에 인라인 설치 API를 통합하기 전에 Google Play Console에서 다음 설정을 완료해야 합니다.

  1. Google Play 카탈로그 액세스 프로그램 등록: 등록 안내를 따르세요.
  2. 카탈로그 액세스 선택: Play Console 설정을 통해 카탈로그 액세스 프로그램에 등록합니다.
  3. 전달 토큰 가져오기: 제공된 Play 앱 카탈로그 내보내기를 처리합니다. 이 내보내기에는 배포할 수 있는 각 앱에 필요한 catalog_token (전달 토큰)이 포함되어 있습니다.

요구사항

사용자에게 하프시트 인터페이스가 표시되려면 다음 요구사항을 충족해야 합니다.

  • 사용자가 미국 에 있어야 합니다.
  • 기기의 최소 Google Play 버전은 52.3 이어야 합니다.
  • Android API 수준은 24 이상 이어야 합니다.
  • Play 스토어에 액세스하려면 유효하고 만료되지 않은 catalog_token을 제공해야 합니다.

앱 스토어에서 인라인 설치 호출

인라인 설치 하프시트를 호출하려면 Google Play 딥 링크 URL을 타겟팅하고 고유한 catalog_token을 포함하는 Intent 클래스의 인스턴스를 만듭니다.

다음 샘플 코드 (Kotlin 또는 자바)를 가이드라인으로 사용하세요.

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
}

자바

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
byte[] 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
}

인라인 설치 API 매개변수

인라인 설치를 승인하려면 다음 매개변수를 인텐트 URL 또는 인텐트 추가 항목으로 전달해야 합니다.

필드 위치 설명 필수
id URL 쿼리 설치할 대상 앱의 패키지 이름입니다. 예
referrer URL 쿼리 선택적 리퍼러 추적 문자열입니다. 아니요
overlay 인텐트 추가 항목 인라인 하프시트 인터페이스를 요청하려면 true로 설정합니다. 예
callerId 인텐트 추가 항목 승인된 서드 파티 앱 스토어의 패키지 이름입니다. 예
catalog_token 인텐트 추가 항목 카탈로그 액세스 내보내기에 제공된 고유한 전달 토큰입니다. 참고: 토큰은 최신 상태, 대상 패키지 일치, 호출자 패키지 일치에 대해 검증됩니다. 예

(선택사항) 설치 상태 오버레이가 있는 Google Play 인라인 설치

인라인 설치 흐름과 함께 설치 상태 오버레이를 표시하려면 Google Play HSDP SDK를 사용하여 Google Play 인라인 설치를 영구적 어포던스 기능과 통합해야 합니다.

영구적 어포던스가 있는 인라인 설치 흐름이 표시되려면 다음을 충족해야 합니다.

  • 대상 기기의 최소 Google Play 스토어 버전은 52.6 이상이어야 합니다.
  • Android API 수준은 24 (Android M) 이상이어야 합니다.
  • 버전 2.1.0 이상으로 HSDP SDK와 통합합니다.

통합 예

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

어포던스 추적 중지 예

호출자 앱에서 설치 상태 추적을 수동으로 중지하고 HPOA 오버레이를 닫을 수 있습니다. 참고: 이 작업은 HSDP 설치 시트 자체를 닫지 않고 어포던스만 닫습니다.

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

어포던스 상태 및 UX

영구적 어포던스 기능이 있는 Google Play 인라인 설치에는 두 가지 시각적 상태가 있습니다.

  1. 설치 상태: 대상 앱의 미리보기 이미지와 설치 진행률 스피너를 표시합니다. 미리보기 이미지를 클릭하면 HSDP 설치 시트가 다시 실행됩니다.
  2. 설치 후 상태: '열기' 작업이 있는 대상 앱 아이콘을 표시합니다. 미리보기 이미지를 클릭하면 새로 설치된 앱이 열립니다.
설치 중 설치 후
설치 상태 (펼침)

설치 상태 (접기)		 설치 후 상태