Встроенные в приложение инструкции по выбору способа оплаты.

В этом руководстве описано, как интегрировать ваше приложение с API библиотеки Play Billing, чтобы предоставить пользователям возможность выбора способа оплаты .

Интеграция с PBL

Интеграция выбора способа оплаты с PBL возможна в четырех сценариях. Сценарии различаются в зависимости от того, кто отображает экран выбора и где будет производиться оплата. В следующей таблице описаны сценарии интеграции:

Где происходит оплата?
В приложении Внешняя веб-ссылка
Какой экран выбора способа оплаты вы хотите отобразить? Google Play Сценарий 1А

Google отображает экран выбора, а альтернативный способ оплаты обрабатывается внутри вашего приложения .

 Сценарий 1Б

Разработчик приложения отображает экран выбора, а альтернативный способ оплаты обрабатывается внутри вашего приложения .

Ваш собственный (в соответствии с рекомендациями по UX) Сценарий 2А

Google отображает экран выбора, и пользователь переходит за пределы вашего приложения на ваши собственные веб-сайты для совершения покупок.

 Сценарий 2Б

Разработчик приложения отображает экран выбора, и пользователь переходит за пределы вашего приложения на ваши собственные веб-сайты для совершения покупок.

Следующая иллюстрация наглядно демонстрирует процесс выбора способа оплаты для каждого из этих сценариев:

Схема выбора способа оплаты, показывающая последовательность вызовов API и взаимодействий пользователя для четырех сценариев интеграции.
Рисунок 1. Сценарии интеграции вариантов оплаты.

Сценарии интеграции PBL

В зависимости от сценария интеграции, выполните действия, описанные в этом разделе, чтобы реализовать возможность выбора способа оплаты в вашем приложении.

Рассмотрите сценарий 1A.

Google отображает экран выбора способа оплаты, а альтернативный способ оплаты обрабатывается внутри вашего приложения. Выполните следующие шаги, чтобы включить возможность выбора способа оплаты в этом случае:

  1. При создании экземпляра BillingClient вызовите enableBillingProgram с EnableBillingProgramParams , а затем установите соединение. Например:

    Котлин 

    
// Build the parameters to enable the Billing Choice program and assign the listener
// to handle user selection of the developer-provided billing option.
val params = EnableBillingProgramParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
    .build()

// Build the parameters to enable support for pending purchases.
val pendingPurchasesParams = PendingPurchasesParams.newBuilder()
    .enableOneTimeProducts()
    .build()

// Construct the BillingClient instance with the purchases updated listener,
// pending purchases support, and the billing choice params.
val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(pendingPurchasesParams)
    .enableBillingProgram(params)
    .build()

// Establish a connection to Google Play
val billingResult = suspendCancellableCoroutine { continuation ->
    billingClient.startConnection(object : BillingClientStateListener {
        // Called when the connection setup process completes.
        override fun onBillingSetupFinished(billingResult: BillingResult) {
            // Resume the coroutine and pass back the BillingResult to the caller.
            continuation.resume(billingResult)
        }

        // Called if the connection to the Play Store service is dropped.
        // This prevents the await or suspension point from hanging indefinitely.
        override fun onBillingServiceDisconnected() {
            continuation.resume(
                BillingResult.newBuilder()
                    .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                    .setDebugMessage("Billing service disconnected during connection setup")
                    .build()
            )
        }
    })
}

    Java 

    
EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
        .build();

BillingClient billingClient = BillingClient.newBuilder(context)
        .setListener(purchasesUpdatedListener)
        .enablePendingPurchases(
                PendingPurchasesParams.newBuilder()
                        .enableOneTimeProducts()
                        .build()
        )
        .enableBillingProgram(params)
        .build();

  2. Убедитесь, что пользователю доступен вариант оплаты, отображаемый Google.

    Для проверки доступности программы вызовите isBillingProgramAvailableAsync , а затем метод queryProductDetailsAsync для отображения доступных продуктов. Например:

    Котлин 

    
val (billingResult, billingProgramAvailabilityDetails) = billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)

if (billingResult.responseCode == BillingResponseCode.OK) {
    val billingChoiceAvailabilityDetails = billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails
    if (billingChoiceAvailabilityDetails != null &&
        billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.GOOGLE_RENDERED
    ) {
        // Billing choice is available. Query products and proceed.

    } else {
        // Fallback to other available programs.
    }
} else {
    // Fallback to other available programs.
}

    Java 

    
// ...
billingClient.isBillingProgramAvailableAsync(
    BillingProgram.BILLING_CHOICE,
    (billingResult, billingProgramAvailabilityDetails) -> {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();

            if (billingChoiceAvailabilityDetails != null &&
                billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.GOOGLE_RENDERED) {
                // Billing choice is available. Query products and proceed.
            } else {
                // Fallback to other available programs.
            }
        } else {
            // Fallback to other available programs.
        }
    }
);

    Примечание : billingProgramAvailabilityDetails показывает, доступен ли экран выбора способа оплаты, созданный Google или разработчиком.

  3. Вызовите launchBillingFlow , чтобы запустить процесс покупки, когда пользователь нажмет кнопку «Купить». Если доступен выбор способа оплаты, передайте DeveloperBillingOptionParams в BillingFlowParams . Например:

    Котлин 

    
val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .build()

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .enableDeveloperBillingOption(developerBillingOptionParams)
    .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

    Java 

    
DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .build();
BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .enableDeveloperBillingOption(developerBillingOptionParams)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

    Примечание : Родительский контроль отображается для пользователей, находящихся под присмотром .

  4. Обработайте выбор пользователем типа оплаты следующим образом:

    • Если пользователь выбирает опцию «Платежи через Play», результат выставления счета возвращается объекту PurchasesUpdatedListener зарегистрированному на шаге 1.
    • Если пользователь выберет ваш альтернативный способ оплаты, результат выставления счета будет возвращен зарегистрированному на шаге 1 объекту DeveloperProvidedBillingListener В этом случае возвращаемый объект DeveloperProvidedBillingDetails будет содержать externalTransactionToken . Этот токен будет использоваться для формирования отчетов о транзакциях.

Рассмотрите сценарий 1B.

Разработчик отображает экран выбора способа оплаты, а альтернативный способ оплаты обрабатывается внутри вашего приложения. Выполните следующие шаги, чтобы включить возможность выбора способа оплаты в этом сценарии:

  1. Вызовите enableBillingProgram без указания DeveloperProvidedBillingListener в EnableBillingProgramParams при создании экземпляра BillingClient , а затем установите соединение. Например:

    Котлин 

    
// Build the parameters to enable the Billing Choice program.
val params = EnableBillingProgramParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .build()

// Construct the BillingClient instance with the purchases updated listener,
// pending purchases support, and the billing choice params.
val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(params)
    .build()

// Establish a connection to Google Play
val billingResult = suspendCancellableCoroutine<BillingResult> { continuation ->
    billingClient.startConnection(object : BillingClientStateListener {
        // Called when the connection setup process completes.
        override fun onBillingSetupFinished(billingResult: BillingResult) {
            // Resume the coroutine and pass back the BillingResult to the caller.
            continuation.resume(billingResult)
        }

        // Called if the connection to the Play Store service is dropped.
        // This prevents the await or suspension point from hanging indefinitely.
        override fun onBillingServiceDisconnected() {
            continuation.resume(
                BillingResult.newBuilder()
                    .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                    .setDebugMessage("Billing service disconnected during connection setup")
                    .build()
            )
        }
    })
}

    Java 

    
EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .build();

BillingClient billingClient = BillingClient.newBuilder(context)
        .setListener(purchasesUpdatedListener)
        .enablePendingPurchases()
        .enableBillingProgram(params)
        .build();

  2. Убедитесь, что пользователю доступен вариант оплаты, предоставленный разработчиком.

    Для проверки доступности программы вызовите isBillingProgramAvailableAsync , а затем метод queryProductDetailsAsync для отображения доступных продуктов. Например:

    Котлин 

    
val (billingResult, billingProgramAvailabilityDetails) =
    billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)

if (billingResult.responseCode == BillingResponseCode.OK) {
    val billingChoiceAvailabilityDetails =
        billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails

    if (billingChoiceAvailabilityDetails != null &&
        billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.DEVELOPER_RENDERED
    ) {
        // Billing choice is available. Query products and proceed.
        // You can inspect details such as:
        // - billingChoiceAvailabilityDetails.choiceScreenType
        // - billingChoiceAvailabilityDetails.isExternalLinkAvailable
    } else {
        // Fallback to other available programs.
    }
} else {
    // Fallback to other available programs.
}

    Java 

    
// ...
billingClient.isBillingProgramAvailableAsync(
    BillingProgram.BILLING_CHOICE,
    (billingResult, billingProgramAvailabilityDetails) -> {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();

            if (billingChoiceAvailabilityDetails != null
                    && billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.DEVELOPER_RENDERED) {
                // Billing choice is available. Query products and proceed.
                // You can inspect details such as:
                // - billingChoiceAvailabilityDetails.getChoiceScreenType()
                // - billingChoiceAvailabilityDetails.isExternalLinkAvailable()
            } else {
                // Fallback to other available programs.
            }
        } else {
            // Fallback to other available programs.
        }
    }
);

    Примечание : billingProgramAvailabilityDetails показывает, доступен ли экран выбора способа оплаты, созданный Google или разработчиком.

  3. Вызовите метод getBillingChoiceInfoAsync , чтобы получить баннер Play Billing и информацию о программе лояльности. Например:

    Котлин 

    
// 1. Create the params required for the request
val params = GetBillingChoiceInfoParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
    .build()

// 2. Call the suspend method on your billingClient instance
val (billingResult, playBillingChoiceInfo) = billingClient.getBillingChoiceInfo(params)

if (billingResult.responseCode == BillingResponseCode.OK && playBillingChoiceInfo != null) {
    // Access the URL of the image associated with the Play Billing Choice
    val imageUrl = playBillingChoiceInfo.playBillingChoiceImageUrl

    // Access the Play Loyalty string information, if available
    val loyaltyInfo = playBillingChoiceInfo.playBillingLoyaltyInfo

    // Populate your developer-rendered UI elements
    playBillingLoyaltyTextView.text = loyaltyInfo
    loadImage(imageUrl, playBillingImageView)
} else {
    // Handle error scenarios
}

    Java 

    
// 1. Create the params required for the request
GetBillingChoiceInfoParams params = GetBillingChoiceInfoParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
    .build();
// 2. Call the method asynchronously on your billingClient instance
billingClient.getBillingChoiceInfoAsync(params, (billingResult, playBillingChoiceInfo) -> {
    if (billingResult.getResponseCode() == BillingResponseCode.OK && playBillingChoiceInfo != null) {
      // Access the URL of the image associated with the Play Billing Choice
        String imageUrl = playBillingChoiceInfo.getPlayBillingChoiceImageUrl();
        // Access the Play Loyalty string information, if available
        String loyaltyInfo = playBillingChoiceInfo.getPlayBillingLoyaltyInfo();

        // Populate your developer-rendered UI elements
        playBillingLoyaltyTextView.setText(loyaltyInfo);
          loadImage(imageUrl, playBillingImageView);
      } else {
          // Handle error scenarios
      }
});

  4. Создайте внешний токен транзакции с параметром DeveloperBillingType, установленным в значение IN_APP . Например:

    Котлин 

    
// Build the parameters specifying the billing program and that the billing type is IN_APP.
val params = BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .setDeveloperBillingType(DeveloperBillingType.IN_APP)
    .build()

// Call the suspending extension function to request the reporting details
val (billingResult, billingProgramReportingDetails) =
    billingClient.createBillingProgramReportingDetails(params)
    
if (billingResult.responseCode != BillingResponseCode.OK) {
    // Handle failures such as retrying due to network errors.
    return
}

// Extract the transaction token from the returned reporting details
val transactionToken = billingProgramReportingDetails?.externalTransactionToken

// Persist the external transaction token locally. Pass it to
// DeveloperBillingOptionParams when launchBillingFlow is called.
// It can also be used as part of your external website

    Java 

    
BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.IN_APP)
        .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
            // DeveloperBillingOptionParams when launchBillingFlow is called.
            // It can also be used as part of your external website
        }
    }
);

  5. Когда пользователь нажимает кнопку «Купить», вызовите метод showBillingProgramInformationDialog , чтобы отобразить информационное диалоговое окно. Например, см. раздел «Информационное диалоговое окно для пользователей» . Параметры BillingProgram и transactionToken из шага 4 должны быть указаны в запросе.

    Примечание : Родительский контроль отображается для пользователей, находящихся под присмотром .

  6. Если результат предыдущего шага вас OK , запустите экран выбора альтернативного способа оплаты.

  7. Обработайте выбор пользователем типа оплаты следующим образом:

    • Если пользователь выбирает Play Billing, вызовите launchBillingFlow в соответствии со стандартными рекомендациями Play Billing . Результат выставления счетов возвращается в PurchasesUpdatedListener зарегистрированный на шаге 1.
    • Если пользователь выберет ваш альтернативный способ оплаты, вы должны самостоятельно обработать транзакцию и сообщить о ней в Play, используя токен, сгенерированный на шаге 4.

Рассмотрите сценарий 2А

Google отображает экран выбора способа оплаты, а альтернативный способ оплаты обрабатывается вне вашего приложения. Выполните следующие шаги, чтобы включить возможность выбора способа оплаты в этом случае:

  1. При создании экземпляра BillingClient вызовите enableBillingProgram с EnableBillingProgramParams , а затем установите соединение. Например:

    Котлин 

    
// Build the parameters to enable the Billing Choice program and assign the listener
// to handle user selection of the developer-provided billing option.
val params = EnableBillingProgramParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
    .build()

// Build the parameters to enable support for pending purchases.
val pendingPurchasesParams = PendingPurchasesParams.newBuilder()
    .enableOneTimeProducts()
    .build()

// Construct the BillingClient instance with the purchases updated listener,
// pending purchases support, and the billing choice params.
val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(pendingPurchasesParams)
    .enableBillingProgram(params)
    .build()

// Establish a connection to Google Play
val billingResult = suspendCancellableCoroutine { continuation ->
    billingClient.startConnection(object : BillingClientStateListener {
        // Called when the connection setup process completes.
        override fun onBillingSetupFinished(billingResult: BillingResult) {
            // Resume the coroutine and pass back the BillingResult to the caller.
            continuation.resume(billingResult)
        }

        // Called if the connection to the Play Store service is dropped.
        // This prevents the await or suspension point from hanging indefinitely.
        override fun onBillingServiceDisconnected() {
            continuation.resume(
                BillingResult.newBuilder()
                    .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                    .setDebugMessage("Billing service disconnected during connection setup")
                    .build()
            )
        }
    })
}

    Java 

    
EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
        .build();

BillingClient billingClient = BillingClient.newBuilder(context)
        .setListener(purchasesUpdatedListener)
        .enablePendingPurchases(
                PendingPurchasesParams.newBuilder()
                        .enableOneTimeProducts()
                        .build()
        )
        .enableBillingProgram(params)
        .build();

  2. Проверьте наличие следующих элементов:

    • Google предоставил возможность выбора способа оплаты.
    • Внешняя веб-ссылка

    Для проверки доступности программы вызовите isBillingProgramAvailableAsync , а затем метод queryProductDetailsAsync для отображения доступных продуктов. Например:

    Котлин 

    
// Check the availability of the billing choice program asynchronously using coroutines
val (billingResult, billingProgramAvailabilityDetails) =
    billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)

// Ensure the billing program query succeeded
if (billingResult.responseCode == BillingResponseCode.OK) {
    // Retrieve the availability details specific to the billing choice program
    val billingChoiceAvailabilityDetails =
        billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails

    // Check if billing choice is available, renders via Google Play, and external link is supported
    if (billingChoiceAvailabilityDetails != null &&
        billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.GOOGLE_RENDERED &&
        billingChoiceAvailabilityDetails.isExternalLinkAvailable
    ) {
        // Billing choice is available and external transaction links are supported. Query products and proceed.
    } else {
        // Fallback to other available programs.
    }
} else {
    // Fallback to other available programs.
}

    Java 

    
// ...
billingClient.isBillingProgramAvailableAsync(
    BillingProgram.BILLING_CHOICE,
    (billingResult, billingProgramAvailabilityDetails) -> {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();

            if (billingChoiceAvailabilityDetails != null
                    && billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.GOOGLE_RENDERED
                    && billingChoiceAvailabilityDetails.isExternalLinkAvailable()) {
                // Billing choice is available and external transaction links are supported.
                // Query products and proceed.
            } else {
                // Fallback to other available programs.
            }
        } else {
            // Fallback to other available programs.
        }
    }
);

  3. Вызовите метод createBillingProgramReportingDetailsAsync для создания внешнего токена транзакции, когда пользователь выразит намерение совершить покупку. Например:

    Котлин 

    
// Build the parameters for creating reporting details
val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
        .build()

// Call the suspend function to create billing program reporting details
val (billingResult, billingProgramReportingDetails) =
    billingClient.createBillingProgramReportingDetails(params)

// Handle response failure cases
if (billingResult.responseCode != BillingResponseCode.OK) {
    // Handle failures such as retrying due to network errors.
    return
}

// Retrieve the external transaction token
val transactionToken =
    billingProgramReportingDetails?.externalTransactionToken

// Persist the external transaction token locally. Pass it to
// DeveloperBillingOptionParams when launchBillingFlow is called.
// It can also be used as part of your external website

    Java 

    
BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_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
            // DeveloperBillingOptionParams when launchBillingFlow is called.
            // It can also be used as part of your external website.
        }
    }
);

  4. Вызовите launchBillingFlow , чтобы запустить процесс покупки, когда пользователь нажмет кнопку «Купить». Если пользователю доступен выбор способа оплаты, выполните следующие действия:

    1. Передайте DeveloperBillingOptionParams в BillingFlowParams .
    2. Передайте внешний токен транзакции из шага 3 в параметр DeveloperBillingOptionParams .

    Например:

    Котлин 

    
// Build the developer billing option parameters with the external link URI,
// the transaction token, and browser/app launch mode.
val developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
        .setExternalTransactionToken(transactionToken)
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
        )
        .build()

    Java 

    
DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
        .setExternalTransactionToken(transactionToken)
        .setLaunchMode(
          DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build();

    Примечание : Родительский контроль отображается для пользователей, находящихся под присмотром .

  5. Обработайте выбор пользователем типа оплаты следующим образом:

    • Если пользователь выбирает Play Billing, вызовите launchBillingFlow в соответствии со стандартными рекомендациями Play Billing . Результат выставления счетов возвращается в PurchasesUpdatedListener зарегистрированный на шаге 1.
    • Если пользователь выберет ваш альтернативный способ оплаты, результат выставления счета будет возвращен зарегистрированному на шаге DeveloperProvidedBillingListener
      1. Возвращаемое значение DeveloperProvidedBillingDetails содержит externalTransactionToken , который был передан в DeveloperBillingOptionParams на шаге 4, если это действительный токен.

Обработайте сценарий 2B

Разработчик отображает экран выбора способа оплаты, а альтернативный способ оплаты обрабатывается вне приложения. Выполните следующие шаги, чтобы включить возможность выбора способа оплаты в этом сценарии:

  1. Вызовите enableBillingProgram без указания DeveloperProvidedBillingListener в EnableBillingProgramParams при создании экземпляра BillingClient, а затем установите соединение. Например:

    Котлин 

    
// Build the parameters to enable the Billing Choice program.
val params = EnableBillingProgramParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .build()

// Construct the BillingClient instance with the purchases updated listener,
// pending purchases support, and the billing choice params.
val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(params)
    .build()

// Establish a connection to Google Play
val billingResult = suspendCancellableCoroutine<BillingResult> { continuation ->
    billingClient.startConnection(object : BillingClientStateListener {
        // Called when the connection setup process completes.
        override fun onBillingSetupFinished(billingResult: BillingResult) {
            // Resume the coroutine and pass back the BillingResult to the caller.
            continuation.resume(billingResult)
        }

        // Called if the connection to the Play Store service is dropped.
        // This prevents the await or suspension point from hanging indefinitely.
        override fun onBillingServiceDisconnected() {
            continuation.resume(
                BillingResult.newBuilder()
                    .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                    .setDebugMessage("Billing service disconnected during connection setup")
                    .build()
            )
        }
    })
}

    Java 

    
EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .build();

BillingClient billingClient = BillingClient.newBuilder(context)
        .setListener(purchasesUpdatedListener)
        .enablePendingPurchases()
        .enableBillingProgram(params)
        .build();

  2. Проверьте наличие следующих элементов:

    • Google предоставил возможность выбора способа оплаты.
    • Внешняя веб-ссылка

    Для проверки доступности программы вызовите isBillingProgramAvailableAsync , а затем метод queryProductDetailsAsync для отображения доступных продуктов. Например:

    Котлин 

    
// Check the availability of the billing choice program asynchronously using a coroutine
val (billingResult, billingProgramAvailabilityDetails) =
    billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)

// Ensure the response code is OK
if (billingResult.responseCode == BillingResponseCode.OK) {
    // Retrieve the billing choice availability details
    val billingChoiceAvailabilityDetails =
        billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails

    // Check if billing choice details are available, choice screen is developer-rendered,
    // and external transaction links are supported.
    if (billingChoiceAvailabilityDetails != null &&
        billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.DEVELOPER_RENDERED &&
        billingChoiceAvailabilityDetails.isExternalLinkAvailable
    ) {
        // Billing choice is available and external transaction links are supported.
        // Query products and proceed.
    } else {
        // Fallback to other available programs.
    }
} else {
    // Fallback to other available programs.
}

    Java 

    
// ...

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.BILLING_CHOICE,
    (billingResult, billingProgramAvailabilityDetails) -> {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();
            if (billingChoiceAvailabilityDetails != null &&
                billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.DEVELOPER_RENDERED &&
                billingChoiceAvailabilityDetails.isExternalLinkAvailable()) {
                // Billing choice is available and external transaction links are supported. Query products and proceed.
            } else {
                // Fallback to other available programs.
            }
        } else {
            // Fallback to other available programs.
        }
    }
);

  3. Вызовите метод getBillingChoiceInfoAsync , чтобы получить баннер Play Billing и информацию о программе лояльности.

    Котлин 

    
// 1. Create the params required for the request
val params = GetBillingChoiceInfoParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
    .build()

// 2. Call the suspend method on your billingClient instance
val (billingResult, playBillingChoiceInfo) = billingClient.getBillingChoiceInfo(params)

if (billingResult.responseCode == BillingResponseCode.OK && playBillingChoiceInfo != null) {
    // Access the URL of the image associated with the Play Billing Choice
    val imageUrl = playBillingChoiceInfo.playBillingChoiceImageUrl

    // Access the Play Loyalty string information, if available
    val loyaltyInfo = playBillingChoiceInfo.playBillingLoyaltyInfo

    // Populate your developer-rendered UI elements
    playBillingLoyaltyTextView.text = loyaltyInfo
    loadImage(imageUrl, playBillingImageView)
} else {
    // Handle error scenarios
}

    Java 

    
// 1. Create the params required for the request
GetBillingChoiceInfoParams params = GetBillingChoiceInfoParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
    .build();
// 2. Call the method asynchronously on your billingClient instance
billingClient.getBillingChoiceInfoAsync(params, (billingResult, playBillingChoiceInfo) -> {
    if (billingResult.getResponseCode() == BillingResponseCode.OK && playBillingChoiceInfo != null) {
      // Access the URL of the image associated with the Play Billing Choice
        String imageUrl = playBillingChoiceInfo.getPlayBillingChoiceImageUrl();
        // Access the Play Loyalty string information, if available
        String loyaltyInfo = playBillingChoiceInfo.getPlayBillingLoyaltyInfo();

        // Populate your developer-rendered UI elements
        playBillingLoyaltyTextView.setText(loyaltyInfo);
          loadImage(imageUrl, playBillingImageView);
      } else {
          // Handle error scenarios
      }
});

  4. Вызовите метод createBillingProgramReportingDetailsAsync для создания внешнего токена транзакции, когда пользователь выразит намерение совершить покупку. Например:

    Котлин 

    
// Build the parameters for creating reporting details
val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
        .build()

// Call the suspend function to create billing program reporting details
val (billingResult, billingProgramReportingDetails) =
    billingClient.createBillingProgramReportingDetails(params)

// Handle response failure cases
if (billingResult.responseCode != BillingResponseCode.OK) {
    // Handle failures such as retrying due to network errors.
    return
}

// Retrieve the external transaction token
val transactionToken =
    billingProgramReportingDetails?.externalTransactionToken

// Persist the external transaction token locally. Pass it to
// DeveloperBillingOptionParams when launchBillingFlow is called.
// It can also be used as part of your external website

    Java 

    
BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_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
            // DeveloperBillingOptionParams when launchBillingFlow is called.
            // It can also be used as part of your external website.
        }
    }
);

  5. При нажатии пользователем кнопки «Купить» отобразится экран с альтернативным вариантом выбора.

  6. Обработайте выбор пользователем типа оплаты следующим образом:

    • Если пользователь выбирает Play Billing, вызовите launchBillingFlow в соответствии со стандартными рекомендациями Play Billing . Результат выставления счетов возвращается в PurchasesUpdatedListener зарегистрированный на шаге 1.

      Функция родительского контроля отображается для пользователей, находящихся под присмотром .

    • Если пользователь выберет ваш альтернативный способ оплаты, вызовите метод launchExternalLink. Например:

      Котлин 

      
// An activity reference from which the purchase flow will be launched.
val activity: Activity = ...

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

// Call launchExternalLink with a callback
billingClient.launchExternalLink(activity, params) { billingResult ->
    if (billingResult.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the purchase 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.
    }
}

      Java 

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

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

LaunchExternalLinkResponseListener listener =
    new LaunchExternalLinkResponseListener() {
      @Override
      public void onLaunchExternalLinkResponse(BillingResult billingResult) {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
          // Proceed with the rest of the purchase 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);

    • Передайте внешний токен транзакции из шага 4 в функцию LaunchExternalLinkParams . Если она вернет OK, продолжите транзакцию и сообщите о ней в Google Play.

      Функция родительского контроля отображается для пользователей, находящихся под присмотром .

Выбор способа оплаты при замене подписки

При замене подписки экран выбора пользователя не должен отображаться, поскольку выбор пользователя при первоначальной покупке сохраняется при обновлении или понижении уровня подписки.

Если первоначальная покупка была оформлена через Google Play Billing , вам следует вызвать launchBillingFlow , указав стандартную информацию для замены подписки Google Play Billing .

Однако, если первоначальная покупка была оформлена через альтернативный способ выставления счетов , обработка замен подписки несколько отличается в зависимости от сценария.

Замена подписки в сценарии 1А

Пользователи, запрашивающие обновление или понижение версии тарифного плана, должны использовать альтернативную систему оплаты разработчика, минуя процедуру выбора варианта оплаты.

Для этого вызовите launchBillingFlow , когда пользователь запрашивает повышение или понижение уровня подписки. Используйте setOriginalExternalTransactionId внутри объекта SubscriptionUpdateParams в параметрах, чтобы указать внешний идентификатор транзакции для первоначальной покупки. При этом экран выбора пользователя не отображается, поскольку выбор пользователя для первоначальной покупки сохраняется для повышений и понижений уровня подписки. В этом случае вызов launchBillingFlow генерирует новый внешний токен транзакции , который можно получить из функции обратного вызова.

Котлин 


// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .build()

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
    )
    .enableDeveloperBillingOption(developerBillingOptionParams)
    .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the DeveloperProvidedBillingListener is triggered.

Java 


// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .build();

List<ProductDetailsParams> productDetailsParamsList = new ArrayList<>();
productDetailsParamsList.add(
    ProductDetailsParams.newBuilder()
        // Fetched using queryProductDetailsAsync.
        .setProductDetails(productDetailsNewPlan)
        // offerIdToken can be found in
        // ProductDetails=>SubscriptionOfferDetails
        .setOfferToken(offerTokenNewPlan)
        .build());

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                .setOriginalExternalTransactionId(externalTransactionId)
                .build())
        .enableDeveloperBillingOption(developerBillingOptionParams)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the DeveloperProvidedBillingListener is triggered.

После завершения обновления или понижения версии необходимо отправить отчет о новой транзакции, используя внешний токен транзакции, полученный в ходе предыдущего вызова для покупки новой подписки.

Замена подписки в сценарии 1B

В этом сценарии необходимо сгенерировать новый внешний токен транзакции. Единственное отличие от обычной покупки заключается в том, что в этом сценарии сохраняется выбор пользователя, и вам не нужно показывать экран выбора обновления или понижения уровня подписки. Однако необходимо показать одноразовое информационное диалоговое окно и подтверждение родителей.

Пример кода интеграции см. на шаге 4 в сценарии 1B: разработчик отображает экран выбора, а альтернативный способ оплаты обрабатывается внутри вашего приложения .

После завершения обновления или понижения версии необходимо отправить отчет о новой транзакции, используя внешний токен транзакции, полученный в ходе предыдущего вызова для покупки новой подписки.

Замена подписки в сценарии 2А

Для подписок, первоначально приобретенных через веб-сайт разработчика или платежное приложение после выбора пользователем, пользователи, запрашивающие повышение или понижение уровня подписки, должны продолжить оформление через веб-сайт разработчика или платежное приложение, минуя повторный процесс выбора пользователем.

Для этого вызовите launchBillingFlow , когда пользователь запросит повышение или понижение уровня подписки. Вместо указания других параметров в объекте SubscriptionUpdateParams используйте setOriginalExternalTransactionId , указав внешний идентификатор транзакции для первоначальной покупки. В этом вызове также необходимо указать DeveloperBillingOptionParams . Это не отобразит экран выбора пользователя, поскольку выбор пользователя для первоначальной покупки сохраняется для повышений и понижений уровня подписки. Например:

Котлин 


val externalTransactionId = //... ;

// 1. Construct DeveloperBillingOptionParams indicating the billing program
val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .build()

// 2. Build BillingFlowParams combining DeveloperBillingOptionParams and SubscriptionUpdateParams
val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
    )
    .enableDeveloperBillingOption(developerBillingOptionParams)
    .build()

Java 


String externalTransactionId = //... ;

// 1. Construct DeveloperBillingOptionParams indicating the billing program
DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
        .build();

// 2. Add ProductDetailsParams
List productDetailsParamsList = new ArrayList<>();
productDetailsParamsList.add(
    ProductDetailsParams.newBuilder()
        // Fetched using queryProductDetailsAsync.
        .setProductDetails(productDetailsNewPlan)
        // offerIdToken can be found in ProductDetails=>SubscriptionOfferDetails
        .setOfferToken(offerTokenNewPlan)
        .build());

// 3. Build BillingFlowParams combining DeveloperBillingOptionParams and SubscriptionUpdateParams
BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                .setOriginalExternalTransactionId(externalTransactionId)
                .build())
        .enableDeveloperBillingOption(developerBillingOptionParams)
        .build();

Вам также необходимо сгенерировать новый внешний токен транзакции. Например:

Котлин 


val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_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 using DeveloperBillingOptionParams when
            // launchBillingFlow is called.
        }
    }
)

Java 


BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_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 using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
      }
    });

После генерации нового токена необходимо вызвать метод launchBillingFlow для запуска процесса покупки.

После завершения обновления или понижения версии необходимо отправить отчет о новой транзакции, используя внешний токен транзакции, полученный в ходе предыдущего вызова для покупки новой подписки.

Замена подписки в сценарии 2B

В этом сценарии действия по замене подписки аналогичны действиям, описанным в разделе «Замена подписки в сценарии 2A» . Единственное отличие заключается в том, что после генерации токена транзакции вместо вызова метода launchBillingFlow необходимо вызвать метод launchExternalLink для отображения диалогового окна с отказом от ответственности. В этом сценарии выбор пользователя сохраняется, и вам не нужно показывать экран выбора между повышением и понижением уровня подписки.

Пример кода интеграции см. на шаге 6 в сценарии 2B: разработчик отображает экран выбора, а альтернативный способ оплаты обрабатывается внутри вашего приложения .

После завершения обновления или понижения версии необходимо отправить отчет о новой транзакции, используя внешний токен транзакции, полученный в ходе предыдущего вызова для покупки новой подписки.