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 Facturación Play para ofrecer vínculos a contenido externo en apps aptas. Esto incluye la capacidad de vincular a los usuarios de EE.UU. fuera de tu app de Play para proporcionarles ofertas de 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.1 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 a contenido externo.

Inicializa el cliente de facturación

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

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

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
            .build()
    )
    .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 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 verificar si el usuario es apto para el programa de vínculos a contenido externo llamando al isBillingProgramAvailableAsync() método. Este método muestra BillingResponseCode.OK si el usuario es apto para el programa de vínculos a contenido externo. En el siguiente ejemplo, se muestra cómo verificar la elegibilidad del usuario para los vínculos a contenido externo:

Kotlin

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.EXTERNAL_CONTENT_LINK,
    object : BillingProgramAvailabilityListener {
        override fun onBillingProgramAvailabilityResponse(
            billingResult: BillingResult,
            billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails
        ) {
            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 control de respuestas para obtener detalles sobre cómo tu app debe responder a otros códigos de respuesta. Si utilizas 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 Facturación Play. 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 vincule al usuario.

Nota: El token de transacción externa nunca debe almacenarse en caché, y debes generar un token nuevo cada vez que se vincule 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 utilizas extensiones de Kotlin, puedes usar corrutinas de Kotlin para no tener que definir un objeto de escucha independiente.

Inicia el vínculo externo

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

Cuando llames al método launchExternalLink, se deben proporcionar los detalles del vínculo externo 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. Para las descargas de apps, este vínculo debe registrarse y aprobarse en Play Console.
  • Tipo de vínculo : Es el tipo de contenido que se ofrece al usuario.
  • Modo de inicio : Especifica cómo se inicia el vínculo. Para las descargas de apps, debes configurarlo como LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.

  • Programa de facturación : Configúralo 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(), y createBillingProgramReportingDetailsAsync(), y onLaunchExternalLinkResponse() pueden proporcionar un BillingResponseCode que no sea 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 a 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 los vínculos a contenido externo y, por lo tanto, no debe continuar con este programa. Esto se debe a que el usuario no se encuentra 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 reintento adecuada. En el caso de SERVICE_DISCONNECTED, restablece una conexión con Google Play antes de volver a intentarlo.

Prueba los vínculos a contenido externo

Se deben usar verificadores con licencia para probar la integración de tus ofertas externas. No se te facturarán las transacciones que hayan iniciado las cuentas de verificadores con licencia. 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.