在 React Native SDK 中首次启动时显示 AA 定向付费墙

本文适用于您应用的 iOS 构建版本。Apple Ads 归因仅在 iOS 上可用。

Apple Ads (AA) 归因数据会在 adapty.activate() 之后异步到达。在首次启动时，归因数据通常尚未落地，因此 getFlow 会根据默认目标受众进行解析，Apple Ads 用户将错过你为 AA 细分设置的付费墙。与其等待归因数据到达后再展示付费墙，不如立即展示一个，等 AA 归因应用后再刷新——这样 Apple Ads 用户能看到定向的实验变体，其他用户也无需等待。AdaptyProfile.appliedExternalAttributionProviders 可以告知你 AA 归因何时已被应用。

Important

此属性仅报告 Apple Ads 数据。来自其他提供商的归因数据可在用户画像中查看，也可用于市场细分筛选，但目前尚不在此处显示。

开始之前

你需要：

Adapty React Native SDK 4.1 或更高版本。在 3.17.1–4.0.x 版本中，用户画像属性名为 appliedAttributionSources，流程通过 getPaywall 获取。
在 Adapty 中为应用配置 Apple Ads。详见 Apple Ads。

工作原理

调用 adapty.activate() 后，SDK 会在后台向 Apple 请求 Apple Ads 归因数据，并将结果转发给 Adapty 后端。当 AA 成为该用户画像的有效归因来源时，SDK 会向你的 onLatestProfileLoad 监听器推送更新后的 AdaptyProfile，其 appliedExternalAttributionProviders 数组中将包含 'apple_search_ads'。

这样你就可以分两步加载付费墙：

立即调用 getFlow。由于尚未应用任何归因，Adapty 会根据默认目标受众解析请求，因此用户可以立即看到付费墙。
当 'apple_search_ads' 出现时，再次调用 getFlow。Adapty 此时会根据 Apple Ads 目标受众解析请求，并返回目标付费墙，替换第一个付费墙。

appliedExternalAttributionProviders 可以为空或不存在，这意味着以下情况之一：

Apple Ads 归因尚未处理到该用户画像。
完全没有收到归因数据。
归因来自其他渠道，该数组不会上报此类数据。

以上三种情况下，第 1 步都是安全的——Adapty 会根据当前用户画像状态匹配对应的目标受众，通常为默认受众。第 2 步仅在 'apple_search_ads' 出现后才会执行。

Important

在每次后续启动时，缓存的用户画像已在 appliedExternalAttributionProviders 中包含 'apple_search_ads'，因此第一次 getFlow 就会直接返回按 Apple Ads 细分的付费墙——不会有第二次请求或任何可见变化。这个两步流程只在首次启动时有意义，因为此时归因数据仍在传输中。

实现

立即展示付费墙，然后监听 'apple_search_ads' 事件，待其到达后刷新付费墙。

激活 SDK。 请参阅安装并配置 React Native SDK。
使用 getFlow 正常加载并展示付费墙 — 不要等待归因数据。
通过 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).

超时后停止监听。 大多数用户不会获得 Apple Ads 归因数据，因此请在一段时间后移除监听器，而不是在整个会话中保持其开启。为版位配置备用付费墙，这样即使请求失败，用户也能看到内容。

完整示例

onAppleAdsAttribution 在 Apple Ads 归因成功应用后 resolve，或在 timeoutMs 超时后 reject。下面的示例会立即加载付费墙，然后在归因数据到达时重新获取——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 用户会短暂看到默认付费墙，随后被替换。如果你使用付费墙编辑工具展示付费墙，请决定是否接受重新展示，或仅在付费墙显示之前进行更新。根据你愿意等待的时长来调整 timeoutMs——通常情况下，归因数据会在启动后几秒内到达。

如果你的应用已经出于其他目的监听 onLatestProfileLoad（例如检查订阅状态），则无需做任何修改。adapty.addEventListener 支持多个独立监听器，因此这里只是新增一个，不会影响其他监听器。