Afficher un paywall ciblé par Apple Ads au premier lancement dans React Native SDK

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, ce qui fait que getFlow se résout sur l’audience par défaut et que les utilisateurs Apple Ads ratent votre paywall segmenté AA. Plutôt que d’attendre l’attribution avant d’afficher le paywall, affichez-en un immédiatement et rafraîchissez-le dès que l’attribution AA est appliquée — ainsi les utilisateurs Apple Ads voient la variante ciblée et les autres n’attendent pas. AdaptyProfile.appliedExternalAttributionProviders vous indique quand l’attribution AA a été appliquée.

Avant de commencer

Vous avez besoin de :

• SDK React Native Adapty 4.1 ou version ultérieure. En versions 3.17.1–4.0.x, la propriété du profil s’appelle appliedAttributionSources et les flows sont récupérés avec getPaywall.
• Apple Ads configuré pour l’application dans Adapty. Voir Apple Ads.

Comment ça fonctionne

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. Lorsque AA devient la source d’attribution active pour le profil, le SDK transmet 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 appliquée, Adapty résout la requête selon l’audience par défaut, et l’utilisateur voit un paywall aussitôt.
2. Quand 'apple_search_ads' apparaît, appelez getFlow à nouveau. Adapty résout alors la requête selon l’audience Apple Ads et renvoie le paywall ciblé, qui remplace le premier.

appliedExternalAttributionProviders peut être vide ou absent. Cela signifie l’une des choses suivantes :

• 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 en fonction de 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 l’événement 'apple_search_ads' et actualisez le paywall dès qu’il arrive.

1. Activez le SDK. Consultez Installer et configurer le SDK React Native.
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.addEventListener('onLatestProfileLoad', …) et surveillez l’apparition de 'apple_search_ads'. Quand il apparaît, rechargez le paywall et affichez la version mise à jour. Si vous n’avez pas encore configuré le listener, consultez Écouter les mises à jour d’abonnement :

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

// Call subscription.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, donc supprimez l’écouteur au bout d’un moment plutôt que de le laisser ouvert pendant 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 est rejetée après timeoutMs. L’exemple ci-dessous charge un paywall immédiatement, puis le récupère à nouveau lorsque 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 subscription: { remove: () => void } | undefined;

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

    subscription = adapty.addEventListener('onLatestProfileLoad', profile => {
      if (!hasAppleAdsAttribution(profile)) return;
      stop();
      resolve();
    });

    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');
  });

Lors du premier lancement, un utilisateur Apple Ads aperçoit brièvement le paywall par défaut avant qu’il ne soit remplacé. Si vous affichez des paywalls avec le Paywall Builder, décidez si le réaffichage est acceptable, ou n’appliquez la mise à jour qu’avant l’affichage du paywall. Ajustez timeoutMs en fonction du temps que vous êtes prêt à attendre — une attribution en cours d’acheminement arrive généralement dans les quelques secondes suivant le lancement.

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