Controlar mensajes del store en Unity SDK

A veces App Store y Google Play necesitan mostrar a tus usuarios un mensaje sobre su suscripción:

  • App Store: Una solicitud de consentimiento para un aumento de precio, un aviso de problema de facturación o una oferta de recuperación. Por defecto, StoreKit muestra estos mensajes por su cuenta mientras la app está abierta.
  • Google Play: Un aviso de que el pago de una suscripción ha sido rechazado y de que es necesario actualizar el método de pago. A partir del SDK 4.3.0, el SDK de Adapty solicita estos mensajes por defecto cada vez que se inicia una Activity de tu app después de la activación, incluso cuando la app vuelve al primer plano y cuando un flow u onboarding se abre o se cierra.

De cualquier modo, el mensaje puede aparecer encima de un flow, un onboarding o un checkout. Para elegir el momento tú mismo, cambia el SDK a gestión manual de mensajes y llama a Adapty.ShowStoreMessages cuando el mensaje no interrumpa al usuario.

Warning

En modo manual, los stores no muestran mensajes por su cuenta. Si tu app nunca llama a Adapty.ShowStoreMessages, los usuarios nunca verán una solicitud de consentimiento de aumento de precio, un aviso de problema de facturación ni un aviso de pago rechazado.

Antes de empezar

Necesitas:

  • Adapty Unity SDK 4.3.0 o posterior: Las versiones anteriores no tienen la API de mensajes del store.
  • iOS 16 o posterior para los mensajes del App Store: StoreKit no entrega mensajes a las apps en versiones anteriores. En iOS 15, Adapty.GetPendingStoreMessageTypes y Adapty.ShowStoreMessages fallan con el error DecodingFailed, así que si tu app es compatible con iOS 15, llama a estos métodos solo en iOS 16 y posteriores:
#if UNITY_IOS && !UNITY_EDITOR
var iosMajorVersion = int.Parse(UnityEngine.iOS.Device.systemVersion.Split('.')[0]);
if (iosMajorVersion >= 16) {
    Adapty.ShowStoreMessages((error) => {
        // handle the error
    });
}
#endif

Habilitar la gestión manual

Para mostrar los mensajes de la store solo cuando tu app llame a Adapty.ShowStoreMessages, llama a SetStoreMessagesHandling con AdaptyStoreMessagesHandling.Manual cuando actives el SDK:

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetStoreMessagesHandling(AdaptyStoreMessagesHandling.Manual); // Auto is the default

Adapty.Activate(builder.Build(), (error) => {
    // handle the error
});

En iOS, el SDK añade cada mensaje de la App Store a una lista de pendientes para la sesión actual de la app. En Android, el SDK deja de solicitar mensajes de Google Play por su cuenta. Con el valor predeterminado Auto, el SDK no captura mensajes de la App Store, por lo que en iOS, Adapty.GetPendingStoreMessageTypes y Adapty.ShowStoreMessages no tienen nada que devolver ni mostrar.

Obtener tipos de mensajes pendientes

En iOS, para averiguar si hay mensajes del App Store en espera, llama a Adapty.GetPendingStoreMessageTypes. Devuelve los tipos de mensajes pendientes sin mostrarlos ni eliminarlos:

Adapty.GetPendingStoreMessageTypes((pendingTypes, error) => {
    if (error != null) {
        // handle the error
        return;
    }

    if (pendingTypes == null) {
        // Android: Google Play decides whether a message applies when you show it
    } else if (pendingTypes.Contains(AdaptyStoreMessageType.BillingIssue)) {
        // For example, skip the upsell and show the billing message first
    }
});

En Android, el método devuelve null sin error: Google Play no notifica los mensajes pendientes y decide si un mensaje aplica solo cuando tu app lo solicita. Una lista vacía significa que no hay mensajes pendientes en iOS. Hasta que Adapty.Activate finalice, la lista siempre estará vacía.

Cada mensaje de App Store tiene uno de estos tipos:

TipoMensaje
AdaptyStoreMessageType.GenericUn mensaje general de App Store.
AdaptyStoreMessageType.PriceIncreaseConsentUna solicitud para aceptar un aumento de precio de suscripción.
AdaptyStoreMessageType.BillingIssueUn aviso sobre un problema de facturación de suscripción. Disponible en iOS 16.4 y versiones posteriores.
AdaptyStoreMessageType.WinBackOfferUna oferta de recuperación elegible. Disponible en iOS 18 y versiones posteriores.

Los nuevos tipos de mensajes de StoreKit llegan con un RawValue de storekit_<number>. Para comprobar un tipo, compáralo con == con uno de los valores anteriores y trata cualquier otro valor como un tipo que el SDK no reconoce.

Mostrar mensajes

Cuando tu app llegue a un punto donde un mensaje de la store no interrumpa al usuario — por ejemplo, después de que cierre un flow o termine el onboarding — llama a Adapty.ShowStoreMessages:

Adapty.ShowStoreMessages((error) => {
    if (error != null) {
        // handle the error
    }
});
  • iOS: El SDK muestra los mensajes pendientes uno tras otro. Tras mostrar un mensaje, StoreKit lo elimina de la lista de pendientes. Si StoreKit no puede mostrar un mensaje, el SDK lo conserva para la próxima llamada y continúa con los demás mensajes.
  • Android: El SDK solicita los mensajes de Google Play para la Activity actual. Google Play decide si un mensaje aplica al usuario, por lo que una solicitud no siempre muestra un mensaje. Si el usuario actualiza su método de pago desde el mensaje, el SDK sincroniza las compras del usuario con Adapty y tu listener de perfil recibe el nivel de acceso actualizado.

Mostrar mensajes al iniciar en Android

En el modo predeterminado Auto, una Activity que se inició antes de la activación no desencadena una solicitud, por lo que los mensajes de Google Play no aparecen al iniciar la app. Para mostrarlos al iniciar, llama a Adapty.ShowStoreMessages una vez después de que Adapty.Activate finalice, solo en Android:

Adapty.Activate(builder.Build(), (error) => {
    if (error != null) {
        // handle the error
        return;
    }

#if UNITY_ANDROID
    Adapty.ShowStoreMessages((showError) => {
        // handle the error
    });
#endif
});

No hagas esta llamada en iOS: en modo Auto, no tiene nada que mostrar, y en iOS 15 falla.

Mostrar solo algunos tipos de mensajes

Para mostrar solo algunos de los mensajes pendientes del App Store, pasa los tipos como primer argumento. El resto de mensajes permanecerán pendientes:

var iosFilter = new List<AdaptyStoreMessageType> {
    AdaptyStoreMessageType.BillingIssue,
    AdaptyStoreMessageType.PriceIncreaseConsent,
};

Adapty.ShowStoreMessages(iosFilter, (error) => {
    // handle the error
});

Sin filtro, o con null, el SDK muestra todos los mensajes pendientes, incluidos los tipos que no reconoce. Una lista vacía no muestra ninguno. Android ignora el filtro y solicita todos los mensajes de Google Play.

Errores

Adapty.ShowStoreMessages puede fallar con un AdaptyError con uno de estos códigos. Todos ellos, excepto WrongParam, ocurren únicamente en iOS:

CódigoNombreCausa
2006DecodingFailedEl dispositivo ejecuta iOS 15 o anterior. Llama al método solo en iOS 16 o posterior.
3201OperationInProgressOtra llamada a Adapty.ShowStoreMessages sigue mostrando mensajes y esta llamada también tiene mensajes que mostrar. Espera a que termine la primera llamada e inténtalo de nuevo.
3202ResolverFailureEl SDK no encontró ninguna escena de ventana activa en primer plano para mostrar los mensajes. Llama al método de nuevo cuando tu app esté en primer plano.
3001WrongParamLa lista de filtros contiene null. El SDK rechaza la llamada antes de que llegue al store.