Показ пейвола с таргетингом Apple Ads при первом запуске в React Native SDK

Эта статья относится к iOS-сборке вашего приложения. Атрибуция Apple Ads доступна только на iOS.

Атрибуция Apple Ads (AA) поступает асинхронно после вызова adapty.activate(). При первом запуске она, как правило, ещё не получена, поэтому getFlow разрешается по аудитории по умолчанию, и пользователи Apple Ads не попадают на пейвол, сегментированный по AA. Вместо того чтобы откладывать показ пейвола до получения атрибуции, покажите его сразу, а затем обновите после применения атрибуции AA — так пользователи Apple Ads увидят целевой вариант, а остальные не будут ждать. AdaptyProfile.appliedExternalAttributionProviders сообщает о том, что атрибуция AA применена.

Перед началом работы

Вам потребуется:

• SDK для React Native 4.1 или новее. В версиях 3.17.1–4.0.x свойство профиля называется appliedAttributionSources, а флоу загружаются через getPaywall.
• Apple Ads, настроенный для приложения в Adapty. См. Apple Ads.

Как это работает

После вызова adapty.activate() SDK в фоновом режиме запрашивает данные атрибуции Apple Ads у Apple и передаёт результат на бэкенд Adapty. Когда AA становится активным источником атрибуции для профиля, SDK доставляет обновлённый AdaptyProfile в ваш слушатель onLatestProfileLoad, где в массиве appliedExternalAttributionProviders появится значение 'apple_search_ads'.

Это позволяет загружать пейвол в два шага:

1. Вызовите getFlow сразу. Поскольку атрибуция ещё не применена, Adapty разрешает запрос против аудитории по умолчанию, и пользователь сразу видит пейвол.
2. Когда появляется 'apple_search_ads', вызовите getFlow снова. Теперь Adapty разрешает запрос против аудитории Apple Ads и возвращает целевой пейвол, который заменяет первый.

appliedExternalAttributionProviders может быть пустым или отсутствовать. Это означает одно из следующего:

• Атрибуция Apple Ads для этого профиля ещё не обработана.
• Атрибуция не поступала вовсе.
• Атрибуция поступила от другого провайдера, который этот массив не отслеживает.

Во всех трёх случаях шаг 1 безопасен — Adapty разрешает запрос относительно той аудитории, которая соответствует текущему состоянию профиля, как правило это аудитория по умолчанию. Шаг 2 выполняется только после появления 'apple_search_ads'.

Реализация

Покажите пейвол сразу, затем ждите события 'apple_search_ads' и обновляйте пейвол при его получении.

1. Активируйте SDK. См. Установка и настройка React Native SDK.
2. Загрузите и покажите пейвол с помощью getFlow как обычно — не блокируйте выполнение в ожидании атрибуции.
3. Подпишитесь на обновления профиля через adapty.addEventListener('onLatestProfileLoad', …) и отслеживайте появление 'apple_search_ads'. Когда оно появится, снова загрузите пейвол и покажите обновлённый. Если вы ещё не настроили слушатель, см. Отслеживание обновлений подписки:

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. Остановите прослушивание по таймауту. Большинство пользователей никогда не получают атрибуцию Apple Ads, поэтому вместо того чтобы держать слушателя открытым на протяжении всей сессии, удалите его через некоторое время. Настройте резервный пейвол для плейсмента, чтобы пользователь всегда что-то видел в случае неудачного запроса.

Полный пример

onAppleAdsAttribution завершается успешно, когда атрибуция Apple Ads применена, или отклоняется по истечении timeoutMs. В примере ниже пейвол загружается сразу, а затем перезапрашивается, когда приходит атрибуция — пользователи Apple Ads получают целевой пейвол, а если атрибуция так и не придёт, остаётся первоначальный пейвол:

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

При первом запуске пользователи Apple Ads на мгновение видят пейвол по умолчанию, прежде чем он заменяется. Если вы показываете пейволы с помощью Paywall Builder, решите, допустимо ли повторное отображение, или применяйте обновление только до того, как пейвол был показан. Настройте timeoutMs в соответствии с тем, как долго вы готовы ждать атрибуцию — она, как правило, приходит в течение нескольких секунд после запуска.

Если ваше приложение уже слушает onLatestProfileLoad для других целей (например, проверки статуса подписки), менять ничего не нужно. adapty.addEventListener поддерживает несколько независимых слушателей, так что этот добавляется сам по себе, не затрагивая остальные.