Mostrar elementos personalizados con el SDK de Android
Cuando se abre una pantalla con un elemento personalizado, el SDK de Adapty pasa el Type y el ID del elemento a un resolver en el código de tu app. El resolver devuelve una de las siguientes opciones:
- La vista que coincide con el Type y el ID: Los usuarios ven la vista nativa, como una animación Lottie, un gráfico interactivo o una vista previa de la cámara.
- Sin vista: Los usuarios ven el fallback, que es el contenido dentro del elemento personalizado en el Flow & Paywall Builder.
Los usuarios de versiones de la app sin el resolver también verán el fallback. Por eso, puedes publicar el flow antes de lanzar la app.
Antes de empezar
Necesitas:
- Adapty Android SDK 4.4 o posterior: Las versiones anteriores muestran el respaldo para cada elemento personalizado.
- Una app nativa de Android: Los SDK de Adapty para frameworks multiplataforma, como Flutter, muestran el respaldo para cada elemento personalizado.
- Un esquema de nomenclatura para los elementos personalizados: Asigna a cada vista nativa un Type, como
lottie_animation. Usa solo letras minúsculas, números y guiones bajos en los Types. Para distinguir entre elementos personalizados del mismo Type, asigna a cada uno un ID, comowelcome_wave. Los Types e IDs en tu código deben coincidir con los del Flow & Paywall Builder.
Si tu app de iOS ya muestra elementos personalizados, reutiliza sus Types e IDs. A menos que configures una audiencia separada para cada plataforma, los usuarios de iOS y Android verán los mismos flows.
Crear vistas para elementos personalizados
Para cada tipo, crea o reutiliza un composable/Android View. Las siguientes vistas del tipo lottie_animation reproducen una animación Lottie desde la carpeta assets de tu app. El ejemplo en Kotlin es un composable que usa la librería com.airbnb.android:lottie-compose. El ejemplo en Java crea un Android View de la librería com.airbnb.android:lottie:
Requisitos y mejores prácticas
-
Dimensionamiento:
- Relleno y alineación: Asegúrate de que la vista nativa encaje en el contenedor que has asignado en el Flow & Paywall Builder, descontando el padding. Si la vista no ocupa toda el área, aparece por defecto en la esquina superior inicial de esa área. Para moverla, cambia la alineación en la sección Layout del elemento personalizado.
- Altura Hug: Si la altura del elemento personalizado está configurada como Hug, una vista que se estira para llenar el espacio disponible (como una lista lazy) se colapsará o se estirará hasta la altura de la pantalla. Asigna al elemento personalizado una altura Fixed en su lugar.
-
Tema: Para mostrar un composable con los colores y fuentes de tu app en una pantalla construida con Views, envuélvelo en tu tema de Compose.
-
Acciones de flow: La vista nativa no puede disparar acciones de flow, como la transición a la siguiente pantalla. Mantén los botones de navegación, los botones de compra y otros botones con acciones de flow fuera del elemento personalizado.
-
Elementos seleccionables: Mantén el elemento personalizado fuera de las tarjetas de producto y otros elementos seleccionables. Cuando cambia la selección, la vista nativa puede perder su estado.
-
Gestión de la navegación: Cuando el usuario avanza a la siguiente pantalla, el SDK elimina la vista nativa de la pantalla. Detén lo que la vista haya iniciado, como sesiones de cámara, reproductores y actualizaciones de ubicación:
- Composable: Usa el bloque
onDisposede unDisposableEffect. Para trabajo asíncrono, usaLaunchedEffect: Compose lo cancela cuando el composable abandona la composición. Viewde Android: SobreescribeonDetachedFromWindowen tu subclase deView, o añade unView.OnAttachStateChangeListenera laView.
Cuando el usuario regresa, o tras un cambio de configuración como una rotación, el SDK vuelve a llamar al resolver y crea una nueva vista nativa sin el estado de la anterior.
- Composable: Usa el bloque
-
Carruseles: En un carrusel, las vistas nativas de todas las diapositivas permanecen activas mientras la pantalla está abierta, no solo la vista de la diapositiva visible. Mantén las previsualizaciones de cámara y los reproductores con sonido fuera de los carruseles.
Escribe un resolver para enlazar elementos y vistas personalizados
Para escribir un resolver, implementa la interfaz AdaptyCustomElementsResolver. Su método resolve recibe el tipo y el ID de un elemento personalizado, y devuelve la vista correspondiente en una de las siguientes formas:
- Un composable: Devuelve
AdaptyCustomElementContent.compose, con el composable dentro de su lambda. - Una
Viewde Android: DevuelveAdaptyCustomElementContent.view, con una función que crea laView. En Kotlin, nombra el parámetrofactory:AdaptyCustomElementContent.view(factory = { context, _ -> ChartView(context) }). Sin el nombre, Kotlin pasa una lambda al final al parámetro opcionalupdate, y el código no compila.
Para el tipo lottie_animation, el siguiente resolver devuelve la vista Lottie. El ID nombra el archivo de animación en la carpeta assets, por ejemplo, welcome_wave para welcome_wave.json:
Para cualquier otro tipo, devuelve null. Si añades un elemento personalizado con un nuevo tipo después de lanzar la app, los usuarios de esa versión verán su fallback.
El resolver tiene los siguientes requisitos:
-
Datos de red y reproductores: Guarda los datos de red y los reproductores en el estado de la vista nativa, no en el resolver. El SDK llama al resolver muchas veces mientras la pantalla está abierta. El código del resolver se ejecuta de nuevo en cada llamada, por lo que las solicitudes de red se repiten y los reproductores vuelven a empezar. El SDK no recrea la vista nativa entre estas llamadas, por lo que los datos se cargan una sola vez y los reproductores siguen reproduciéndose. Crea reproductores, sesiones y solicitudes de red dentro de la vista nativa:
- Composable: Crea reproductores y sesiones en
remember, y solicitudes de red enLaunchedEffect. - Android
View: Crea reproductores, sesiones y solicitudes de red enonAttachedToWindow.
- Composable: Crea reproductores y sesiones en
-
Una vista nativa por elemento personalizado: Algunas vistas nativas cambian mientras la pantalla está abierta, por ejemplo, cuando se cargan sus datos o cuando el usuario las toca. Implementa esta lógica en la propia vista nativa, no en el resolver. Si el resolver devuelve un composable diferente para el mismo elemento personalizado, Compose restablece el estado de la vista.
-
Un nuevo
Viewpor cada aparición: Crea un nuevoViewen cada llamada afactory. El SDK llama afactorycada vez que aparece el elemento personalizado, por ejemplo, cuando se abre la pantalla, cuando el usuario vuelve a ella o después de una rotación. -
Datos de la app: Guarda un objeto que contenga los datos, como un
StateFlowo unLiveDatacon una racha diaria, en una propiedad del resolver. Pasa el objeto a la vista nativa y obsérvalo allí:- Composable: Recopila un
StateFlowconcollectAsState, u observa unLiveDataconobserveAsState. - Android
View: Observa el objeto enonAttachedToWindow, y detén la observación enonDetachedFromWindow.
Un valor que copias en el resolver, como el número de racha, permanece tal como estaba cuando creaste el resolver.
- Composable: Recopila un
Establecer condiciones para el contenido de respaldo
Para mostrar a los usuarios el contenido de respaldo en lugar de un elemento personalizado vacío, devuelve ninguna vista en las siguientes situaciones:
- Nada que visualizar: falta el archivo de animación o de datos necesario.
- Nada que procesar: el usuario omitió una pregunta del cuestionario y los datos están incompletos.
- Acceso prohibido: un permiso denegado impide que la vista acceda a un recurso.
Por ejemplo, el resolver no devuelve ninguna vista cuando falta el archivo de animación.
Para un permiso, devuelve null solo cuando el usuario lo denegó antes de que se abriera la pantalla. ContextCompat.checkSelfPermission devuelve el mismo valor, PERMISSION_DENIED, en dos casos: antes de que tu app solicite el permiso por primera vez, y después de que el usuario lo deniegue. Para distinguir estos casos, guarda el resultado de la solicitud de permiso y lee ese resultado guardado en el resolver. Si tu app aún no ha solicitado el permiso, devuelve la vista nativa en lugar de null y solicita el permiso dentro de la vista. Por ejemplo, solicita acceso a la ubicación cuando aparezca una vista de mapa y muestra el mapa en cuanto el usuario conceda el acceso. Si devuelves null y el usuario concede el acceso después, seguirá viendo el fallback. Un cambio de permiso no hace que el SDK llame al resolver de nuevo. La vista nativa solo aparece después de que el SDK vuelva a llamar al resolver, por ejemplo cuando el usuario regresa a la pantalla.
Pasa el resolver al SDK
Empieza con un resolver global para toda la app. El SDK lo llama en cada flow que no tenga su propio resolver. Los usuarios ven tus vistas nativas en nuevos flows y pruebas A/B sin necesidad de publicar una nueva versión de la app. Estas vistas siguen mostrando a cada usuario sus propios datos, como una racha diaria, porque los leen directamente de tu app.
Adjunta un resolver a un flow concreto cuando ese flow necesite datos que tu aplicación solo tiene en el momento de abrirlo. Por ejemplo, un paywall muestra el peso que el usuario introdujo en un flow anterior, o previsualiza el documento que el usuario quiere exportar. También puedes adjuntar un resolver a un flow para mostrar una vista diferente para un Type en ese flow.
Mostrar vistas en cada flow
Para usar el resolver en cada flow, llama a AdaptyUI.setCustomElementsResolver una vez, por ejemplo en el método onCreate de tu clase Application:
Para mostrar la misma vista en cada elemento personalizado de un Type, pasa un mapa de Types y vistas a AdaptyCustomElementsResolver.of. Un mapa requiere menos código que una clase resolver, pero no puedes establecer condiciones para el contenido de respaldo.
val appWideViews = mapOf(
"confetti" to AdaptyCustomElementContent.compose { LottieElement("confetti.json") },
)
AdaptyUI.setCustomElementsResolver(AdaptyCustomElementsResolver.of(appWideViews))Mostrar datos para un flow, como un documento a exportar
Un resolver que pasas a una vista de flow reemplaza el resolver global en esa vista de flow.
Para mantener las vistas globales en este flow, pasa el resolver global a este resolver y llama al resolver global para los demás Types e IDs. El siguiente resolver previsualiza el documento que el usuario quiere exportar y llama al resolver global para cualquier otro elemento personalizado:
Pasa el resolver en el parámetro customElementsResolver de AdaptyUI.getFlowView:
Si creas AdaptyFlowView tú mismo, pasa el resolver al método showFlow. En Java, showFlow acepta los mismos argumentos que getFlowView, excepto activity. En Jetpack Compose, pasa el resolver a AdaptyFlowScreen. Para ver un ejemplo de cada llamada, consulta Mostrar flows y paywalls.
Si usas AdaptyCustomElementsResolver.of en lugar de clases de resolución, combina el mapa de vistas globales con el mapa de este flow: AdaptyCustomElementsResolver.of(appWideViews + flowViews). Pasa el resultado a la vista del flow. Si un tipo aparece en ambos mapas, este código conserva la vista del flow.
Prueba en un dispositivo
El Flow & Paywall Builder no puede ejecutar el código de tu app, por lo que el canvas solo muestra el fallback. Un error en la vista nativa puede hacer que la app se bloquee. Antes de publicar la app, prueba en un dispositivo cada pantalla que tenga un elemento personalizado:
-
Para ver la versión publicada más reciente de cada flow en lugar de una versión en caché, registra el dispositivo como dispositivo de prueba.
-
Para ver las advertencias del SDK de Adapty en Logcat, establece el nivel de log en
AdaptyLogLevel.WARNo un nivel más detallado. Con el nivel predeterminado,AdaptyLogLevel.NONE, el SDK no registra nada. -
En el dispositivo, ejecuta una compilación que incluya el resolver. Abre cada pantalla que tenga un elemento personalizado y verifica que la vista nativa aparezca y se ajuste al elemento personalizado. Si la vista se desplaza o responde a gestos de arrastre, prueba estos gestos.
-
Si aparece el respaldo en lugar de la vista nativa, busca esta advertencia en Logcat:
custom element <type>:<id> is not served by a resolver. Luego verifica que:- El tipo y el ID en la advertencia coincidan exactamente con los de tu código, letra por letra.
- Tu app tenga el archivo, los datos o el permiso que necesita la vista.
- Tu app establezca el resolver a nivel de app.
- Un resolver para este flow, si pasas uno, devuelva una vista para el tipo y el ID.
Si la advertencia no aparece, verifica que la app usa el SDK de Adapty para Android 4.4 o posterior.
-
Si el elemento personalizado permanece vacío, busca alguna de estas advertencias en Logcat:
custom element <type>:<id> is not served by a resolver: El elemento personalizado no tiene contenido de respaldo y ningún resolver devuelve una vista para él. Verifica cada elemento del paso 4.content does not report its size: El composable no tiene altura propia. Dale al elemento personalizado una altura Fixed.
El SDK solo registra la advertencia de tamaño para los composables. Si un
Viewde Android permanece vacío sin ninguna advertencia, dale también una altura Fixed al elemento personalizado. -
Para previsualizar el fallback, devuelve
nullpara el tipo y vuelve a abrir la pantalla.
Ejemplos
Cada ejemplo muestra la configuración en el builder y el código para tu app:
- Mostrar el progreso del usuario con una animación Lottie: Un anillo que se rellena a medida que crece una racha.
- Mostrar un gráfico interactivo de objetivo de peso en un paywall: Un gráfico de objetivo de peso, en el flow de paywall que sigue al flow de onboarding.
- Mostrar lugares cercanos en un mapa en un flow: Un mapa de centros de fitness cercanos a cada usuario.