Capacitor SDK'da ilk başlatmada AA hedefli paywall göster

Apple Ads (AA) attribution, adapty.activate() çağrısından sonra asenkron olarak gelir. İlk açılışta genellikle henüz gelmemiş olur; bu nedenle getFlow, varsayılan kitle için çözümlenir ve Apple Ads kullanıcıları AA segmentine özel paywallı kaçırır. Paywall’ı attribution gelene kadar geciktirmek yerine hemen bir paywall gösterin ve AA attribution uygulandığında yenileyin — böylece Apple Ads kullanıcıları hedeflenmiş varyantı görürken diğer herkes de bekleme yaşamadan bir paywall görür. AdaptyProfile.appliedExternalAttributionProviders, AA attribution’ın ne zaman uygulandığını size bildirir.

Başlamadan önce

İhtiyacınız olanlar:

• Adapty Capacitor SDK 3.17.1 veya üstü.
• Uygulamanız için Adapty’de Apple Ads yapılandırılmış olmalı. Bkz. Apple Ads.

Nasıl çalışır

adapty.activate() çağrısının ardından SDK, arka planda Apple’dan Apple Ads attribution verilerini ister ve sonucu Adapty’nin backend’ine iletir. AA, profil için aktif attribution kaynağı haline geldiğinde, SDK onLatestProfileLoad dinleyicinize güncellenmiş bir AdaptyProfile iletir; bu profilin appliedExternalAttributionProviders dizisinde 'apple_search_ads' bulunur.

Bu sayede paywall’ı iki adımda yükleyebilirsiniz:

1. getFlow’u hemen çağırın. Henüz herhangi bir attribution uygulanmamış olduğundan Adapty, isteği varsayılan kitleye göre çözümler ve kullanıcı anında bir paywall görür.
2. 'apple_search_ads' göründüğünde getFlow’u tekrar çağırın. Adapty artık isteği Apple Ads kitlesine göre çözümler ve ilkinin yerini alan hedefli paywall’ı döndürür.

appliedExternalAttributionProviders boş olabilir ya da hiç bulunmayabilir. Bu şu anlama gelir:

• Bu profil için Apple Ads attribution’ı henüz işlenmemiştir, veya
• hiç attribution gelmemiştir.

Her iki durumda da 1. adım güvenlidir — Adapty, isteği mevcut profil durumuyla eşleşen kitleye göre çözümler; bu genellikle varsayılan kitlendir. 2. adım yalnızca 'apple_search_ads' göründüğünde çalışır.

Uygulama

Hemen bir paywall göster, ardından 'apple_search_ads' olayını dinle ve geldiğinde paywall’ı yenile.

1. SDK’yı etkinleştirin. Bkz. Capacitor SDK’yı yükleyin ve yapılandırın.
2. Bir paywall yükleyin ve gösterin — getFlow ile her zamanki gibi yapın, attribution için beklemeyin.
3. Profil güncellemelerini dinleyin — adapty.addListener('onLatestProfileLoad', …) ile 'apple_search_ads' verisini izleyin. Göründüğünde paywall’ı yeniden çekip güncel olanı gösterin. Dinleyiciyi henüz kurmadıysanız bkz. Abonelik güncellemelerini dinleyin:

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. Zaman aşımından sonra dinlemeyi durdurun. Kullanıcıların büyük çoğunluğu hiçbir zaman Apple Ads attribution verisi almaz; bu nedenle dinleyiciyi tüm oturum boyunca açık tutmak yerine bir süre sonra kaldırın. İstek başarısız olduğunda kullanıcının her zaman bir şey görmesini sağlamak için placement’a bir yedek paywall yapılandırın.

Tam örnek

onAppleAdsAttribution, Apple Ads attribution uygulandığında çözümlenir ya da timeoutMs süresinde reddedilir. Aşağıdaki kullanımda paywall hemen yüklenir, ardından attribution geldiğinde yeniden getirilir — Apple Ads kullanıcıları hedeflenmiş paywalli görür; attribution hiç gelmezse ilk paywall geçerli kalır:

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

İlk başlatmada, Apple Ads kullanıcısı varsayılan paywallı kısaca görür ve ardından yenisiyle değiştirilir. Paywallları Paywall Builder ile sunuyorsanız, yeniden sunmanın kabul edilebilir olup olmadığına karar verin ya da güncellemeyi yalnızca paywall gösterilmeden önce uygulayın. timeoutMs değerini ne kadar süre dinlemeye hazır olduğunuza göre ayarlayın — gelmekte olan attribution genellikle başlatmanın birkaç saniyesi içinde ulaşır. Uygulamanız halihazırda başka amaçlarla onLatestProfileLoad dinliyorsa (örneğin, abonelik durumunu kontrol etmek için), herhangi bir değişiklik yapmanıza gerek yok. adapty.addListener birden fazla bağımsız dinleyiciyi destekler; bu nedenle kendi dinleyicisi, diğerlerini etkilemeden eklenir.