외부 콘텐츠 링크용 인앱 통합 가이드

이 문서에서는 Play Billing Library API를 통합하여 요건을 충족하는 앱에서 외부 콘텐츠 링크를 제공하는 방법을 설명합니다. 여기에는 Play 앱 외부에서 미국 사용자를 연결하여 사용자에게 인앱 디지털 콘텐츠 및 앱 다운로드 혜택을 제공하는 기능이 포함됩니다. 이 프로그램에 관해 자세히 알아보려면 프로그램 요구사항을 참고하세요.

Play 결제 라이브러리 설정

Android 앱에 Play Billing Library 종속 항목을 추가합니다. 외부 링크 API를 사용하려면 버전 8.2.1 이상을 사용해야 합니다. 이전 버전에서 이전해야 하는 경우 외부 콘텐츠 링크를 추가하기 전에 이전 가이드의 안내를 따르세요.

결제 클라이언트 초기화

결제 클라이언트를 초기화하려면 BillingClient 초기화에 설명된 단계와 동일한 단계를 따르되 다음과 같이 수정합니다.

  • PurchasesUpdatedListener를 사용 설정하지 마세요. 이 리스너는 외부 콘텐츠 링크에 필요하지 않습니다.
  • BillingProgram.EXTERNAL_CONTENT_LINK를 사용하여 enableBillingProgram()을 호출하여 앱이 외부 콘텐츠 링크를 사용함을 나타냅니다.

다음 예에서는 이러한 수정사항으로 BillingClient를 초기화하는 방법을 보여줍니다.

Kotlin

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

Java

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

Google Play에 연결

BillingClient를 초기화한 후 Google Play에 연결에 설명된 대로 Google Play에 연결합니다.

사용자 자격 확인

Google Play에 연결한 후에는 사용자가 외부 콘텐츠 연결 프로그램에 참여할 수 있는지 isBillingProgramAvailableAsync() 메서드를 호출하여 확인해야 합니다. 이 메서드는 사용자가 외부 콘텐츠 링크 프로그램을 이용할 수 있는 경우 BillingResponseCode.OK를 반환합니다. 다음 샘플은 외부 콘텐츠 링크에 대한 사용자 자격을 확인하는 방법을 보여줍니다.

Kotlin

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

        // External content links are available. Prepare an external
        // transaction token.
      }
    })

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare an external
        // transaction token.
      }

    });

앱이 다른 응답 코드에 응답하는 방법에 관한 자세한 내용은 응답 처리 섹션을 참고하세요. Kotlin 확장 프로그램을 사용하는 경우 Kotlin 코루틴을 사용하면 별도의 리스너를 정의할 필요가 없습니다.

외부 거래 토큰 준비

다음으로 Play Billing Library에서 외부 거래 토큰을 생성해야 합니다. 사용자가 외부 링크 API를 통해 외부 웹사이트를 방문할 때마다 새 외부 거래 토큰을 생성해야 합니다. 이는 createBillingProgramReportingDetailsAsync API를 호출하여 실행할 수 있습니다. 토큰은 사용자가 연결되기 직전에 생성되어야 합니다.

참고: 외부 거래 토큰은 캐시하면 안 되며 사용자가 연결될 때마다 새 토큰을 생성해야 합니다.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
    }
  })

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 external transaction token locally. Pass it to the
        // external website when launchExternalLink is called.
      }
  });

Kotlin 확장 프로그램을 사용하는 경우 Kotlin 코루틴을 사용하면 별도의 리스너를 정의할 필요가 없습니다.

외부 링크 실행

외부 거래 토큰이 준비되면 사용자는 앱 외부의 디지털 콘텐츠 혜택 또는 앱 다운로드로 연결될 수 있습니다. launchExternalLink 메서드를 호출하여 이 API를 호출하면 Google Play에서 사용자 설정에 따라 사용자에게 추가 정보 대화상자를 렌더링할 수 있습니다.

launchExternalLink 메서드를 호출할 때는 외부 링크의 세부정보 를 LaunchExternalLinkParams를 통해 제공해야 합니다. 이 클래스에는 다음과 같은 매개변수가 포함되어 있습니다.

  • 링크 URI - 디지털 콘텐츠 또는 앱 다운로드가 제공되는 외부 웹사이트의 링크입니다. 앱 다운로드의 경우 이 링크는 Play Console에 등록되고 승인되어야 합니다.
  • 링크 유형 - 사용자에게 제공되는 콘텐츠 유형입니다.
  • 실행 모드 - 링크가 실행되는 방법을 지정합니다. 앱 다운로드의 경우 이를 LAUNCH_IN_EXTERNAL_BROWSER_OR_APP으로 설정해야 합니다.
  • 결제 프로그램 - 이를 BillingProgram.EXTERNAL_CONTENT_LINK로 설정합니다.

Kotlin

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(
        billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
}

billingClient.launchExternalLink(activity, params, listener)

Java

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .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.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

응답 처리

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

  • ERROR: 내부 오류입니다. 거래 또는 외부 웹사이트 열기를 진행하지 마세요. API를 다시 호출하거나 다음에 사용자를 앱 외부로 안내할 때 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와의 연결을 다시 설정합니다.

외부 콘텐츠 링크 테스트

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

다음 단계

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