Cómo usar la Biblioteca de Facturación Google Play con Unity

El complemento de la Facturación Google Play extiende servicios y recursos integrados de Unity para compras directas desde la aplicación, denominados Unity IAP, para proporcionar a tu juego las funciones más recientes de la Biblioteca de Facturación Google Play. En esta guía, se explica la configuración de tu proyecto para usar el complemento. También se describe cómo implementar en Unity las funciones de la Biblioteca de Facturación Google Play en tu juego.

Cómo configurar el complemento de la Facturación Google Play

Para configurar el complemento, sigue los pasos de cada una de estas secciones vinculadas:

1. Habilita la capa de abstracción de Unity IAP.
2. Descarga e importa el complemento.
3. Configura las opciones de compilación del complemento.
4. Habilita el complemento.

Cómo habilitar la capa de abstracción de Unity IAP

El complemento de la Facturación Google Play se compila en una capa de abstracción incluida en Unity IAP, por lo que debes habilitar esa capa de abstracción antes de descargar e importar el complemento. Para habilitar la capa de abstracción de Unity IAP, haz lo siguiente:

1. Completa todos los pasos del siguiente instructivo de Unity: Set up your project for Unity Services.
2. Completa todos los pasos del siguiente instructivo de Unity: Enable the Unity IAP service.

Cómo descargar e importar el complemento

El complemento se envía como un paquete de Unity en formato .unitypackage. Para descargar e importar el complemento, sigue estos pasos:

1. Descarga la versión más reciente de Complementos de Google Play para Unity desde la página de versiones en GitHub del repositorio.

2. En la barra de menú de Unity, haz clic en Assets > Import Package > Custom Package.

   

3. Busca dónde se descargó el archivo .unitypackage y selecciónalo.

4. En el diálogo Import Unity Package, deja todos los elementos seleccionados y haz clic en Import.

   

Después de importar el paquete, se agrega una nueva carpeta llamada GooglePlayPlugins (en la raíz de la carpeta Assets) a los recursos del proyecto. Esa carpeta contiene todos los recursos de la Biblioteca de Facturación Google Play correspondientes al complemento.

Cómo configurar las opciones de compilación

Debido a que el complemento extiende Unity IAP, Unity tendrá conflictos y no podrá compilar un APK para Android, a menos que se quiten de la compilación algunas dependencias antiguas que se superponen en Unity IAP. El complemento sirve para quitar automáticamente las bibliotecas conflictivas de tu proyecto. Para resolver esos conflictos, sigue estos pasos:

1. En la barra de menú de Unity, selecciona Google > Play Billing > Build Settings.

   

2. En la ventana Play Billing Build Settings, haz clic en Fix. Esta acción resuelve el conflicto y mueve los archivos conflictivos de Unity IAP a un directorio de copia de seguridad. Después de hacer clic en Fix, el botón cambia a Restore, y puedes hacer clic en él para restablecer los archivos conflictivos originales.

   

Cómo habilitar el complemento

Para habilitar el complemento, reemplaza la implementación de Unity IAP de Google Play por el complemento de la Facturación Google Play. Por ejemplo, cuando se usa Unity IAP Purchaser Script, debes cambiar el objeto StandardPurchaseModule que se pasa al compilador de CDA para usar Google.Play.Billing.GooglePlayStoreModule:

// Create a builder using the GooglePlayStoreModule.
var configurationBuilder =
    ConfigurationBuilder.Instance(Google.Play.Billing.GooglePlayStoreModule.Instance());

Nota: Para evitar posibles conflictos con la implementación de CDA estándar de Unity, debes especificar completamente el espacio de nombres incluyendo Google.Play.Billing siempre que tu código haga referencia a las clases públicas del complemento de la Facturación Google Play. Todos los ejemplos de código de esta guía usan ese enfoque.

Si tu juego usa la misma versión de Purchaser Script para varias plataformas, deberías agregar una verificación de plataforma para garantizar que Unity siga usando su propia solución de CDA en otras plataformas:

ConfigurationBuilder builder;
if (Application.platform == RuntimePlatform.Android)
{
  builder = ConfigurationBuilder.Instance(
      Google.Play.Billing.GooglePlayStoreModule.Instance());
}
else
{
  builder = ConfigurationBuilder.Instance(StandardPurchasingModule.Instance());
}

Si publicas tu juego en otras tiendas de apps para Android además de Google Play Store, debes reemplazar la implementación predeterminada de Unity IAP solo cuando selecciones Google Play Store:

ConfigurationBuilder builder;
if (Application.platform == RuntimePlatform.Android
       && SelectedAndoidAppStore == AppStore.GooglePlay)
{
  builder = ConfigurationBuilder.Instance(
      Google.Play.Billing.GooglePlayStoreModule.Instance());
}
else
{
  builder = ConfigurationBuilder.Instance(StandardPurchasingModule.Instance());
}

Cómo implementar las funciones de la Biblioteca de Facturación Google Play en tu juego

El complemento de la Facturación Google Play extiende los servicios de Unity IAP, por lo que puedes usar las mismas APIs de Unity para administrar flujos de trabajo de compras comunes. Ten en cuenta que existen algunos cambios menores en el comportamiento de la API debido a diferencias entre la biblioteca de Google Play Billing y la implementación de CDA estándar de Unity para otras tiendas de aplicaciones. Si no conoces las APIs de Unity IAP, consulta la sección "Making a Purchase Script" del instructivo de Unity IAP para ver un ejemplo sobre la implementación de flujos de compra básicos.

La biblioteca de Google Play Billing también incluye algunas funciones exclusivas de Google Play Store. Puedes acceder a esas funciones mediante una interfaz extendida. El resto de esta sección describe la implementación de esas funciones únicas de la Biblioteca de Facturación Google Play en tu juego.

Cómo habilitar compras diferidas

Google Play admite compras diferidas, también denominadas compras o transacciones pendientes, en las que los usuarios pueden crear una compra y completarla más tarde con dinero en efectivo en tiendas físicas.

Si quieres habilitar las compras diferidas, usa el compilador de CDA para modificar la configuración de tu módulo llamando al método EnableDeferredPurchase():

// Create a builder using a GooglePlayStoreModule.
var configurationBuilder =
    ConfigurationBuilder.Instance(Google.Play.Billing.GooglePlayStoreModule.Instance());
// Enable deferred purchases
configurationBuilder.Configure<Google.Play.Billing.IGooglePlayConfiguration>()
    .EnableDeferredPurchase();

Luego, implementa una devolución de llamada de compras diferidas mediante las extensiones de Play Store:

// Get the plugin extensions for the Google Play Store.
_playStoreExtensions =
    extensions.GetExtension<Google.Play.Billing.IGooglePlayStoreExtensions>();

// Set the deferred purchases callback.
_playStoreExtensions.SetDeferredPurchaseListener(
    delegate(Product product)
    {
        // Do not grant the item here. Instead, record the purchase and remind
        // the user to complete the transaction in the Play Store.
    });

Cómo pasar IDs de cuentas ofuscados a Google Play

Puedes pasar IDs de cuentas de usuario ofuscados a Google Play para facilitar la detección de abusos, como detectar si varios dispositivos realizan compras en la misma cuenta en un período corto.

Nota: Este ID de cuenta también se devuelve con los datos de compra. Si para identificar a los usuarios usabas la carga útil para desarrolladores, puedes usar este ID de cuenta como alternativa.

Para pasar un ID de cuenta ofuscado, invoca el método SetObfuscatedAccountId() desde la API de extensiones:

// Get the plugin extensions for the Google Play Store.
_playStoreExtensions =
    extensions.GetExtension<Google.Play.Billing.IGooglePlayStoreExtensions>();

// Pass an obfuscated account ID.
_playStoreExtensions.SetObfuscatedAccountId(obfuscatedAccountId);

Cómo pasar IDs de perfiles ofuscados a Google Play

Puedes pasar un ID de un perfil ofuscado a Google Play para facilitar la detección de fraudes, como detectar si varios dispositivos realizan compras en la misma cuenta en un período corto. Esto es similar a pasar un ID de cuenta de usuario ofuscado. En ambos casos, el ID representa a un solo usuario, pero el ID de perfil te permite identificar de forma única a un solo usuario que usa varios perfiles en una misma app. Después de enviar un ID de perfil ofuscado a Google Play, puedes recuperar ese ID más tarde en un recibo de compra.

Para pasar un ID de perfil ofuscado, usa el compilador de CDA con el objetivo de modificar la configuración de tu módulo. Para ello, llama al método SetObfuscatedProfileId():

// Get the plugin extensions for the Google Play Store.
_playStoreExtensions =
    extensions.GetExtension<Google.Play.Billing.IGooglePlayStoreExtensions>();

// Pass an obfuscated profile ID.
_playStoreExtensions.SetObfuscatedProfileId(obfuscatedProfileId);

Cómo confirmar cambios en el precio de las suscripciones

Google Play te permite cambiar el precio de una suscripción activa. Los usuarios de tu juego deben confirmar cualquier cambio de precio antes de que se aplique la modificación. Para solicitar a los usuarios que confirmen un cambio de precio correspondiente a su suscripción, llama al método ConfirmSubscriptionPriceChange():

// Get the plugin extensions for the Google Play Store.
_playStoreExtensions =
    extensions.GetExtension<Google.Play.Billing.IGooglePlayStoreExtensions>();

_playStoreExtensions.ConfirmSubscriptionPriceChange(productId,
    delegate (bool success)
    {
        // Returns whether the user has accepted the new price or not.
    });

Cambios en el comportamiento de la API de Unity

Cuando usas el complemento de la Facturación Google Play, la mayoría de las APIs se comportan de la misma manera que la implementación de CDA estándar de Unity para otras tiendas de aplicaciones. Sin embargo, hay casos en los que las APIs se comportarán de manera diferente. En esta sección, se describen estas diferencias de comportamiento.

No se admite la carga útil para desarrolladores

Google Play dio de baja la carga útil para desarrolladores y la reemplazó por alternativas más significativas y contextuales. Por este motivo, ya no se admite la carga útil para desarrolladores. Si quieres obtener más información sobre las alternativas, consulta la página sobre Carga útil para desarrolladores.

Puedes seguir usando las mismas interfaces que define la implementación de CDA estándar de Unity para otras tiendas de aplicaciones, por ejemplo, IStoreController. Cuando inicias una compra, puedes usar IStoreController y llamar al método InitiatePurchase():

public void InitiatePurchase(Purchasing.Product product, string payload);

Sin embargo, no se aplicará ninguna carga útil que envíes (no aparecerá en el recibo final).

No se admite SubscriptionManager

Unity IAP proporciona la clase SubscriptionManager para administrar suscripciones. Debido a que la implementación de CDA estándar de Unity de esta clase usa la carga útil para desarrolladores, no se admite esta clase. Sin embargo, igual puedes crear esta clase, aunque es posible que recibas datos poco confiables cuando uses cualquiera de sus métodos get.

UpdateSubscription incluye pequeños cambios en la API

El complemento de la Facturación Google Play no admite el uso de los métodos SubscriptionManager.UpdateSubscription() y SubscriptionManager.UpdateSubscriptionInGooglePlayStore() para actualizar tus suscripciones ni para cambiarlas por una versión inferior. Si tu juego invoca esos métodos, se arroja un GooglePlayStoreUnsupportedException.

La Biblioteca de Facturación Google Play proporciona una API alternativa para usar en lugar de esos métodos. Para actualizar la categoría de una suscripción o cambiar a una versión inferior, llama al método UpdateSubscription() con el modo de prorrateo:

void UpdateSubscription(Product oldProduct, Product newProduct,
           GooglePlayStoreProrationMode prorationMode = GooglePlayStoreProrationMode.Unknown);

Puedes unir esta llamada de método con una verificación de plataforma o en un bloque de captura cuando se detecte GooglePlayStoreUnsupportedException.

Para obtener más información y ejemplos de cómo usar el modo de prorrateo, consulta cómo configurar el modo de prorrateo.