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

Bu makale, uygulamanızın iOS derlemesi için geçerlidir. Apple Ads attribution yalnızca iOS’ta mevcuttur.

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 4.1 veya üzeri. 3.17.1–4.0 sürümlerinde profil özelliğinin adı appliedAttributionSources’tır ve 3.17.1, paywall’ları getPaywall yerine getFlow ile çeker.
• Uygulamanız için Adapty’de yapılandırılmış Apple Ads. 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. Hemen getFlow çağırın. Henüz hiçbir attribution uygulanmadığından, Adapty isteği varsayılan kitle üzerinden çözümler ve kullanıcı anında bir paywall görür.
2. 'apple_search_ads' göründüğünde, getFlow tekrar çağırın. Adapty artık isteği Apple Ads kitlesi üzerinden çözümler ve ilk paywall’ın yerini alan hedeflenmiş paywall’ı döndürür.

appliedExternalAttributionProviders boş veya mevcut olmayabilir. Bu, aşağıdakilerden biri anlamına gelir:

• Bu profil için Apple Ads attribution henüz işlenmedi.
• Hiç attribution gelmedi.
• Attribution başka bir sağlayıcıdan geldi; bu dizi onu raporlamıyor.

Her üç durumda da 1. adım güvenlidir — Adapty, isteği mevcut profil durumuyla eşleşen kitleye (genellikle varsayılan kitle) göre çözümler. 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.