Controlar los mensajes de la store en el SDK de Flutter

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 sí solo mientras tu app está abierta.
Google Play: Un aviso de que el pago de una suscripción ha sido rechazado y el método de pago necesita actualizarse. Por defecto, el SDK de Adapty solicita estos mensajes cada vez que se inicia una Activity de tu app después de activate, incluso cuando la app vuelve al primer plano y cuando un flow u onboarding se abre o se cierra.

Ya sea de un modo u otro, un 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 showStoreMessages cuando un mensaje no interrumpa al usuario.

Warning

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

Antes de empezar

Necesitas:

Adapty Flutter SDK 4.3.0 o posterior: Las versiones anteriores no tienen la API de mensajes del store.
iOS 16 o posterior para mensajes del App Store: StoreKit no entrega mensajes a aplicaciones en versiones anteriores. En iOS 15, getPendingStoreMessageTypes y showStoreMessages fallan con el error decodingFailed, así que si tu app admite iOS 15, llama a estos métodos solo en iOS 16 y posterior.

Habilitar la gestión manual

Para mostrar los mensajes del store solo cuando tu app llama a showStoreMessages, llama a withStoreMessagesHandling con AdaptyStoreMessagesHandling.manual cuando actives el SDK:

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withStoreMessagesHandling(AdaptyStoreMessagesHandling.manual), // auto is the default
);

En iOS, el SDK añade cada mensaje del App Store a una lista de mensajes 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 del App Store, por lo que en iOS getPendingStoreMessageTypes y showStoreMessages no tienen nada que devolver ni mostrar.

Obtener los tipos de mensajes pendientes

En iOS, para saber si hay mensajes de la App Store en espera, llama a getPendingStoreMessageTypes. Devuelve los tipos de mensajes pendientes sin mostrarlos ni eliminarlos:

final pendingTypes = await Adapty().getPendingStoreMessageTypes();

if (pendingTypes == null) {
  // Android: Google Play decide si un mensaje aplica cuando lo muestras
} else if (pendingTypes.contains(AdaptyStoreMessageType.billingIssue)) {
  // Por ejemplo, omite el upsell y muestra primero el mensaje de facturación
}

En Android, el método devuelve null: Google Play no reporta 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 activate finalice, la lista siempre estará vacía.

Cada mensaje de App Store tiene uno de estos tipos:

Tipo	Mensaje
`AdaptyStoreMessageType.generic`	Un mensaje general de la App Store.
`AdaptyStoreMessageType.priceIncreaseConsent`	Una solicitud para aceptar un aumento de precio de la suscripción.
`AdaptyStoreMessageType.billingIssue`	Un aviso sobre un problema de facturación de la suscripción. Disponible en iOS 16.4 y versiones posteriores.
`AdaptyStoreMessageType.winBackOffer`	Una oferta de recuperación elegible. Disponible en iOS 18 y versiones posteriores.

Un tipo de mensaje que el SDK no reconoce tiene un value de storekit_<number>. Compara los tipos con == en lugar de asumir que estos cuatro tipos son los únicos.

Mostrar mensajes

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

try {
  await Adapty().showStoreMessages();
} on AdaptyError catch (adaptyError) {
  // handle the error
} catch (e) {
  // handle other errors
}

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 siguiente llamada y continúa con los demás mensajes.
Android: El SDK solicita mensajes de Google Play para la Activity actual. Google Play decide si un mensaje es aplicable al usuario, por lo que una solicitud no siempre muestra un mensaje. La llamada retorna de inmediato sin esperar a Google Play y nunca falla. Si el usuario corrige 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 inicia antes de activate no dispara una solicitud, por lo que los mensajes de Google Play no aparecen al arrancar. Para mostrarlos al inicio, llama a showStoreMessages una vez después de activate, solo en Android:


await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY'),
);

if (Platform.isAndroid) {
  await Adapty().showStoreMessages();
}

No hagas esta llamada en iOS: en el 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 en iosFilter. El resto de mensajes permanecen pendientes:

await Adapty().showStoreMessages(
  iosFilter: [
    AdaptyStoreMessageType.billingIssue,
    AdaptyStoreMessageType.priceIncreaseConsent,
  ],
);

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

Errores

En iOS, showStoreMessages falla con un AdaptyError con uno de estos códigos:

Código	Nombre	Causa
2006	`decodingFailed`	El dispositivo usa iOS 15 o anterior. Llama al método solo en iOS 16 o posterior.
3201	`operationInProgress`	Otra llamada a `showStoreMessages` sigue mostrando mensajes. Espera a que termine e inténtalo de nuevo.
3202	`resolverFailure`	El 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.