Mostrar elementos personalizados con el SDK de iOS

Cuando se abre una pantalla con un elemento personalizado, el SDK de Adapty pasa el tipo y el ID del elemento a un resolver en el código de tu app. El resolver devuelve uno de los siguientes:

  • La vista que coincide con el Type y el ID: Los usuarios ven la vista nativa de SwiftUI, como una animación de Lottie, un gráfico interactivo o una vista previa de la cámara.
  • Sin vista: Los usuarios ven el contenido de respaldo, que es el contenido dentro del elemento personalizado en el Flow & Paywall Builder.

Si el usuario tiene una versión desactualizada de tu app — una que no tiene el resolver en absoluto — igualmente ve el contenido de respaldo. Por lo tanto, puedes publicar el flow antes de lanzar la app.

Antes de empezar

Necesitas:

  • Adapty iOS SDK 4.4 o posterior: Las versiones anteriores muestran el respaldo para cada elemento personalizado.
  • Una aplicación iOS nativa: 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 únicamente 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, como welcome_wave. Los Types e IDs en tu código deben coincidir con los del Flow & Paywall Builder.

Crea vistas para elementos personalizados

Para cada tipo, crea una vista nativa de SwiftUI o reutiliza una de tu app. La siguiente vista del tipo lottie_animation reproduce una animación Lottie:


struct LottieElementView: View {
    let animation: LottieAnimation?

    var body: some View {
        LottieView(animation: animation)
            .resizable()
            .looping()
    }
}

Ver requisitos y mejores prácticas

  • Tamaño:
    • Relleno y alineación: Asegúrate de que la vista nativa encaje en el contenedor que has reservado en el Flow & Paywall Builder, descontando el relleno. Si la vista no ocupa toda el área, aparece en la esquina superior izquierda de forma predeterminada. 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 expande para llenar el espacio disponible (como un mapa) se colapsará. Asigna una altura Fixed al elemento personalizado.
  • Acciones de flow: La vista nativa no puede desencadenar acciones de flow, como la transición a la siguiente pantalla. Mantén los botones de navegación, los botones de compra y cualquier otro botón 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, SwiftUI ejecuta la acción onDisappear de la vista nativa. En esa acción, detén lo que la vista haya iniciado, como sesiones de cámara, reproductores y actualizaciones de ubicación. Para trabajo asíncrono, usa .task: SwiftUI lo cancela cuando la vista desaparece. Cuando el usuario regresa, el SDK llama de nuevo al resolver y SwiftUI reinicia el estado de la vista.
  • Vistas UIKit: Envuélvelas en UIViewRepresentable.

Escribe un resolver para identificar elementos y vistas personalizadas

Para escribir un resolver, haz que un tipo se ajuste al protocolo AdaptyUICustomElementsResolver e implementa el método view(forType:id:context:).

Para el tipo lottie_animation, el siguiente resolver devuelve LottieElementView. El ID identifica el archivo de animación en el bundle de la app, por ejemplo welcome_wave:


struct CustomElementsResolver: AdaptyUICustomElementsResolver {
    func view(
        forType type: String,
        id: String,
        context: AdaptyUICustomElementContext
    ) -> AnyView? {
        switch type {
        case "lottie_animation":
            // the ID names the animation file, such as welcome_wave.json
            guard let animation = LottieAnimation.named(id) else {
                return nil // no file for this ID: show the fallback
            }
            return AnyView(LottieElementView(animation: animation))
        default:
            return nil
        }
    }
}

En el caso default, devuelve nil. Si añades un elemento personalizado con un nuevo Type después de publicar la app, los usuarios de esa versión verán su fallback.

El resolver tiene los siguientes requisitos:

  • Datos de red y reproductores: Mantén 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, por ejemplo, cuando se cargan los productos o se inicia una compra. 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. SwiftUI mantiene el estado de la vista nativa entre llamadas, de modo que los datos se cargan una sola vez y los reproductores siguen reproduciéndose. Crea reproductores, sesiones y solicitudes de red en .task o en un @StateObject, no en el valor inicial de una propiedad @State. Swift evalúa ese valor inicial de nuevo cada vez que el resolver crea la vista.
  • 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 el propio body de la vista, no en el resolver. Si el resolver devuelve una vista diferente para el mismo elemento personalizado, SwiftUI restablece el estado de la vista.
  • Datos de la app: Almacena un objeto de la app que contenga los datos, como un ObservableObject con el streak diario, en una propiedad del resolver. Pasa el objeto a la vista nativa y obsérvalo allí con @ObservedObject. Un valor que copies al resolver, como el número del streak, se quedará tal como estaba cuando creaste el resolver. No uses objetos de entorno para estos datos: con el controlador de flow de UIKit, la vista nativa no recibe el entorno SwiftUI de tu app.

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 nil en las siguientes situaciones:

  • Nada que visualizar: falta el archivo de animación o el archivo 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, la declaración guard en el resolver devuelve nil cuando falta el archivo de animación.

Para un permiso, devuelve nil solo cuando el usuario lo haya denegado antes de que se abra la pantalla. Si el usuario aún no ha respondido a la solicitud de permiso, devuelve la vista nativa en lugar de nil y pídele el permiso dentro de ella. Por ejemplo, en Mostrar lugares cercanos en un mapa en un flow, iOS muestra el aviso de acceso a la ubicación cuando aparece el mapa. La vista nativa puede mostrar el mapa en cuanto el usuario concede el acceso. Si devuelves nil antes de que el usuario responda, el respaldo permanece incluso después de que conceda el acceso, hasta que el SDK vuelva a llamar al resolver.

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 verán tus vistas nativas en los 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 desde tu app.

Adjunta un resolver a un flow concreto cuando ese flow necesita datos que tu app solo tiene en el momento de abrirlo. Por ejemplo, una 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.

Establecer un resolver global para la app

Para usar el resolver en cada flow, llama a AdaptyUI.setCustomElementsResolver(_:) una vez, por ejemplo al iniciar la app:


// keep this instance: a resolver for one flow can reuse it
@MainActor let customElementsResolver = CustomElementsResolver()

AdaptyUI.setCustomElementsResolver(customElementsResolver)
Tip

La alternativa más sencilla y limitada al enfoque de resolver es pasar un diccionario [String: AdaptyUICustomElementBuilder] con claves de tipo. Requiere menos código, pero no puedes establecer condiciones para el contenido de respaldo.

AdaptyUI.setCustomElementsResolver([
    "lottie_animation": .init { _, id, _ in LottieElementView(animation: .named(id)) },
])

Adjuntar un resolver a un flow

Un resolver que adjuntas a un flow reemplaza al resolver global en ese flow. Los valores que pasas a este resolver permanecen tal como estaban cuando obtuviste la configuración del flow. Para mostrar nuevos valores, vuelve a obtener la configuración.

Para conservar 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 muestra una vista previa del documento que el usuario quiere exportar y llama al resolver global para cualquier otro elemento personalizado:


struct ExportPaywallResolver: AdaptyUICustomElementsResolver {
    let document: Document // the document that the user wants to export
    let appWideResolver: any AdaptyUICustomElementsResolver

    func view(
        forType type: String,
        id: String,
        context: AdaptyUICustomElementContext
    ) -> AnyView? {
        if type == "document_preview" {
            return AnyView(DocumentPreview(document: document))
        }
        // other Types: the views of the app-wide resolver
        return appWideResolver.view(forType: type, id: id, context: context)
    }
}

Adjunta el resolver al flow cuando obtengas su configuración:

func showExportPaywall(flow: AdaptyFlow, document: Document) async {
    do {
        let flowConfiguration = try await AdaptyUI.getFlowConfiguration(
            forFlow: flow,
            customElementsResolver: ExportPaywallResolver(
                document: document,
                appWideResolver: customElementsResolver // the instance that you set app-wide
            )
        )
        // present the flow
    } catch {
        // handle the error
    }
}

Si usas diccionarios en lugar de resolvers, combina los dos diccionarios y adjunta el resultado al flow: appWideViews.merging(flowViews) { _, flowView in flowView }. Si un mismo Type aparece en ambos diccionarios, este código conserva la vista del flow en cuestión.

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:

  1. 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.

  2. 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 aparece y encaja en el elemento personalizado. Si la vista se desplaza o responde a gestos de arrastre, prueba también esos gestos.

  3. Si aparece el fallback en lugar de la vista nativa, busca esta advertencia en la consola de Xcode: custom element <type>:<id> is not served by a resolver. Luego verifica que:

    • El tipo y el ID de la advertencia coincidan exactamente, letra por letra, con los de tu código.
    • Tu app tiene el archivo, los datos o el permiso que necesita la vista.
    • Tu app establece el resolver global antes de que se abra la pantalla con el elemento personalizado.
    • Un resolver para este flow, si lo adjuntas, devuelve una vista para el tipo y el ID correspondientes.

    Si la advertencia no aparece, verifica que la app use el SDK de Adapty para iOS 4.4 o posterior y que Adapty.logLevel no sea .error.

  4. Para previsualizar el paywall de respaldo, devuelve nil para el Type y abre la pantalla de nuevo.

Ejemplos

Cada receta muestra la configuración en el builder y el código para tu app: