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

Apple Ads (AA) attribution, adapty.activate() sonrasında asenkron olarak gelir. İlk açılışta genellikle henüz gelmemiş olduğundan, getFlow varsayılan kitleye göre çözümlenir ve Apple Ads kullanıcıları AA-segmentli paywallınızı kaçırır. Paywall’ı attribution gelene kadar geciktirmek yerine, hemen bir tane gösterin ve AA attribution uygulandığında yenileyin; böylece Apple Ads kullanıcıları hedefli varyantı görürken diğer herkes hiç beklemeden bir paywall görür. AdaptyProfile.appliedAttributionSources, 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 verisi 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 profildeki appliedAttributionSources dizisinde 'apple_search_ads' yer alır.

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

1. getFlow’u hemen çağırın. Henüz attribution uygulanmadığından Adapty isteği varsayılan kitleye göre çözümler ve kullanıcı hemen 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ümleyerek hedeflenmiş paywall’ı döndürür ve bu paywall ilkinin yerini alır.

appliedAttributionSources boş olabilir veya hiç bulunmayabilir. Bu şu anlama gelir:

• Bu profil için Apple Ads attribution henüz işlenmemiştir ya da
• hiç attribution gelmemiştir. Her iki durumda da 1. adım güvenlidir — Adapty, isteği mevcut profil durumuna göre eşleşen kitleyle, genellikle varsayılan kitleyle çözümler. 2. adım yalnızca 'apple_search_ads' göründükten sonra ç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.appliedAttributionSources?.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_SOURCE = 'apple_search_ads';
const placementId = 'YOUR_PLACEMENT_ID';

function hasAppleAdsAttribution(profile: AdaptyProfile): boolean {
  return profile.appliedAttributionSources?.includes(APPLE_ADS_SOURCE) ?? 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.