Obtener paywalls y productos personalizados en el SDK de Kotlin Multiplatform

Antes de mostrar paywalls personalizados, necesitas obtener información sobre ellos. Ten en cuenta que este tema se refiere a paywalls personalizados. Para obtener orientación sobre cómo obtener flows o paywalls personalizados en el Flow & Paywall Builder o el old Paywall Builder, consulta Obtener flows y paywalls.

Tip

¿Quieres ver un ejemplo real de cómo se integra el SDK de Adapty en una app móvil? Echa un vistazo a nuestras apps de ejemplo, que muestran la configuración completa, incluyendo la visualización de paywalls, la realización de compras y otras funcionalidades básicas.

Antes de comenzar a obtener flows y productos en tu app móvil (haz clic para expandir)
  1. Crea tus productos en el Adapty Dashboard.

  2. Crea un flow o paywall e incorpora los productos en él en el Adapty Dashboard.

  3. Crea placements e incorpora tu flow o paywall en el placement en el Adapty Dashboard.

  4. Instala el SDK de Adapty en tu aplicación móvil.

Obtener información del flow

En Adapty, un producto combina productos tanto de App Store como de Google Play. Estos productos multiplataforma se integran en flows y paywalls, lo que te permite mostrarlos en placements específicos de tu app móvil.

Para mostrar los productos, debes obtener un AdaptyFlow desde uno de tus placements con el método getFlow.

Important

No escribas los IDs de producto en el código. El único ID que debes incluir en el código es el ID del placement. Los flows se configuran de forma remota, por lo que el número de productos y las ofertas disponibles pueden cambiar en cualquier momento. Tu app debe gestionar estos cambios de forma dinámica: si un flow devuelve dos productos hoy y tres mañana, muéstralos todos sin modificar el código.


Adapty.getFlow(
    placementId = "YOUR_PLACEMENT_ID", 
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
    loadTimeout = 5.seconds
).onSuccess { flow ->
    // the requested flow
}.onError { error ->
    // handle the error
}
ParámetroPresenciaDescripción
placementIdobligatorioEl identificador del Placement. Es el valor que especificaste al crear un placement en tu Adapty Dashboard.
fetchPolicypredeterminado: AdaptyPaywallFetchPolicy.Default

fetchPolicy establece qué capa lee primero el SDK, no si puede usar la caché. Por defecto, el SDK va primero al servidor y devuelve los datos en caché si esa solicitud falla. Recomendamos esta opción porque garantiza que tus usuarios siempre reciban los datos más actualizados.

Sin embargo, si crees que tus usuarios tienen una conexión a internet inestable, considera AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad, que invierte ese orden: lee primero la caché y va al servidor solo cuando no hay nada en caché. Es posible que los usuarios no obtengan los datos más recientes, pero experimentarán tiempos de carga más rápidos, independientemente de lo inestable que sea su conexión. La caché se actualiza con regularidad, por lo que es seguro usarla durante la sesión para evitar solicitudes de red.

Una tercera política, AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis), se sitúa entre las dos: lee primero la caché mientras la copia almacenada sea más reciente que maxAgeMillis, y va al servidor una vez que sea más antigua.

Ten en cuenta que la caché permanece intacta al reiniciar la app y solo se borra cuando se reinstala la app o mediante una limpieza manual.

El SDK de Adapty almacena flows y paywalls en dos capas: la caché con actualización regular descrita anteriormente y los paywalls de respaldo. También usamos CDN para obtener flows y paywalls más rápido, y un servidor de respaldo independiente en caso de que el CDN no esté disponible. Este sistema está diseñado para garantizar que siempre obtengas la versión más reciente de tus flows y paywalls, asegurando la fiabilidad incluso cuando la conexión a internet es escasa.

loadTimeoutpredeterminado: 5 seg

Este valor limita el tiempo de espera para este método. Si se alcanza el tiempo de espera, se devolverán los datos en caché o el fallback local.

Ten en cuenta que en casos excepcionales este método puede agotar el tiempo de espera un poco más tarde de lo especificado en loadTimeout, ya que la operación puede estar compuesta por diferentes solicitudes internamente.

¡No escribas los IDs de producto en el código! Como los flows se configuran de forma remota, los productos disponibles, el número de productos y las ofertas especiales (como las pruebas gratuitas) pueden cambiar con el tiempo. Asegúrate de que tu código gestione estos escenarios.

Por ejemplo, si en un primer momento recuperas 2 productos, tu app debería mostrar esos 2 productos. Sin embargo, si más adelante recuperas 3 productos, tu app debería mostrar los 3 sin necesidad de modificar el código. Lo único que tienes que escribir en el código es el ID del placement.

Parámetros de respuesta:

ParámetroDescripción
FlowUn objeto AdaptyFlow con: el identificador del flow, las variaciones de paywall (paywalls — cada una con sus propios identificadores de producto), una lista remoteConfigs (una entrada por locale configurado) y varias otras propiedades. Para obtener los productos del flow, llama a getPaywallProducts(flow).
Note

En la v4, getFlow no tiene el parámetro locale. Cuando renderizas un flow con createFlowView, la localización se resuelve automáticamente. Para paywalls personalizados, todos los idiomas disponibles se devuelven juntos en flow.remoteConfigs — elige el idioma que coincida con el dispositivo del usuario o la configuración de tu app. Consulta Localizaciones y códigos de idioma para más detalles.

Obtener productos

Una vez que tengas el flow, puedes consultar el array de productos que le corresponde:

Adapty.getPaywallProducts(flow).onSuccess { products ->
    // the requested products
}.onError { error ->
    // handle the error
}

Parámetros de respuesta:

ParameterDescription
ProductsLista de objetos AdaptyPaywallProduct con: identificador del producto, nombre del producto, precio, moneda, duración de la suscripción y otras propiedades.

Al implementar tu propio diseño de flow, probablemente necesitarás acceder a estas propiedades del objeto AdaptyPaywallProduct. A continuación se ilustran las propiedades más utilizadas; consulta el documento enlazado para obtener todos los detalles sobre las propiedades disponibles.

PropiedadDescripción
TitlePara mostrar el título del producto, usa product.localizedTitle. Ten en cuenta que la localización se basa en el país del store seleccionado por el usuario, no en el idioma del dispositivo.
PricePara mostrar el precio localizado, usa product.price.localizedString. Esta localización se basa en la configuración regional del dispositivo. También puedes acceder al precio como número con product.price.amount. El valor se proporciona en la moneda local. Para obtener el símbolo de moneda correspondiente, usa product.price.currencySymbol.
Subscription PeriodPara mostrar el período (p. ej. semana, mes, año, etc.), usa product.subscriptionDetails?.localizedSubscriptionPeriod. Esta localización se basa en la configuración regional del dispositivo. Para obtener el período de suscripción de forma programática, usa product.subscriptionDetails?.subscriptionPeriod. Desde ahí puedes acceder al enum unit para conocer la unidad (es decir, DAY, WEEK, MONTH, YEAR o UNKNOWN). El valor numberOfUnits te dará el número de unidades del período. Por ejemplo, para una suscripción trimestral verías MONTH en la propiedad unit y 3 en la propiedad numberOfUnits.
Introductory OfferPara mostrar un badge u otro indicador de que una suscripción incluye una oferta introductoria, consulta la propiedad product.subscriptionDetails?.introductoryOfferPhases. Es una lista que puede contener hasta dos fases de descuento: la fase de prueba gratuita y la fase de precio introductorio. Dentro de cada objeto de fase encontrarás las siguientes propiedades útiles:
• paymentMode: un enum con los valores FREE_TRIAL, PAY_AS_YOU_GO, PAY_UPFRONT y UNKNOWN. Las pruebas gratuitas son del tipo FREE_TRIAL.
• price: el precio con descuento como número. Para las pruebas gratuitas, busca 0 aquí.
• localizedNumberOfPeriods: una cadena localizada con la configuración regional del dispositivo que describe la duración de la oferta. Por ejemplo, una oferta de prueba de tres días muestra 3 days en este campo.
• subscriptionPeriod: como alternativa, puedes obtener los detalles individuales del período de la oferta con esta propiedad. Funciona de la misma manera para las ofertas que lo descrito en la sección anterior.
• localizedSubscriptionPeriod: un período de suscripción formateado del descuento para la configuración regional del usuario.

Acelera la obtención de flows con el flow de audiencia predeterminada

Normalmente, los flows se obtienen casi de forma instantánea, por lo que no necesitas preocuparte por acelerar este proceso. Sin embargo, cuando tienes numerosas audiencias y placements, y tus usuarios tienen una conexión a internet débil, obtener un flow puede tardar más de lo deseado. En esas situaciones, puede que quieras mostrar un flow predeterminado para garantizar una experiencia de usuario fluida en lugar de no mostrar nada.

Para abordar esto, puedes usar el método getFlowForDefaultAudience, que obtiene el flow del placement especificado para la audiencia All Users. Sin embargo, es fundamental entender que el enfoque recomendado es obtener el flow mediante el método getFlow, tal como se detalla en la sección Obtener información del flow anterior.

Warning

Por qué recomendamos usar getFlow

El método getFlowForDefaultAudience tiene algunos inconvenientes importantes:

  • Posibles problemas de compatibilidad con versiones anteriores: Si necesitas mostrar flows distintos según la versión de la app (la actual y las futuras), puedes encontrarte con dificultades. Tendrás que diseñar flows que sean compatibles con la versión actual (legacy) o asumir que los usuarios de esa versión podrían tener problemas con flows que no se renderizan correctamente.
  • Pérdida de segmentación: Todos los usuarios verán el mismo flow diseñado para la audiencia All Users, lo que significa que pierdes la segmentación personalizada (incluyendo por países, atribución de marketing o tus propios atributos personalizados).

Si estás dispuesto a aceptar estas desventajas a cambio de una obtención de flows más rápida, usa el método getFlowForDefaultAudience como se indica a continuación. De lo contrario, usa getFlow descrito anteriormente.


Adapty.getFlowForDefaultAudience(
    placementId = "YOUR_PLACEMENT_ID",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default
).onSuccess { flow ->
    // the requested flow
}.onError { error ->
    // handle the error
}
ParámetroPresenciaDescripción
placementIdobligatorioEl identificador del Placement. Es el valor que especificaste al crear un placement en tu Adapty Dashboard.
fetchPolicypor defecto: AdaptyPaywallFetchPolicy.Default

fetchPolicy define qué capa lee primero el SDK, no si puede usar la caché. Por defecto, el SDK consulta primero el servidor y devuelve los datos en caché si esa solicitud falla. Recomendamos esta opción porque garantiza que los usuarios siempre reciban los datos más actualizados.

Sin embargo, si crees que tus usuarios tienen una conexión a internet inestable, considera AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad, que invierte ese orden: lee primero la caché y acude al servidor solo cuando no hay nada en caché. Es posible que los usuarios no obtengan los datos más recientes, pero la carga será más rápida independientemente de lo irregular que sea su conexión. La caché se actualiza con regularidad, por lo que es seguro usarla durante la sesión para evitar solicitudes de red.

Una tercera política, AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis), se sitúa entre las dos: lee primero la caché mientras la copia almacenada tiene menos de maxAgeMillis de antigüedad, y acude al servidor cuando es más antigua.

Ten en cuenta que la caché se conserva al reiniciar la app y solo se borra cuando se reinstala la app o mediante una limpieza manual.

Antes de mostrar paywalls personalizados, necesitas obtener la información sobre ellos. Ten en cuenta que este tema hace referencia a paywalls personalizados. Para obtener orientación sobre cómo obtener paywalls con Paywall Builder, consulta Obtener paywalls del Paywall Builder y su configuración.

Tip

¿Quieres ver un ejemplo real de cómo se integra el SDK de Adapty en una app móvil? Echa un vistazo a nuestras apps de ejemplo, que muestran la configuración completa, incluyendo la visualización de paywalls, la realización de compras y otras funcionalidades básicas.

Antes de empezar a obtener paywalls y productos en tu app (haz clic para expandir)
  1. Crea tus productos en el Adapty Dashboard.

  2. Crea un paywall e incorpora los productos en tu paywall en el Adapty Dashboard.

  3. Crea placements e incorpora tu paywall en el placement en el Adapty Dashboard.

  4. Instala el SDK de Adapty en tu aplicación móvil.

Obtén la información del paywall

En Adapty, un producto es una combinación de productos del App Store y Google Play. Estos productos multiplataforma se integran en paywalls, lo que te permite mostrarlos en placements específicos de tu aplicación móvil.

Para mostrar los productos, necesitas obtener un Paywall de uno de tus placements con el método getPaywall.

Important

No fijes los IDs de producto en el código. El único ID que debes incluir en el código es el ID del placement. Los paywalls se configuran de forma remota, por lo que el número de productos y las ofertas disponibles pueden cambiar en cualquier momento. Tu app debe gestionar estos cambios de forma dinámica: si un paywall devuelve dos productos hoy y tres mañana, muéstralos todos sin necesidad de modificar el código.


Adapty.getPaywall(
    placementId = "YOUR_PLACEMENT_ID", 
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default,
    loadTimeout = 5.seconds
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}
ParámetroPresenciaDescripción
placementIdobligatorioEl identificador del Placement. Es el valor que especificaste al crear un placement en tu Adapty Dashboard.
locale

opcional

por defecto: en

El identificador de la localización del paywall. Se espera que este parámetro sea un código de idioma compuesto por una o más subetiquetas separadas por el carácter menos (-). La primera subetiqueta corresponde al idioma y la segunda a la región.

Ejemplo: en significa inglés, pt-br representa el portugués de Brasil.

fetchPolicypor defecto: AdaptyPaywallFetchPolicy.Default

fetchPolicy determina qué capa lee primero el SDK, no si puede usar la caché. Por defecto, el SDK va primero al servidor y devuelve los datos en caché si esa solicitud falla. Recomendamos esta opción porque garantiza que tus usuarios siempre obtengan los datos más actualizados.

Sin embargo, si crees que tus usuarios tienen una conexión a internet inestable, considera AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad, que invierte ese orden: lee primero la caché y va al servidor solo cuando no hay nada en caché. Es posible que los usuarios no obtengan los datos más recientes, pero experimentarán tiempos de carga más rápidos, independientemente de lo inestable que sea su conexión. La caché se actualiza con regularidad, por lo que es seguro usarla durante la sesión para evitar peticiones de red.

Una tercera política, AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis), se sitúa entre las dos: lee primero la caché mientras la copia en caché sea más reciente que maxAgeMillis, y va al servidor cuando es más antigua.

Ten en cuenta que la caché permanece intacta al reiniciar la app y solo se borra cuando se reinstala la app o mediante una limpieza manual.

El SDK de Adapty almacena los paywalls en dos capas: la caché actualizada regularmente que se describe arriba y los paywalls de respaldo. También usamos CDN para obtener los paywalls más rápido y un servidor de respaldo independiente en caso de que el CDN sea inaccesible. Este sistema está diseñado para garantizar que siempre obtengas la última versión de tus paywalls, asegurando la fiabilidad incluso cuando la conexión a internet es escasa.

loadTimeoutpor defecto: 5 seg

Este valor limita el tiempo de espera de este método. Si se alcanza el tiempo de espera, se devolverán los datos en caché o el fallback local.

Ten en cuenta que en casos excepcionales este método puede agotar el tiempo de espera un poco más tarde de lo especificado en loadTimeout, ya que la operación puede estar compuesta por diferentes solicitudes internamente.

¡No codifiques los IDs de producto de forma fija! Dado que los paywalls se configuran de forma remota, los productos disponibles, el número de productos y las ofertas especiales (como los períodos de prueba gratuitos) pueden cambiar con el tiempo. Asegúrate de que tu código gestione estos escenarios.

Por ejemplo, si inicialmente obtienes 2 productos, tu app debería mostrar esos 2 productos. Sin embargo, si más adelante obtienes 3 productos, tu app debería mostrar los 3 sin necesidad de cambios en el código. Lo único que tienes que codificar de forma fija es el ID del placement.

Parámetros de respuesta:

ParámetroDescripción
PaywallUn objeto AdaptyPaywall con: una lista de IDs de producto, el identificador del paywall, Remote Config y varias otras propiedades.

Obtener productos

Una vez que tienes el paywall, puedes consultar el array de productos que le corresponde:

Adapty.getPaywallProducts(paywall).onSuccess { products ->
    // the requested products
}.onError { error ->
    // handle the error
}

Parámetros de respuesta:

ParámetroDescripción
ProductsLista de objetos AdaptyPaywallProduct con: identificador del producto, nombre del producto, precio, moneda, duración de la suscripción y otras propiedades.

Al implementar tu propio diseño de paywall, probablemente necesitarás acceder a estas propiedades del objeto AdaptyPaywallProduct. A continuación se ilustran las propiedades más utilizadas, pero consulta el documento enlazado para obtener detalles completos sobre todas las propiedades disponibles.

PropiedadDescripción
TitlePara mostrar el título del producto, usa product.localizedTitle. Ten en cuenta que la localización se basa en el país de la store seleccionado por el usuario, no en el idioma del dispositivo.
PricePara mostrar el precio en formato localizado, usa product.price.localizedString. Esta localización se basa en la configuración regional del dispositivo. También puedes acceder al precio como número con product.price.amount. El valor se proporcionará en la moneda local. Para obtener el símbolo de moneda correspondiente, usa product.price.currencySymbol.
Subscription PeriodPara mostrar el período (p. ej., semana, mes, año, etc.), usa product.subscriptionDetails?.localizedSubscriptionPeriod. Esta localización se basa en la configuración regional del dispositivo. Para obtener el período de suscripción de forma programática, usa product.subscriptionDetails?.subscriptionPeriod. Desde ahí puedes acceder al enum unit para conocer la duración (es decir, DAY, WEEK, MONTH, YEAR o UNKNOWN). El valor numberOfUnits te dará el número de unidades del período. Por ejemplo, para una suscripción trimestral verás MONTH en la propiedad unit y 3 en la propiedad numberOfUnits.
Introductory OfferPara mostrar una insignia u otro indicador de que una suscripción incluye una oferta introductoria, consulta la propiedad product.subscriptionDetails?.introductoryOfferPhases. Es una lista que puede contener hasta dos fases de descuento: la fase de prueba gratuita y la fase de precio introductorio. Dentro de cada objeto de fase encontrarás las siguientes propiedades útiles:
• paymentMode: un enum con los valores FREE_TRIAL, PAY_AS_YOU_GO, PAY_UPFRONT y UNKNOWN. Las pruebas gratuitas serán del tipo FREE_TRIAL.
• price: el precio con descuento como número. Para las pruebas gratuitas, busca 0 aquí.
• localizedNumberOfPeriods: una cadena localizada según el idioma del dispositivo que describe la duración de la oferta. Por ejemplo, una oferta de prueba de tres días muestra 3 days en este campo.
• subscriptionPeriod: alternativamente, puedes obtener los detalles individuales del período de la oferta con esta propiedad. Funciona de la misma manera para las ofertas que en la sección anterior.
• localizedSubscriptionPeriod: un período de suscripción formateado del descuento para la configuración regional del usuario.

Acelera la obtención del paywall con el paywall de audiencia predeterminada

Normalmente, los paywalls se obtienen casi al instante, por lo que no necesitas preocuparte por acelerar este proceso. Sin embargo, cuando tienes numerosas audiencias y paywalls, y tus usuarios tienen una conexión a internet débil, obtener un paywall puede tardar más de lo deseable. En esas situaciones, puede que quieras mostrar un paywall predeterminado para garantizar una experiencia de usuario fluida en lugar de no mostrar ningún paywall.

Para solucionar esto, puedes usar el método getPaywallForDefaultAudience, que obtiene el paywall del placement especificado para la audiencia All Users. Sin embargo, es fundamental entender que el enfoque recomendado es obtener el paywall mediante el método getPaywall, tal como se detalla en la sección Obtener información del paywall anterior.

Warning

Por qué recomendamos usar getPaywall

El método getPaywallForDefaultAudience tiene algunos inconvenientes importantes:

  • Posibles problemas de compatibilidad con versiones anteriores: Si necesitas mostrar diferentes paywalls para distintas versiones de la app (actual y futuras), puedes encontrarte con dificultades. Tendrás que diseñar paywalls compatibles con la versión actual (heredada) o asumir que los usuarios con esa versión pueden tener problemas con paywalls que no se renderizan correctamente.
  • Pérdida de targeting: Todos los usuarios verán el mismo paywall diseñado para la audiencia All Users, lo que implica perder la segmentación personalizada (incluyendo por países, atribución de marketing o atributos personalizados propios).

Si estás dispuesto a aceptar estas desventajas a cambio de una obtención más rápida del paywall, usa el método getPaywallForDefaultAudience como se describe a continuación. De lo contrario, utiliza getPaywall descrito anteriormente.


Adapty.getPaywallForDefaultAudience(
    placementId = "YOUR_PLACEMENT_ID",
    locale = "en",
    fetchPolicy = AdaptyPaywallFetchPolicy.Default
).onSuccess { paywall ->
    // the requested paywall
}.onError { error ->
    // handle the error
}
ParámetroPresenciaDescripción
placementIdrequeridoEl identificador del Placement. Es el valor que especificaste al crear un placement en tu Adapty Dashboard.
locale

opcional

por defecto: en

El identificador de la localización del paywall. Se espera que este parámetro sea un código de idioma compuesto por una o más subetiquetas separadas por el carácter menos (-). La primera subetiqueta corresponde al idioma y la segunda a la región.

Ejemplo: en significa inglés, pt-br representa el portugués de Brasil.

fetchPolicypor defecto: AdaptyPaywallFetchPolicy.Default

fetchPolicy determina qué capa consulta primero el SDK, no si puede usar la caché. Por defecto, el SDK va primero al servidor y devuelve los datos en caché si esa solicitud falla. Recomendamos esta opción porque garantiza que tus usuarios siempre reciban los datos más actualizados.

Sin embargo, si crees que tus usuarios tienen una conexión a internet inestable, considera AdaptyPaywallFetchPolicy.ReturnCacheDataElseLoad, que invierte ese orden: lee primero la caché y solo va al servidor cuando no hay nada en caché. Es posible que los usuarios no obtengan los datos más recientes, pero experimentarán tiempos de carga más rápidos, independientemente de lo inestable que sea su conexión. La caché se actualiza con regularidad, por lo que es seguro usarla durante la sesión para evitar solicitudes de red.

Una tercera política, AdaptyPaywallFetchPolicy.ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis), se sitúa entre las dos: lee primero la caché mientras la copia almacenada sea más reciente que maxAgeMillis, y va al servidor una vez que sea más antigua.

Ten en cuenta que la caché permanece intacta al reiniciar la app y solo se borra cuando se desinstala la app o mediante una limpieza manual.