Afficher un paywall ciblé AA au premier lancement dans le SDK Capacitor

Cet article s’applique à la version iOS de votre application. L’attribution Apple Ads n’existe que sur iOS.

L’attribution Apple Ads (AA) arrive de manière asynchrone après adapty.activate(). Au premier lancement, elle n’est généralement pas encore disponible, donc getFlow résout contre l’audience par défaut et les utilisateurs Apple Ads ratent votre paywall segmenté AA. Plutôt que de retarder le paywall jusqu’à l’arrivée de l’attribution, affichez-en un immédiatement et actualisez-le une fois l’attribution AA appliquée — les utilisateurs Apple Ads obtiennent ainsi la variante ciblée, et tout le monde voit un paywall sans attente. AdaptyProfile.appliedExternalAttributionProviders vous indique quand l’attribution AA a été appliquée.

Avant de commencer

Vous aurez besoin de :

• Adapty Capacitor SDK 4.1 ou ultérieur. Sur les versions 3.17.1–4.0, la propriété de profil est nommée appliedAttributionSources, et la version 3.17.1 récupère les paywalls avec getPaywall plutôt que getFlow.
• Apple Ads configuré pour l’application dans Adapty. Voir Apple Ads.

Comment ça fonctionne

Après adapty.activate(), le SDK demande les données d’attribution Apple Ads à Apple en arrière-plan et transmet le résultat au backend d’Adapty. Lorsque AA devient la source d’attribution active pour le profil, le SDK envoie un AdaptyProfile mis à jour à votre listener onLatestProfileLoad, avec 'apple_search_ads' dans son tableau appliedExternalAttributionProviders.

Cela vous permet de charger le paywall en deux étapes :

1. Appelez getFlow immédiatement. Sans attribution encore appliquée, Adapty résout la requête sur l’audience par défaut, et l’utilisateur voit un paywall aussitôt.
2. Dès que 'apple_search_ads' apparaît, rappelez getFlow. Adapty résout alors la requête sur l’audience Apple Ads et renvoie le paywall ciblé, qui remplace le premier.

appliedExternalAttributionProviders peut être vide ou absent. Cela signifie l’un des cas suivants :

• L’attribution Apple Ads n’a pas encore été traitée pour ce profil.
• Aucune attribution n’est arrivée.
• L’attribution provient d’un autre fournisseur, que ce tableau ne signale pas.

Dans les trois cas, l’étape 1 est sans risque — Adapty résout la requête selon l’audience qui correspond à l’état actuel du profil, généralement l’audience par défaut. L’étape 2 ne s’exécute qu’une fois que 'apple_search_ads' apparaît.

Implémentation

Affichez un paywall immédiatement, puis écoutez 'apple_search_ads' et actualisez le paywall lorsqu’il arrive.

1. Activez le SDK. Voir Installer et configurer le SDK Capacitor.
2. Chargez et affichez un paywall avec getFlow comme d’habitude — n’attendez pas l’attribution.
3. Abonnez-vous aux mises à jour du profil avec adapty.addListener('onLatestProfileLoad', …) et surveillez 'apple_search_ads'. Quand il apparaît, récupérez à nouveau le paywall et affichez celui mis à jour. Si vous n’avez pas encore configuré le listener, consultez Écouter les mises à jour d’abonnement :

const listener = await adapty.addListener('onLatestProfileLoad', async ({ profile }) => {
  if (!profile.appliedExternalAttributionProviders?.includes('apple_search_ads')) return;
  const targeted = await adapty.getFlow({ placementId });
  // present the targeted flow in place of the first one
});

// Call listener.remove() after the upgrade, or after a timeout (see below).

4. Arrêtez d’écouter après un délai. La plupart des utilisateurs ne reçoivent jamais d’attribution Apple Ads, alors supprimez l’écouteur au bout d’un moment plutôt que de le garder actif pour toute la session. Configurez un paywall de secours pour le placement afin que l’utilisateur voie toujours quelque chose si une requête échoue.

Exemple complet

onAppleAdsAttribution se résout une fois l’attribution Apple Ads appliquée, ou expire après timeoutMs. L’exemple ci-dessous charge un paywall immédiatement, puis le recharge quand l’attribution arrive — les utilisateurs Apple Ads obtiennent le paywall ciblé, et si l’attribution n’arrive jamais, le premier paywall reste en place :

const APPLE_ADS_PROVIDER = 'apple_search_ads';
const placementId = 'YOUR_PLACEMENT_ID';

function hasAppleAdsAttribution(profile: AdaptyProfile): boolean {
  return profile.appliedExternalAttributionProviders?.includes(APPLE_ADS_PROVIDER) ?? false;
}

/**
 * Resolves once Apple Ads attribution is applied to the profile.
 * Rejects with a timeout error if attribution never arrives within `timeoutMs`.
 * Call after `adapty.activate()`.
 */
export function onAppleAdsAttribution(timeoutMs: number): Promise<void> {
  return new Promise((resolve, reject) => {
    let timer: ReturnType<typeof setTimeout> | undefined;
    let handle: { remove: () => void } | undefined;

    const stop = () => {
      clearTimeout(timer);
      handle?.remove();
    };

    adapty
      .addListener('onLatestProfileLoad', ({ profile }) => {
        if (!hasAppleAdsAttribution(profile)) return;
        stop();
        resolve();
      })
      .then(listener => {
        handle = listener;
      });

    timer = setTimeout(() => {
      stop();
      reject(new Error(`Apple Ads attribution timed out after ${timeoutMs}ms`));
    }, timeoutMs);
  });
}

let flow = await adapty.getFlow({ placementId });

onAppleAdsAttribution(30_000)
  .then(() => adapty.getFlow({ placementId }))
  .then(updated => {
    flow = updated;
  })
  .catch(() => {
    console.log('Apple Ads attribution or loading failed');
  });

Au premier lancement, un utilisateur Apple Ads voit brièvement le paywall par défaut avant qu’il soit remplacé. Si vous affichez des paywalls avec le Paywall Builder, décidez si le ré-affichage est acceptable, ou appliquez la mise à jour uniquement avant que le paywall ne soit affiché. Ajustez timeoutMs selon le temps que vous souhaitez attendre — l’attribution qui arrive le fait généralement en quelques secondes après le lancement.

Si votre application écoute déjà onLatestProfileLoad à d’autres fins (par exemple, vérifier le statut de l’abonnement), vous n’avez pas besoin de la modifier. adapty.addListener prend en charge plusieurs écouteurs indépendants, ce qui permet d’en ajouter un sans affecter les autres.