외부 혜택 프로그램을 위한 인앱 통합 가이드

이 가이드에서는 API와 통합하여 대상 앱 및 지역에서 외부 제안을 지원하는 방법을 설명합니다. 자격 요건과 지리적 범위 등 외부 제안 프로그램에 관한 자세한 내용은 프로그램 요구사항을 참고하세요.

Play 결제 라이브러리 설정

외부 제안 API를 사용하려면 Android 앱에 Play 결제 라이브러리 종속 항목 버전 8.2 이상을 추가하세요. 이전 버전에서 이전해야 하는 경우 외부 제안을 구현하기 전에 이전 가이드의 안내를 따르세요.

Google Play에 연결

통합 프로세스의 첫 번째 단계는 결제 통합 가이드에 설명된 단계와 동일하지만 BillingClient 초기화 시 외부 제안을 사용하겠다고 표시하려면 enableBillingProgram를 호출해야 합니다.

다음 예는 이러한 수정을 적용하여 BillingClient를 초기화하는 방법을 보여줍니다.

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_OFFER)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

BillingClient를 초기화한 후에는 통합 가이드에 설명된 대로 Google Play에 연결해야 합니다.

사용 가능 여부 확인

현재 사용자가 외부 제안을 사용할 수 있는지 확인하려면 isBillingProgramAvailableAsync을 호출하세요.

이 API는 외부 제안이 제공되는 경우 BillingResponseCode.OK를 반환합니다. 앱이 다른 응답 코드에 응답하는 방법에 관한 자세한 내용은 응답 처리를 참고하세요.

Kotlin


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingResult: BillingResult,
      billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers unavailable, etc.
            return
        }

        // External offers are available. Continue with steps in the
        // guide.
      }
  })

자바


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      BillingResult billingResult,
      BillingProgramAvailabilityDetails billingProgramAvailabilityDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }
  });

외부 거래 토큰 준비

Google Play에 외부 거래를 보고하려면 Play 결제 라이브러리에서 생성된 외부 거래 토큰이 있어야 합니다. createBillingProgramReportingDetailsAsync API를 호출하여 이 토큰을 가져올 수 있습니다. 사용자를 앱 외부로 안내하기 직전에 각 외부 혜택에 대해 새 토큰을 생성해야 합니다. 토큰은 트랜잭션 간에 캐시하면 안 됩니다.

Kotlin

val params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
    }
})

자바

BillingProgramReportingDetailsParams params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();
        // Persist the transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
      }
});

또는 Kotlin 확장 프로그램으로 정지 함수 createBillingProgramReportingDetailsAsync를 쿼리하여 리스너를 정의하지 않아도 됩니다.

  val createBillingProgramReportingDetailsResult =
    withContext(context) {
      billingClient
        .createBillingProgramReportingDetails(params)
    }
  // Process the result

외부 제안 흐름 시작

외부 제안 흐름을 시작하려면 자격 요건을 충족하는 앱이 앱의 기본 스레드에서 launchExternalLink() API를 호출해야 합니다. 이 API는 LaunchExternalLinkParams 객체를 입력으로 사용합니다. LaunchExternalLinkParams 객체를 만들려면 LaunchExternalLinkParams.Builder 클래스를 사용하세요. 이 클래스에는 다음 매개변수가 포함됩니다.

  • linkUri - 디지털 콘텐츠 또는 앱 다운로드가 제공되는 외부 웹사이트로 연결되는 링크입니다. 앱 다운로드의 경우 이 링크가 Play 개발자 콘솔에 등록되고 승인되어야 합니다.
  • linkType - 사용자에게 제공되는 콘텐츠의 유형입니다.
  • launchMode - 링크가 실행되는 방식을 지정합니다. 앱 다운로드의 경우 이 값을 LAUNCH_IN_EXTERNAL_BROWSER_OR_APP로 설정해야 합니다.
  • billingProgram - BillingProgram.EXTERNAL_OFFER로 설정합니다.

launchExternalLink()를 호출하면 사용자 설정에 따라 사용자에게 추가 정보 대화상자가 표시될 수 있습니다. launchMode 매개변수에 따라 Play는 외부 브라우저에서 링크 URI를 실행하거나 URI를 실행하기 위해 흐름을 앱으로 반환합니다. 대부분의 경우 Play에서 URI를 실행하는 LAUNCH_IN_EXTERNAL_BROWSER_OR_APP 모드를 사용할 수 있습니다. 웹뷰에서 URI를 실행하거나 특정 브라우저에서 URI를 여는 등 더 맞춤화된 동작을 원한다면 CALLER_WILL_LAUNCH_LINK 모드를 사용하면 됩니다. 사용자 개인 정보를 보호하려면 URI에 개인 식별 정보 (PII)가 전달되지 않도록 하세요.

Kotlin


// An activity reference from which the external offers flow will be launched.
val activity = ...;

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    // You can pass along the external transaction token from
    // BillingProgramReportingDetails as a URL parameter in the URI
    .setLinkUri(yourLinkUri)
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
  LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(billingResult: BillingResult) {
    if (billingResult.responseCode == BillingResponseCode.OK) {
      // Proceed with the rest of the external offer flow. If the user
      // purchases an item, be sure to report the transaction to Google Play.
    } else {
      // Handle failures such as retrying due to network errors.
    }
  }
}

billingClient.launchExternalLink(activity, params, listener)

자바


// An activity reference from which the external offers flow will be launched.
Activity activity = ...;

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
  .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
  // You can pass along the external transaction token from  
  // BillingProgramReportingDetails as a URL parameter in the URI
  .setLinkUri(yourLinkUri)
  .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
  .setLaunchMode(
    LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
  .build();

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
      if (billingResult.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the external offer flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
      } else {
        // Handle failures such as retrying due to network errors.
      }
    }
  }

billingClient.launchExternalLink(activity, params, listener);

LaunchMode를 CALLER_WILL_LAUNCH_LINK로 설정하는 경우 onLaunchExternalLinkResponse에서 BillingResponseCode.OK를 제공하는 경우에만 사용자를 앱 외부로 안내해야 합니다.

Google Play에 거래 보고

백엔드에서 Google Play Developer API를 호출하여 모든 외부 거래를 Google Play에 보고해야 합니다. 거래를 신고할 때는 createBillingProgramReportingDetailsAsync API에서 가져온 externalTransactionToken를 제공해야 합니다. 사용자가 여러 번 구매하는 경우 동일한 externalTransactionToken를 사용하여 각 구매를 신고할 수 있습니다. 거래를 보고하는 방법을 알아보려면 백엔드 통합 가이드를 참고하세요.

응답 처리

오류가 발생하면 isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync(), launchExternalLink() 메서드가 BillingResponseCode.OK 이외의 응답을 반환할 수 있습니다. 다음과 같이 이러한 응답 코드를 처리하는 것이 좋습니다.

  • ERROR: 내부 오류입니다. 거래를 진행하거나 외부 웹사이트를 열지 마세요. 다음에 사용자를 앱 외부로 안내하려고 할 때 launchExternalLink()를 호출하여 정보 대화상자를 사용자에게 표시하여 다시 시도하세요.
  • FEATURE_NOT_SUPPORTED: 현재 기기의 Play 스토어에서 외부 제안 API를 지원하지 않습니다. 거래를 진행하거나 외부 웹사이트를 열지 마세요.
  • USER_CANCELED: 외부 웹사이트를 열지 않습니다. 다음에 사용자를 앱 외부로 안내하려고 할 때 launchExternalLink()를 다시 호출하여 사용자에게 정보 대화상자를 표시합니다.
  • BILLING_UNAVAILABLE: 이 거래는 외부 제안에 적합하지 않으므로 이 프로그램에서 진행되면 안 됩니다. 이는 사용자가 이 프로그램을 이용할 수 있는 국가에 거주하지 않거나 계정이 프로그램에 등록되지 않았기 때문입니다. 후자인 경우 Play Console에서 등록 상태를 확인하세요.
  • DEVELOPER_ERROR: 요청에 오류가 있습니다. 계속하기 전에 디버그 메시지를 사용하여 오류를 식별하고 수정하세요.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: 적절한 재시도 정책으로 처리해야 하는 일시적인 오류입니다. SERVICE_DISCONNECTED의 경우 다시 시도하기 전에 Google Play와의 연결을 다시 설정합니다.

외부 제안 테스트

라이선스 테스터는 외부 제안 통합을 테스트하는 데 사용해야 합니다. 라이선스 테스터 계정에서 시작된 거래에 대해서는 인보이스가 발행되지 않습니다. 라이선스 테스터 구성에 관한 자세한 내용은 애플리케이션 라이선스로 인앱 결제 테스트를 참고하세요.

다음 단계

인앱 통합을 완료했으면 백엔드 통합을 진행할 수 있습니다.