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 또는 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
}

자바

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.5 이상이어야 합니다.
  • Android API 수준은 24 (Android M) 이상이어야 합니다.
  • 버전 2.0.2 (출시 예정) 이상의 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. 설치 후 상태: '열기' 작업과 함께 타겟 앱 아이콘을 표시합니다. 썸네일을 클릭하면 새로 설치된 앱이 열립니다.
설치 설치 후
설치 상태 (펼침)

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