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

L’attribution Apple Ads (AA) arrive de façon asynchrone après adapty.activate(). Au premier lancement, elle n’est généralement pas encore disponible, donc getFlow se résout par rapport à l’audience par défaut et les utilisateurs Apple Ads ratent votre paywall segmenté AA. Plutôt que de retarder le paywall jusqu’à la réception de l’attribution, affichez-en un immédiatement et actualisez-le dès que l’attribution AA est appliquée — ainsi, les utilisateurs Apple Ads voient la variante ciblée et les autres voient un paywall sans attente. AdaptyProfile.appliedAttributionSources vous indique quand l’attribution AA a été appliquée.

Avant de commencer

Vous avez besoin de :

• SDK Adapty Capacitor 3.17.1 ou version ultérieure.
• Apple Ads configuré pour l’application dans Adapty. Voir Apple Ads.

Fonctionnement

Après adapty.activate(), le SDK demande l’attribution Apple Ads à Apple en arrière-plan et transmet le résultat au backend d’Adapty. Quand 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 appliedAttributionSources.

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

1. Appelez getFlow immédiatement. Sans attribution appliquée, Adapty résout la requête par rapport à l’audience par défaut, et l’utilisateur voit un paywall tout de suite.
2. Quand 'apple_search_ads' apparaît, appelez à nouveau getFlow. Adapty résout alors la requête par rapport à l’audience Apple Ads et retourne le paywall ciblé, qui remplace le premier.

appliedAttributionSources peut être vide ou absent. Cela signifie soit :

• L’attribution Apple Ads n’a pas encore été traitée pour ce profil, soit
• aucune attribution n’est arrivée du tout.

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

Implémentation

Affichez un paywall immédiatement, puis écoutez 'apple_search_ads' et actualisez le paywall dès qu’il arrive.

1. Activez le SDK. Voir Installer et configurer le SDK Capacitor.
2. Chargez et affichez un paywall avec getFlow comme d’habitude — ne bloquez pas sur 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 le mis à jour. Si vous n’avez pas encore configuré le listener, voir Écouter les mises à jour d’abonnement :

const listener = await adapty.addListener('onLatestProfileLoad', async ({ profile }) => {
  if (!profile.appliedAttributionSources?.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 d’expiration. La plupart des utilisateurs ne reçoivent jamais d’attribution Apple Ads, donc supprimez le listener au bout d’un moment plutôt que de le garder ouvert pour toute la session. Configurez un paywall de secours pour le placement afin que l’utilisateur voie toujours quelque chose en cas d’échec d’une requête.

Exemple complet

onAppleAdsAttribution se résout dès que l’attribution Apple Ads est appliquée, ou rejette après timeoutMs. L’utilisation ci-dessous charge un paywall immédiatement, puis le récupère à nouveau 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_SOURCE = 'apple_search_ads';
const placementId = 'YOUR_PLACEMENT_ID';

function hasAppleAdsAttribution(profile: AdaptyProfile): boolean {
  return profile.appliedAttributionSources?.includes(APPLE_ADS_SOURCE) ?? 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 la re-présentation est acceptable, ou appliquez la mise à jour uniquement avant que le paywall soit affiché. Ajustez timeoutMs en fonction du temps pendant lequel vous souhaitez garder l’écoute active — 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 le modifier. adapty.addListener prend en charge plusieurs listeners indépendants, donc celui-ci s’ajoute sans affecter les autres.