Mostrar un paywall dirigido por AA en el primer inicio con Capacitor SDK

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 se pierden el paywall segmentado por AA. En lugar de retrasar el paywall hasta que llegue la atribución, muestra uno inmediatamente y actualízalo una vez que se aplique la atribución de AA — así los usuarios de Apple Ads obtienen la variante segmentada y todos los demás ven un paywall sin espera. AdaptyProfile.appliedExternalAttributionProviders te indica cuándo se ha aplicado la atribución de AA.

Antes de empezar

Necesitas:

• Adapty Capacitor SDK 3.17.1 o posterior.
• Apple Ads configurado para la app en Adapty. Consulta Apple Ads.

Cómo funciona

Tras adapty.activate(), el SDK solicita en segundo plano la 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 del 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 ninguna atribución aplicada todavía, Adapty resuelve la solicitud según la audiencia predeterminada, por lo que el usuario ve un paywall inmediatamente.
2. Cuando aparece 'apple_search_ads', llama a getFlow de nuevo. Adapty ahora resuelve la solicitud según la audiencia de Apple Ads y devuelve el paywall segmentado, que reemplaza al primero.

appliedExternalAttributionProviders puede estar vacío o ausente. Eso significa que:

• La atribución de Apple Ads aún no se ha procesado para este perfil, o
• no ha llegado ninguna atribución todavía.

En cualquier caso, 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 una vez que 'apple_search_ads' aparece.

Implementación

Muestra un paywall de inmediato, luego escucha 'apple_search_ads' y actualiza el paywall cuando llegue.

1. Activa el SDK. Consulta Instala y configura el SDK de Capacitor.
2. Carga y muestra un paywall con getFlow como de costumbre — no bloquees la ejecución esperando la atribución.
3. Suscríbete a las actualizaciones del perfil con adapty.addListener('onLatestProfileLoad', …) y comprueba si aparece 'apple_search_ads'. Cuando aparezca, vuelve a obtener el paywall y muestra el actualizado. Si todavía no has configurado el listener, consulta Escucha las actualizaciones de suscripción:

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. 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 pasado un tiempo en lugar de mantenerlo abierto durante toda la sesión. Configura un paywall de respaldo para el placement para que el usuario siempre vea algo si falla una solicitud.

Ejemplo completo

onAppleAdsAttribution se resuelve cuando 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 ven el paywall personalizado y, si la atribución nunca llega, el primer paywall se mantiene:

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

Al primer lanzamiento, un usuario de Apple Ads verá brevemente el paywall predeterminado antes de que se reemplace. 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 el tiempo que quieras esperar — la atribución que está en camino suele llegar en pocos segundos tras el lanzamiento. Si tu app ya escucha onLatestProfileLoad para otros propósitos (por ejemplo, comprobar el estado de la suscripción), no necesitas cambiarlo. adapty.addListener admite múltiples listeners independientes, así que este añade el suyo propio sin afectar a los demás.