Capacitor SDKで初回起動時にAA向けペイウォールを表示する

この記事はアプリのiOSビルドに適用されます。Apple AdsのアトリビューションはiOSのみに存在します。

Apple Ads (AA) のアトリビューションは adapty.activate() の後に非同期で届きます。初回起動時にはまだ届いていないことが多いため、getFlow はデフォルトのオーディエンスに対して解決され、Apple Ads ユーザーが AA セグメント向けのペイウォールを見逃してしまいます。アトリビューションが届くまでペイウォールの表示を遅らせるのではなく、すぐにペイウォールを表示し、AA アトリビューションが適用されたタイミングでリフレッシュしましょう。そうすることで、Apple Ads ユーザーはターゲット向けのバリアントを受け取り、それ以外のユーザーは待たずにペイウォールを見られます。AA アトリビューションが適用されたかどうかは AdaptyProfile.appliedExternalAttributionProviders で確認できます。

Important

appliedExternalAttributionProviders はApple Adsのみを報告します。他のプロバイダーからのアトリビューションはユーザープロファイルに表示され、セグメントフィルターでも利用できますが、ここではまだサポートされていません。

始める前に

必要なもの：

Adapty Capacitor SDK 4.1 以降。3.17.1〜4.0 では、プロファイルプロパティの名前が appliedAttributionSources となっており、3.17.1 では getFlow の代わりに getPaywall でペイウォールを取得します。
アプリに Apple Ads が Adapty で設定済みであること。Apple Ads を参照してください。

仕組み

adapty.activate() を呼び出すと、SDKはバックグラウンドでApple AdsのアトリビューションをAppleに要求し、結果をAdaptyのバックエンドに転送します。AAがプロファイルの有効なアトリビューションソースになると、SDKは更新された AdaptyProfile を onLatestProfileLoad リスナーに届けます。このとき、appliedExternalAttributionProviders 配列に 'apple_search_ads' が含まれます。

これにより、ペイウォールを2つのステップで読み込むことができます：

すぐにgetFlowを呼び出します。まだアトリビューションが適用されていないため、Adaptyはデフォルトのオーディエンスに対してリクエストを解決し、ユーザーにすぐにペイウォールが表示されます。
'apple_search_ads'が現れたら、getFlowを再度呼び出します。AdaptyはApple Adsオーディエンスに対してリクエストを解決し、ターゲットに合ったペイウォールを返します。これにより最初のペイウォールが置き換えられます。

appliedExternalAttributionProvidersは空または存在しない場合があります。その場合、以下のいずれかを意味します：

このプロファイルのApple Adsアトリビューションがまだ処理されていない。
アトリビューションがまだ届いていない。
別のプロバイダーからアトリビューションが届いたが、この配列には含まれない。

いずれの場合も、ステップ1は安全です。Adaptは現在のプロファイル状態に一致するオーディエンスに対してリクエストを解決します（通常はデフォルトのオーディエンス）。ステップ2は'apple_search_ads'が現れたときにのみ実行されます。

Important

その後の起動では、キャッシュされたプロファイルにすでに appliedExternalAttributionProviders 内に 'apple_search_ads' が含まれているため、最初の getFlow からすでにApple Ads向けセグメントのペイウォールが返されます。2回目のフェッチや表示の切り替えは発生しません。この2ステップのフローが重要なのは、アトリビューションがまだ処理中の初回起動時のみです。

実装

ペイウォールをすぐに表示し、'apple_search_ads' を受信したらペイウォールを更新します。

SDKを有効化します。 Capacitor SDKのインストールと設定をご覧ください。
getFlowを使ってペイウォールを読み込み、表示します — アトリビューションを待たずに進めてください。
adapty.addListener('onLatestProfileLoad', …)でプロファイルの更新を購読し、'apple_search_ads'が現れるのを監視します。これが表示されたら、ペイウォールを再取得して更新済みのものを表示してください。まだリスナーを設定していない場合は、サブスクリプション更新のリッスンをご覧ください。

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).

タイムアウト後にリスナーを停止する。 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 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');
  });

初回起動時、Apple Ads ユーザーにはデフォルトのペイウォールが一瞬表示された後、差し替えられます。ペイウォールビルダーでペイウォールを表示している場合は、再表示が許容できるかどうかを判断するか、ペイウォールを表示する前にアップグレードを適用してください。timeoutMs は、どのくらいの時間待ち受けるかに合わせて調整してください。アトリビューションが届く場合、通常は起動から数秒以内に到着します。

アプリがすでに別の目的（例：サブスクリプション状態の確認）のために onLatestProfileLoad をリッスンしている場合、変更の必要はありません。adapty.addListener は複数の独立したリスナーをサポートしているため、既存のリスナーに影響を与えることなく、新しいリスナーを追加できます。