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

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

Play 결제 라이브러리 설정

외부 쿠폰 API를 사용하려면 Android 앱에 Play 결제 라이브러리 종속 항목 버전 6.2.1 이상을 추가합니다. 이전 버전에서 이전해야 한다면 외부 혜택을 구현하기 전에 이전 가이드의 안내를 따르세요.

Google Play에 연결

통합 프로세스의 첫 번째 단계는 결제 통합 가이드와 동일하지만 BillingClient 초기화 시 몇 가지 사항이 수정됩니다.

  • 외부 혜택을 사용하려는 것을 나타내려면 새 메서드 enableExternalOffer를 호출해야 합니다.

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

Kotlin

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

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

사용 가능 여부 확인

앱에서 isExternalOfferAvailableAsync를 호출하여 외부 혜택을 사용할 수 있는지 확인해야 합니다.

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

Kotlin


billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        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.
})

Java


billingClient.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        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 결제 라이브러리에서 생성된 외부 거래 토큰이 있어야 합니다. 사용자가 외부 쿠폰 API를 통해 외부 웹사이트를 방문할 때마다 새 외부 거래 토큰을 생성해야 합니다. 이렇게 하려면 createExternalOfferReportingDetailsAsync API를 호출하면 됩니다. 이 토큰은 사용자가 앱 외부로 연결되기 직전에 생성되어야 합니다. 이 토큰은 절대 캐시되면 안 되며 사용자가 앱 외부로 연결될 때마다 새 토큰을 생성해야 합니다.

Kotlin


billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

Java


billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

사용자를 위한 정보 대화상자

외부 제품과 통합하려면 자격요건을 충족하는 앱에서 사용자가 앱 외부에서 외부 웹사이트로 이동하려고 함을 알리는 정보 화면을 표시해야 합니다. 정보 화면은 매번 외부 혜택에 연결하기 전에 showExternalOfferInformationDialog API를 호출하여 사용자에게 표시되어야 합니다.

Kotlin


// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

Java


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

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

이 메서드가 BillingResponseCode.OK를 반환하면 앱에서 사용자를 외부 웹사이트로 안내할 수 있습니다. 메서드가 BillingResponseCode.USER_CANCELED를 반환하면 앱에서 웹사이트를 계속 열면 안 됩니다.

Google Play에 거래 보고

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

응답 처리

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

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

외부 제품 테스트

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

다음 단계

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