Guía de integración en la app para el programa de ofertas externas

En esta guía, se describe cómo realizar la integración con las APIs para admitir ofertas externas en apps y regiones aptas. Obtén más información sobre el programa de ofertas externas incluidos los requisitos de elegibilidad y el alcance geográfico, requisitos del programa.

Configuración de la Biblioteca de Facturación Play

Para usar las APIs de ofertas externas, agrega la versión 6.2.1 o una posterior de la dependencia de la Biblioteca de Facturación Play a tu app de Android. Si necesitas migrar desde una versión anterior, sigue siga las instrucciones de la guía de migración antes de intentar implementar ofertas externas.

Cómo conectarse a Google Play

Los primeros pasos del proceso de integración son los mismos que los descritos en la guía de integración de facturación, con algunas modificaciones cuando inicializando tu BillingClient:

• Debes llamar a un nuevo método para indicar que quieres usar ofertas: enableExternalOffer.

En el siguiente ejemplo, se muestra cómo inicializar un objeto BillingClient con estas modificaciones:

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

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

Después de inicializar el objeto BillingClient, debes establecer una conexión con Google Play, como se describe en la guía de integración.

Comprobar disponibilidad

Tu app debe confirmar que las ofertas externas están disponibles llamando isExternalOfferAvailableAsync

Esta API muestra BillingResponseCode.OK si hay ofertas externas disponibles. Consulta la sección de manejo de respuestas para obtener detalles sobre cómo tu app debe responder a otros códigos de respuesta.

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.
})

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.
      }

});

Prepara un token de transacción externo

Para denunciar una transacción externa a Google Play, debes tener una token de transacción generado desde la Biblioteca de Facturación Play. Un nuevo proveedor de token de transacción se debe generar cada vez que el usuario visita un a través de la API de ofertas externas. Para ello, se debe llamar al API de createExternalOfferReportingDetailsAsync. Este token debe ser generarse inmediatamente antes de que se dirija al usuario fuera de la app. Debe no se almacenan en caché, y se debe generar una nueva cada vez que se redirige al usuario fuera de la app.

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.
    }
})

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.
      }
});

Diálogo de información para los usuarios

Para integrar las ofertas externas, tu app apta debe mostrar una información en la pantalla, lo que ayuda a los usuarios a entender que están a punto de ser dirigidos la aplicación a un sitio web externo. La pantalla de información se debe mostrar a los usuarios Llamar a la API de showExternalOfferInformationDialog antes de realizar la vinculación a un una oferta externa cada vez.

// 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)

// 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);

Si este método devuelve BillingResponseCode.OK, tu app puede continuar con dirigir al usuario al sitio web externo. Si el método devuelve BillingResponseCode.USER_CANCELED, tu app no debe seguir abriendo la app sitio web.

Cómo informar transacciones a Google Play

Todas las transacciones externas se deben informar a Google Play llamando a la API de Google Play Developer desde tu backend. Transacciones externas debe informarse cuando se proporcione un externalTransactionToken obtenidos mediante el API de createExternalOfferReportingDetailsAsync. Si un usuario realiza varias compras, puedes utilizar la misma externalTransactionToken para informar cada compra. Para aprender a denunciar un consulta la guía de integración del backend.

Control de respuestas

Cuando se produce un error, los métodos isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync y showExternalOfferInformationDialog podría mostrar respuestas que no sean BillingResponseCode.OK Considera manejar estos códigos de respuesta de la siguiente manera:

• ERROR: Este es un error interno. No continúes con la transacción o abriendo el sitio web externo. Llama para volver a intentarlo showExternalOfferInformationDialog() para mostrar la información al usuario la próxima vez que intentes dirigirlo fuera del .
• FEATURE_NOT_SUPPORTED: Las APIs de ofertas externas no son compatibles con la Play Store en el dispositivo actual. No continúes con la transacción o abriendo el sitio web externo.
• USER_CANCELED: No continúes con la apertura del sitio web externo. Llamada showExternalOfferInformationDialog() de nuevo para mostrar la información al usuario la próxima vez que intentes dirigirlo fuera de la aplicación.
• BILLING_UNAVAILABLE: La transacción no es apta para ofertas externas. por lo que no deberías continuar con este programa. Esto se debe a que el usuario no está en un país apto para este programa o tu cuenta tiene no se inscribió correctamente en el programa. Si es la última opción, el estado de tu inscripción en Play Console.
• DEVELOPER_ERROR: Se produjo un error con la solicitud. Usa el mensaje de depuración para identificar y corregir el error antes de continuar.
• NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: Son errores transitorios que se deben manejar con una política de reintento adecuada. En el caso de SERVICE_DISCONNECTED, restablece una conexión con Google Play antes de volver a intentarlo.

Prueba las ofertas externas

Los verificadores de licencias deben usarse para probar la integración de ofertas externas. Tú no se facturarán las transacciones que haya iniciado el verificador con licencia cuentas de servicio. Para obtener más información, consulta Prueba la facturación integrada con licencias de aplicaciones. información sobre la configuración de verificadores con licencia.

Próximos pasos

Una vez que termines la integración en la app, tendrás todo listo para integrar tu backend.