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. Para obtener más información sobre el programa de ofertas externas, incluidos los requisitos de elegibilidad y el alcance geográfico, consulta los 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 para Android. Si necesitas migrar desde una versión anterior, sigue 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 inicializas tu BillingClient:

• Debes llamar a un método nuevo para indicar que deseas usar ofertas externas: 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.

Consultar disponibilidad

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

Esta API muestra BillingResponseCode.OK si hay ofertas externas disponibles. Consulta 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 informar una transacción externa a Google Play, debes tener un token de transacción externo generado desde la Biblioteca de Facturación Play. Se debe generar un nuevo token de transacción externo cada vez que el usuario visite un sitio web externo a través de la API de ofertas externas. Para ello, se debe llamar a la API de createExternalOfferReportingDetailsAsync. Este token debe generarse inmediatamente antes de que se dirija al usuario fuera de la app. Nunca debe almacenarse en caché y se debe generar uno nuevo cada vez que se redirija 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 integrarse a ofertas externas, tu app apta debe mostrar una pantalla de información que ayude a los usuarios a comprender que están a punto de ser dirigidos fuera de la app a un sitio web externo. La pantalla de información se debe mostrar a los usuarios llamando a la API de showExternalOfferInformationDialog antes de vincular 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 proceder a dirigir al usuario al sitio web externo. Si el método muestra BillingResponseCode.USER_CANCELED, tu app no debe seguir abriendo el sitio web.

Cómo informar transacciones a Google Play

Todas las transacciones externas se deben informar a Google Play mediante una llamada a la API de Google Play Developer desde tu backend. Se deben informar las transacciones externas mientras se proporciona un externalTransactionToken obtenido con la API de createExternalOfferReportingDetailsAsync. Si un usuario realiza varias compras, puedes usar el mismo externalTransactionToken para informar cada compra. Si quieres obtener información para informar una transacción, consulta la guía de integración del backend.

Control de respuestas

Cuando se produce un error, los métodos isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync y showExternalOfferInformationDialog pueden mostrar respuestas distintas de 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 ni abras el sitio web externo. Vuelve a intentarlo llamando a showExternalOfferInformationDialog() para mostrar el diálogo de información al usuario la próxima vez que intentes dirigirlo fuera de la app.
• FEATURE_NOT_SUPPORTED: Play Store no admite las APIs de ofertas externas en el dispositivo actual. No continúes con la transacción ni abras el sitio web externo.
• USER_CANCELED: No abras el sitio web externo. Vuelve a llamar a showExternalOfferInformationDialog() para mostrarle al usuario el diálogo de información la próxima vez que intentes dirigirlo fuera de la app.
• BILLING_UNAVAILABLE: La transacción no es apta para ofertas externas y, por lo tanto, no debe continuar con este programa. Esto se debe a que el usuario no está en un país apto para este programa o a que tu cuenta no se inscribió correctamente en el programa. Si es la última opción, verifica el estado de 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: Estos son errores transitorios que deben manejarse 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.

Cómo probar ofertas externas

Los verificadores con licencia deben usarse para probar la integración de ofertas externas. No se te facturarán las transacciones que se hayan iniciado con cuentas de verificador con licencia. Consulta Prueba la facturación integrada con licencias de aplicaciones para obtener más información sobre la configuración de verificadores de licencias.

Próximos pasos

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