Optimiser la récupération des flows et paywalls dans le SDK Android

Une récupération fiable d’un flow ou d’un paywall sur Android repose sur trois points : un affichage rapide, le retour de la variante ciblée par audience, et un repli élégant en cas de réseau lent. Les règles ci-dessous couvrent le timing, la mise en cache et les patterns de secours pour y parvenir.

Règles et pièges

Consultez Récupérer les paywalls et les produits pour la référence des paramètres fetchPolicy et loadTimeout, et Placements pour choisir le bon placement.

Précharger les placements

preloadFlows met en cache le JSON du flow à l’avance — une requête par placement. Vous l’utilisez ensuite normalement : getFlow pour le flow, getFlowConfiguration pour sa configuration d’affichage.

fetchPolicy détermine quelle couche un getFlow ultérieur lit en premier, et non s’il peut accéder au cache :

• ReturnCacheDataElseLoad lit d’abord la copie préchargée et ne contacte le réseau que si rien n’est en cache. ReturnCacheDataIfNotExpiredElseLoad(maxAgeMillis) fait de même tant que la copie est plus récente que maxAgeMillis.
• La valeur par défaut, ReloadRevalidatingCacheData, contacte d’abord le réseau et bascule sur la copie préchargée si la requête échoue ou expire.

Un préchargement est utile dans les deux cas, mais différemment : une politique cache-first supprime la requête, tandis que la valeur par défaut la conserve et dispose d’une copie de secours prête à l’emploi.

Utilisez cette méthode quand vous savez quels placements la session va utiliser, mais que vous ne souhaitez pas encore les afficher — par exemple, juste après la résolution de activate et identify, pour le flow derrière un bouton que l’utilisateur n’a pas encore appuyé.

...

Adapty.preloadFlows(listOf("onboarding", "main_paywall"), loadTimeout = 5.seconds) { error ->
    if (error != null) {
        // at least one placement failed to preload
    }
}

// Later, when the user reaches the paywall:
Adapty.getFlow(
    "main_paywall",
    fetchPolicy = AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad,
) { result ->
    // ...
}

...

Adapty.preloadFlows(Arrays.asList("onboarding", "main_paywall"), TimeInterval.seconds(5), error -> {
    if (error != null) {
        // at least one placement failed to preload
    }
});

// Later, when the user reaches the paywall:
Adapty.getFlow("main_paywall", AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad, result -> {
    // ...
});

Paramètres :

• placementIds (obligatoire) : les placements à précharger. Les identifiants vides et en double sont ignorés.
• loadTimeout (optionnel) : délai d’expiration appliqué à chaque placement du lot, et non au lot dans son ensemble. Par défaut à 5 secondes ; les valeurs inférieures à 1 seconde sont relevées à 1 seconde.

Points importants à connaître :

• Le callback ne se déclenche qu’après que tous les placements ont été traités, et il reporte les échecs par placement ensemble. L’échec d’un placement n’empêche pas les autres de s’exécuter.
• Si un placement expire, rencontre une erreur serveur ou une erreur réseau, le SDK bascule sur les variantes de secours pour ce placement. Les autres échecs sont remontés tels quels.
• Le préchargement ne fait que réchauffer le cache. Il ne retourne pas de contenu — vous appelez toujours getFlow pour l’afficher.

Ce que couvre un préchargement

Un flow s’affiche à l’écran en plusieurs couches. Un préchargement couvre la première, exactement comme getFlow :

getFlowConfiguration attend le layout, donc la première requête pour un layout donné coûte un aller-retour réseau même après un préchargement. Le SDK conserve ensuite ce layout dans son propre cache disque, qui survit aux redémarrages de l’application et est lu avant tout appel réseau — le coût ne tombe donc que sur la première requête, pas sur toutes les suivantes. Une fois le layout en main, le SDK commence à mettre en cache les images indépendamment de l’appel : cela ne bloque pas l’affichage de l’écran, et aucun callback ni aucune erreur ne signale la fin de cette opération.

Identifier quel placement a échoué

Le callback reçoit une AdaptyPreloadPlacementsError couvrant l’ensemble du lot, avec le code REQUEST_FAILED (2005). Pour voir les échecs individuels, lisez sa propriété preloadErrors — une map indexée par ID de placement :

Adapty.preloadFlows(listOf("onboarding", "main_paywall")) { error ->
    if (error is AdaptyPreloadPlacementsError) {
        error.preloadErrors.forEach { (placementId, placementError) ->
            // log or retry the individual placement
        }
    }
}

preloadErrors existe uniquement sur AdaptyPreloadPlacementsError, donc vérifiez d’abord le type — tout autre AdaptyError provient d’autre chose qu’une défaillance par placement.

Ignorer la segmentation d’audience

Pour préchauffer le cache sans attendre la segmentation d’audience, utilisez la variante d’audience par défaut. Elle ne prend pas de loadTimeout :

Adapty.preloadFlowsForDefaultAudience(listOf("main_paywall")) { error -> }

Afficher les médias du premier écran depuis le bundle de l’application

Un flow télécharge ses images et vidéos depuis Adapty. Pour afficher les médias du premier écran instantanément, servez-les depuis le bundle de l’application. C’est une bonne façon de réutiliser des médias que vous livrez déjà, comme les visuels d’un onboarding natif existant.

1. Dans le Flow & Paywall Builder, définissez un identifiant de média personnalisé sur l’image ou la vidéo. Le fichier que vous téléversez là-bas reste comme fichier de secours.
2. Ajoutez le fichier dans le dossier res/raw ou assets de votre application.
3. Lorsque vous créez la vue du flow avec getFlowView, passez le fichier intégré pour cet identifiant dans customAssets :

// "welcome_video" is the custom media ID set in the Flow & Paywall Builder
val bundledAssets = AdaptyCustomAssets.of(
    "welcome_video" to
            AdaptyCustomVideoAsset.file(
                FileLocation.fromResId(requireContext(), R.raw.welcome),
                preview = AdaptyCustomImageAsset.file(
                    FileLocation.fromResId(requireContext(), R.drawable.welcome_poster),
                ),
                resolution = AdaptyCustomVideoAsset.Resolution(width = 1080, height = 1920),
            ),
)

val flowView = AdaptyUI.getFlowView(
    activity,
    flowConfiguration,
    products,
    eventListener,
    insets,
    bundledAssets,
)

Les fichiers groupés augmentent la taille de téléchargement de votre app, donc ne groupez que les médias visibles dès le premier affichage.

Les médias non groupés s’affichent tout de même immédiatement : la configuration de la vue embarque une petite copie basse résolution de chaque image, ainsi que l’image fixe des vidéos, et l’affiche jusqu’au chargement du fichier complet.

Pour la référence complète de customAssets, voir Personnaliser les assets.

Optimiser pour les connexions instables

Pour les marchés où la connectivité est durablement mauvaise (zones rurales, transports, régions affectées par le routage) :

• Définissez fetchPolicy sur AdaptyPlacementFetchPolicy.ReturnCacheDataElseLoad pour chaque récupération sauf la toute première.
• Configurez un paywall de secours pour chaque placement dans l’Adapty Dashboard.
• Réglez loadTimeout sur 3 à 5 secondes et acceptez le paywall de secours lorsque le délai expire.
• Ne conditionnez pas l’affichage du flow à getProfile. Appelez getFlow indépendamment pour qu’un profil lent ne bloque pas l’interface.