Guía de integración en la app para vínculos a contenido externo

En este documento, se describe cómo integrar las APIs de la Biblioteca de Play Billing para ofrecer vínculos a contenido externo en las apps aptas. Esto incluye la capacidad de vincular a los usuarios de EE.UU. fuera de tu app de Play para ofrecerles contenido digital integrado en la app y descargas de apps. Para obtener más información sobre este programa, consulta los requisitos del programa.

Configuración de la Biblioteca de Facturación Play

Agrega la dependencia de la Biblioteca de Facturación Play a tu app para Android. Si quieres usar las APIs de vínculos externos, debes utilizar la versión 8.2 o una posterior. Si necesitas migrar desde una versión anterior, sigue las instrucciones de la guía de migración antes de agregar los vínculos de contenido externo.

Inicializa el cliente de facturación

Para inicializar el cliente de facturación, sigue los mismos pasos que se describen en Inicializa un BillingClient con las siguientes modificaciones:

  • No habilites PurchasesUpdatedListener, ya que este objeto de escucha no es necesario para los vínculos de contenido externo.
  • Llama a enableBillingProgram() con BillingProgram.EXTERNAL_CONTENT_LINK para indicar que tu app usa vínculos a contenido externo.

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

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

Cómo conectarse a Google Play

Después de inicializar el objeto BillingClient, conéctate a Google Play como se describe en Cómo conectarse a Google Play.

Verifica la elegibilidad del usuario

Después de conectarte a Google Play, debes llamar al método isBillingProgramAvailableAsync() para verificar si el usuario cumple con los requisitos del programa de vínculos a contenido externo. Este método devuelve BillingResponseCode.OK si el usuario cumple con los requisitos para participar en el programa de vínculos a contenido externo. En el siguiente ejemplo, se muestra cómo verificar si el usuario cumple con los requisitos para ver vínculos de contenido externo:

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

    });

Consulta la sección de manejo de respuestas para obtener detalles sobre cómo tu app debe responder a otros códigos de respuesta. Si usas extensiones de Kotlin, puedes usar corrutinas de Kotlin para no tener que definir un objeto de escucha independiente.

Prepara un token de transacción externa

A continuación, debes generar un token de transacción externa desde la biblioteca de Play Billing. Se debe generar un token de transacción externa nuevo cada vez que el usuario visite un sitio web externo a través de la API de vínculos externos. Para ello, llama a la API de createBillingProgramReportingDetailsAsync. El token se debe generar inmediatamente antes de que se redireccione al usuario.

Nota: El token de transacción externa nunca debe almacenarse en caché, y debes generar un token nuevo cada vez que se redireccione al usuario.

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

Si usas extensiones de Kotlin, puedes usar corrutinas de Kotlin para no tener que definir un objeto de escucha independiente.

Cómo iniciar el vínculo externo

Una vez que el token de transacción externa esté listo, se puede vincular al usuario fuera de la app a una oferta de contenido digital o a una descarga de app llamando al método launchExternalLink. Google Play podría renderizar diálogos de información adicionales para el usuario según su configuración cuando llames a esta API.

Cuando se llama al método launchExternalLink, los detalles del vínculo externo se deben proporcionar a través de LaunchExternalLinkParams. Esta clase contiene los siguientes parámetros:

  • URI del vínculo: Es el vínculo al sitio web externo en el que se ofrece el contenido digital o la descarga de la app. En el caso de las descargas de apps, este vínculo debe estar registrado y aprobado en Play Console.
  • Tipo de vínculo: Es el tipo de contenido que se ofrece al usuario.
  • Launch Mode: Especifica cómo se inicia el vínculo. En el caso de las descargas de aplicaciones, debes establecer este parámetro en LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.

  • Programa de facturación: Configura este campo como 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);

Control de respuestas

Cuando se produce un error, los métodos isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() y onLaunchExternalLinkResponse() pueden proporcionar un BillingResponseCode distinto de BillingResponseCode.OK. Considera controlar 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 la API o a launchExternalLink() la próxima vez que intentes dirigir al usuario fuera de la app.
  • FEATURE_NOT_SUPPORTED: Play Store no admite las APIs de vínculos de contenido externo en el dispositivo actual. No continúes con la transacción ni abras el sitio web externo.
  • USER_CANCELED: No continúes con la apertura del sitio web externo. Vuelve a llamar a launchExternalLink() la próxima vez que intentes dirigir al usuario fuera de la app.
  • BILLING_UNAVAILABLE: La transacción no es apta para vínculos a contenido externo 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 se deben controlar con una política de reintentos adecuada. En el caso de SERVICE_DISCONNECTED, restablece una conexión con Google Play antes de reintentarlo.

Prueba los vínculos a contenido externo

Los verificadores de licencias se deben usar para probar la integración de tus ofertas externas. No se te facturarán las transacciones que se hayan iniciado desde cuentas de verificadores de licencias. Consulta Prueba la facturación integrada con licencias de aplicaciones para obtener más información sobre cómo configurar los verificadores con licencia.

Próximos pasos

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