Récupérer les flows & paywalls - iOS

Après avoir conçu votre flow ou paywall avec le Paywall Builder, vous pouvez l’afficher dans votre application mobile. La première étape consiste à récupérer le flow ou le paywall associé au placement ainsi que sa configuration d’affichage, comme décrit ci-dessous.

Récupérer un flow/paywall

Si vous avez conçu un flow ou un paywall avec le Flow Builder ou le Paywall Builder, vous n’avez pas à vous soucier de son rendu dans le code de votre application mobile pour l’afficher à l’utilisateur. Un tel flow ou paywall contient à la fois ce qui doit être affiché et la manière dont cela doit l’être. Vous devez néanmoins récupérer son ID via le placement, sa configuration d’affichage, puis le présenter dans votre application mobile.

Récupérez le flow ou le paywall et sa configuration de vue le plus tôt possible — idéalement bien avant de l’afficher. Dès que vous récupérez la configuration de vue, le SDK commence à télécharger et mettre en cache ses images en arrière-plan. Plus tôt vous la récupérez, plus ces téléchargements ont de temps pour se terminer. Au moment où vous affichez le flow ou le paywall, sa configuration et ses images peuvent déjà être mises en cache et prêtes à afficher.

Pour obtenir un flow ou un paywall, utilisez la méthode getFlow :

do {
    let flow = try await Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID")
    // the requested flow/paywall
} catch {
    // handle the error
}

Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID") { result in
    switch result {
        case let .success(flow):
            // the requested flow/paywall
        case let .failure(error):
            // handle the error
    }
}

Paramètres :

Paramètres de réponse :

Récupérer la configuration de vue

Après avoir récupéré le flow ou le paywall, vérifiez s’il inclut une configuration de vue via flow.hasViewConfiguration. Ce flag distingue la façon dont le placement a été conçu dans l’Adapty Dashboard :

• true — le placement a été conçu dans le Flow Builder (un flow) ou le Paywall Builder (un paywall). Adapty génère l’interface utilisateur pour vous. Continuez avec les étapes ci-dessous pour récupérer la configuration de vue et présenter le flow ou le paywall.
• false — le placement est un paywall personnalisé sans interface Builder.

Utilisez la méthode getFlowConfiguration pour charger la configuration de la vue.

guard flow.hasViewConfiguration else {
    // handle as remote config paywall
    return
}

let flowConfiguration = try await AdaptyUI.getFlowConfiguration(forFlow: flow)

Paramètres :

Une fois chargé, présentez le flow/paywall.

Récupérer un flow ou un paywall pour une audience par défaut afin d’accélérer la récupération

En général, les flows et les paywalls sont récupérés presque instantanément, vous n’avez donc pas à vous soucier d’accélérer ce processus. Cependant, si vous avez de nombreuses audiences et placements, et que vos utilisateurs ont une connexion internet faible, la récupération d’un flow ou d’un paywall peut prendre plus de temps que souhaité. Dans ce cas, vous pouvez afficher un flow ou un paywall par défaut pour garantir une expérience utilisateur fluide plutôt que de ne rien afficher.

Pour y remédier, vous pouvez utiliser la méthode getFlowForDefaultAudience, qui récupère le flow ou le paywall du placement spécifié pour l’audience All Users. Cependant, il est essentiel de comprendre que l’approche recommandée est de récupérer le flow ou le paywall via la méthode getFlow, comme décrit dans la section Récupérer les informations du paywall ci-dessus.

Adapty.getFlowForDefaultAudience(placementId: "YOUR_PLACEMENT_ID") { result in
    switch result {
        case let .success(flow):
            // the requested flow
        case let .failure(error):
            // handle the error
    }
}

Personnaliser les ressources

Pour personnaliser les images et vidéos de votre paywall/flow, implémentez des ressources personnalisées.

Les images et vidéos hero ont des identifiants prédéfinis : hero_image et hero_video. Dans un bundle de ressources personnalisées, vous ciblez ces éléments par leurs identifiants et personnalisez leur comportement.

Pour les autres images et vidéos, vous devez définir un identifiant personnalisé dans l’Adapty Dashboard.

Par exemple, vous pouvez :

• Afficher une image ou vidéo différente à certains utilisateurs.
• Afficher une image de prévisualisation locale pendant le chargement d’une image principale distante.
• Afficher une image de prévisualisation avant de lancer une vidéo.
• Fournir la résolution en pixels d’une vidéo afin que le lecteur réserve l’espace de mise en page (ratio = width / height) avant le chargement de la vidéo. Passez nil pour ignorer cela.

Voici un exemple de la façon dont vous pouvez fournir des ressources personnalisées via un simple dictionnaire :

let customAssets: [String: AdaptyCustomAsset] = [
    // Show a local image using a custom ID
    "custom_image": .image(
        .uiImage(value: UIImage(named: "image_name")!)
    ),

    // Show a local preview image while a remote main image is loading
    "hero_image": .image(
        .remote(
            url: URL(string: "https://example.com/image.jpg")!,
            preview: UIImage(named: "preview_image")
        )
    ),

    // Show a local video with a preview image and a known resolution
    "hero_video": .video(
        .file(
            url: Bundle.main.url(forResource: "custom_video", withExtension: "mp4")!,
            preview: .uiImage(value: UIImage(named: "video_preview")!),
            resolution: CGSize(width: 1080, height: 1920)
        )
    ),
]

let flowConfig = try await AdaptyUI.getFlowConfiguration(
    forFlow: flow,
    assetsResolver: customAssets
)

Configurer les minuteries définies par le développeur

Pour utiliser des minuteries personnalisées dans votre application mobile, créez un objet qui suit le protocole AdaptyTimerResolver. Cet objet définit comment chaque minuterie personnalisée doit être rendue. Si vous préférez, vous pouvez utiliser directement un dictionnaire [String: Date], car il est déjà conforme à ce protocole. Voici un exemple :

@MainActor
struct AdaptyTimerResolverImpl: AdaptyTimerResolver {
    func timerEndAtDate(for timerId: String) -> Date {
        switch timerId {
        case "CUSTOM_TIMER_6H":
            Date(timeIntervalSinceNow: 3600.0 * 6.0) // 6 hours
        case "CUSTOM_TIMER_NY":
            Calendar.current.date(from: DateComponents(year: 2025, month: 1, day: 1)) ?? Date(timeIntervalSinceNow: 3600.0)
        default:
            Date(timeIntervalSinceNow: 3600.0) // 1 hour
        }
    }
}

Dans cet exemple, CUSTOM_TIMER_NY et CUSTOM_TIMER_6H sont les Timer IDs des minuteurs définis par le développeur que vous avez configurés dans l’Adapty Dashboard. Le timerResolver garantit que votre application met à jour dynamiquement chaque minuteur avec la valeur correcte. Par exemple :

• CUSTOM_TIMER_NY : le temps restant jusqu’à la fin du minuteur, par exemple le Jour de l’An.
• CUSTOM_TIMER_6H : le temps restant dans une période de 6 heures qui a démarré lorsque l’utilisateur a ouvert le paywall.

Après avoir conçu la partie visuelle de votre paywall avec le Paywall Builder dans l’Adapty Dashboard, vous pouvez l’afficher dans votre application mobile. La première étape consiste à récupérer le paywall associé au placement et sa configuration d’affichage, comme décrit ci-dessous.

Notez que cette rubrique concerne les paywalls personnalisés avec le Paywall Builder. Si vous implémentez vos paywalls manuellement, consultez Récupérer les paywalls et produits pour les paywalls en Remote Config.

Récupérer un paywall conçu avec le Paywall Builder

Si vous avez conçu un paywall avec le Paywall Builder, vous n’avez pas à vous soucier de son rendu dans le code de votre application mobile pour l’afficher à l’utilisateur. Un tel paywall contient à la fois ce qui doit être affiché et la manière dont cela doit l’être. Vous devez néanmoins récupérer son identifiant via le placement, sa configuration d’affichage, puis le présenter dans votre application mobile.

Pour garantir des performances optimales, il est essentiel de récupérer le paywall et sa configuration de vue le plus tôt possible, afin de laisser suffisamment de temps aux images de se télécharger avant de les afficher à l’utilisateur.

Pour obtenir un paywall, utilisez la méthode getPaywall :

do {
    let paywall = try await Adapty.getPaywall("YOUR_PLACEMENT_ID")
    // the requested paywall
} catch {
    // handle the error
}

Adapty.getPaywall(placementId: "YOUR_PLACEMENT_ID", locale: "en") { result in
    switch result {
        case let .success(paywall):
            // the requested paywall
        case let .failure(error):
            // handle the error
    }
}

Paramètres :

Récupérer la configuration de vue d’un paywall créé avec Paywall Builder

Après avoir récupéré le paywall, vérifiez s’il contient une configuration de vue, ce qui indique qu’il a été créé avec Paywall Builder. Cela vous guidera sur la façon d’afficher le paywall. Si la configuration de vue est présente, traitez-le comme un paywall Paywall Builder ; sinon, gérez-le comme un paywall Remote Config.

Utilisez la méthode getPaywallConfiguration pour charger la configuration de la vue.

guard paywall.hasViewConfiguration else {
    //  use your custom logic
    return
}

do {
    let paywallConfiguration = try await AdaptyUI.getPaywallConfiguration(
            forPaywall: paywall,
            products: products
    )
    // use loaded configuration
} catch {
    // handle the error
}

Paramètres :

Une fois chargé, présentez le paywall.

Obtenir un paywall pour l’audience par défaut afin d’accélérer le chargement

En règle générale, les paywalls sont récupérés presque instantanément, donc vous n’avez pas à vous soucier d’accélérer ce processus. Cependant, si vous avez de nombreuses audiences et paywalls et que vos utilisateurs disposent d’une connexion internet faible, la récupération d’un paywall peut prendre plus de temps que souhaité. Dans ce cas, vous pouvez afficher un paywall par défaut pour garantir une expérience fluide plutôt que de ne rien afficher du tout.

Pour y remédier, vous pouvez utiliser la méthode getPaywallForDefaultAudience, qui récupère le paywall du placement spécifié pour l’audience All Users. Il est cependant essentiel de comprendre que l’approche recommandée est de récupérer le paywall via la méthode getPaywall, comme indiqué dans la section Récupérer les informations du paywall ci-dessus.

Adapty.getPaywallForDefaultAudience(placementId: "YOUR_PLACEMENT_ID", locale: "en") { result in
    switch result {
        case let .success(paywall):
            // the requested paywall
        case let .failure(error):
            // handle the error
    }
}

Personnaliser les ressources

Pour personnaliser les images et vidéos de votre paywall, implémentez des ressources personnalisées.

Les images et vidéos hero ont des ID prédéfinis : hero_image et hero_video. Dans un bundle de ressources personnalisées, vous ciblez ces éléments par leur ID et personnalisez leur comportement.

Pour les autres images et vidéos, vous devez définir un ID personnalisé dans l’Adapty Dashboard.

Par exemple, vous pouvez :

• Afficher une image ou une vidéo différente à certains utilisateurs.
• Afficher une image de prévisualisation locale pendant le chargement d’une image principale distante.
• Afficher une image de prévisualisation avant de lancer une vidéo.

Voici un exemple montrant comment fournir des ressources personnalisées via un simple dictionnaire :

let customAssets: [String: AdaptyCustomAsset] = [
    // Show a local image using a custom ID
    "custom_image": .image(
        .uiImage(value: UIImage(named: "image_name")!)
    ),

    // Show a local preview image while a remote main image is loading
    "hero_image": .image(
        .remote(
            url: URL(string: "https://example.com/image.jpg")!,
            preview: UIImage(named: "preview_image")
        )
    ),

    // Show a local video with a preview image
    "hero_video": .video(
        .file(
            url: Bundle.main.url(forResource: "custom_video", withExtension: "mp4")!,
            preview: .uiImage(value: UIImage(named: "video_preview")!)
        )
    ),
]

let paywallConfig = try await AdaptyUI.getPaywallConfiguration(
    forPaywall: paywall,
    assetsResolver: customAssets
)

Configurer des minuteurs définis par le développeur

Pour utiliser des minuteurs personnalisés dans votre application mobile, créez un objet qui suit le protocole AdaptyTimerResolver. Cet objet définit comment chaque minuteur personnalisé doit être rendu. Si vous préférez, vous pouvez utiliser directement un dictionnaire [String: Date], car il est déjà conforme à ce protocole. Voici un exemple :

@MainActor
struct AdaptyTimerResolverImpl: AdaptyTimerResolver {
    func timerEndAtDate(for timerId: String) -> Date {
        switch timerId {
        case "CUSTOM_TIMER_6H":
            Date(timeIntervalSinceNow: 3600.0 * 6.0) // 6 hours
        case "CUSTOM_TIMER_NY":
            Calendar.current.date(from: DateComponents(year: 2025, month: 1, day: 1)) ?? Date(timeIntervalSinceNow: 3600.0)
        default:
            Date(timeIntervalSinceNow: 3600.0) // 1 hour
        }
    }
}

Dans cet exemple, CUSTOM_TIMER_NY et CUSTOM_TIMER_6H sont les Timer IDs des minuteries définies par le développeur que vous avez configurées dans l’Adapty Dashboard. Le timerResolver garantit que votre application met dynamiquement à jour chaque minuterie avec la valeur correcte. Par exemple :

• CUSTOM_TIMER_NY : le temps restant jusqu’à la fin de la minuterie, comme le Jour de l’An.
• CUSTOM_TIMER_6H : le temps restant dans une période de 6 heures qui a démarré lorsque l’utilisateur a ouvert le paywall.