Mostrar un paywall orientado a Apple Ads en el primer lanzamiento con React Native SDK

Este artículo se aplica a la compilación iOS de tu app. La atribución de Apple Ads solo existe en iOS.

La atribución de Apple Ads (AA) llega de forma asíncrona después de adapty.activate(). En el primer lanzamiento normalmente aún no ha llegado, por lo que getFlow resuelve contra la audiencia predeterminada y los usuarios de Apple Ads no ven el paywall segmentado por AA. En lugar de retrasar el paywall hasta que llegue la atribución, muestra uno de inmediato y actualízalo una vez que se aplique la atribución de AA, para que los usuarios de Apple Ads obtengan la variante segmentada y el resto no tenga que esperar. AdaptyProfile.appliedExternalAttributionProviders te indica cuándo se ha aplicado la atribución de AA.

Antes de comenzar

Necesitas:

• Adapty React Native SDK 4.1 o posterior. En las versiones 3.17.1–4.0.x, la propiedad del perfil se llama appliedAttributionSources y los flows se obtienen con getPaywall.
• Apple Ads configurado para la app en Adapty. Consulta Apple Ads.

Cómo funciona

Tras llamar a adapty.activate(), el SDK solicita en segundo plano los datos de atribución de Apple Ads a Apple y reenvía el resultado al backend de Adapty. Cuando AA se convierte en la fuente de atribución activa para el perfil, el SDK entrega un AdaptyProfile actualizado a tu listener onLatestProfileLoad, con 'apple_search_ads' en su array appliedExternalAttributionProviders.

Esto te permite cargar el paywall en dos pasos:

1. Llama a getFlow de inmediato. Sin atribución aplicada todavía, Adapty resuelve la solicitud frente a la audiencia predeterminada, por lo que el usuario ve un paywall de inmediato.
2. Cuando aparece 'apple_search_ads', llama a getFlow de nuevo. Adapty ahora resuelve la solicitud frente a la audiencia de Apple Ads y devuelve el paywall segmentado, que reemplaza al primero.

appliedExternalAttributionProviders puede estar vacío o ausente. Eso significa una de las siguientes cosas:

• La atribución de Apple Ads aún no se ha procesado para este perfil.
• No ha llegado ninguna atribución.
• La atribución llegó de otro proveedor, que este array no registra.

En los tres casos, el paso 1 es seguro: Adapty resuelve la solicitud según la audiencia que coincida con el estado actual del perfil, normalmente la audiencia predeterminada. El paso 2 solo se ejecuta cuando aparece 'apple_search_ads'.

Implementación

Muestra el paywall de inmediato y luego escucha el evento 'apple_search_ads' para actualizar el paywall cuando llegue.

1. Activa el SDK. Consulta Instalar y configurar el SDK de React Native.
2. Carga y muestra un paywall con getFlow como de costumbre — no bloquees esperando la atribución.
3. Suscríbete a actualizaciones del perfil con adapty.addEventListener('onLatestProfileLoad', …) y espera 'apple_search_ads'. Cuando aparezca, vuelve a obtener el paywall y muestra el actualizado. Si aún no has configurado el listener, consulta Escuchar actualizaciones de suscripción:

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. Detén la escucha tras un tiempo de espera. La mayoría de los usuarios nunca reciben atribución de Apple Ads, así que elimina el listener después de un tiempo en lugar de mantenerlo abierto toda la sesión. Configura un paywall de respaldo para el placement para que el usuario siempre vea algo si una solicitud falla.

Ejemplo completo

onAppleAdsAttribution se resuelve una vez que se aplica la atribución de Apple Ads, o se rechaza tras timeoutMs. El siguiente ejemplo carga un paywall de inmediato y lo vuelve a obtener cuando llega la atribución; los usuarios de Apple Ads reciben el paywall personalizado y, si la atribución nunca llega, el primer paywall permanece activo:

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

Al primer lanzamiento, un usuario de Apple Ads ve brevemente el paywall predeterminado antes de que sea reemplazado. Si presentas paywalls con el Paywall Builder, decide si volver a presentarlo es aceptable, o aplica la actualización solo antes de mostrar el paywall. Ajusta timeoutMs según cuánto tiempo estés dispuesto a esperar — la atribución que está en camino suele llegar a los pocos segundos del lanzamiento.

Si tu app ya escucha onLatestProfileLoad para otros fines (por ejemplo, comprobar el estado de la suscripción), no necesitas cambiarlo. adapty.addEventListener admite múltiples listeners independientes, así que este añade el suyo sin afectar a los demás.