Flutter SDK'da ilk açılışta AA hedefli paywall gösterme

Bu makale, uygulamanızın iOS build’i 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ş olduğundan, hemen getFlow çağırırsanız Adapty isteği varsayılan kitleye göre çözümler ve Apple Ads kullanıcıları AA segmentinize özel paywallı göremez. Bir paywallı gösterip sonra değiştirmek yerine, herhangi bir şey görüntülemeden önce AA attribution için kısa bir süre bekleyin: attribution kısa bir zaman aşımı içinde gelirse hedefli paywallı, gelmezse varsayılan kitle paywallını gösterin. AdaptyProfile.appliedExternalAttributionProviders, AA attributionunun uygulanıp uygulanmadığını size bildirir.

Başlamadan önce

İhtiyacınız olanlar:

• Adapty Flutter SDK 4.1 veya üzeri. 4.0.x sürümünde, profil özelliğinin adı appliedAttributionSources ve değerleri AdaptyAttributionSource’dur — bkz. v4.1’e Geçiş. 3.17.0–3.x sürümlerinde, flow’lar da getPaywall/getPaywallForDefaultAudience ile çekilir ve döndürülen tür AdaptyPaywall’dur — bkz. v4.0’a Geçiş.
• Adapty’de uygulama için 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 verisini talep eder ve sonucu Adapty’nin backend’ine iletir. AA, profil için aktif attribution kaynağı haline geldiğinde SDK, didUpdateProfileStream dinleyicinize güncellenmiş bir AdaptyProfile iletir; bu profilin appliedExternalAttributionProviders listesinde AdaptyExternalAttributionProvider.appleAds yer alır.

İlk başlatmada ele almanız gereken iki olası sonuç vardır:

1. Attribution, zaman aşımı süreniz içinde gelir. getFlow çağrısı yapın — Adapty, isteği Apple Ads kitlesine göre değerlendirir ve hedeflenmiş paywall’ı döndürür.
2. Önce zaman aşımı gerçekleşir. Bunun yerine varsayılan kitle paywall’ını gösterin; böylece Apple Ads attribution’ı olmayan kullanıcılar beklemez. getFlowForDefaultAudience bunu segmentasyon beklemeden döndürür.

appliedExternalAttributionProviders boş olabilir. Bu, aşağıdakilerden birini ifade eder:

• 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 getFlowForDefaultAudience çağrısı güvenlidir — profil durumundan bağımsız olarak varsayılan kitle paywall’ını döndürür.

Uygulama

İlk başlatmada AdaptyExternalAttributionProvider.appleAds beklentisine girin ve kesin bir zaman aşımı uygulayın — Apple Ads attribution hiç gelmese bile, o kullanıcıların yine de bir paywall görmesi gerekir.

1. SDK’yı etkinleştirin. Bkz. Flutter SDK’yı yükle ve yapılandır.
2. Profil güncellemelerine abone olun: Adapty().didUpdateProfileStream.listen(…). Henüz listener kurulmadıysa bkz. Abonelik güncellemelerini dinle.
3. appliedExternalAttributionProviders içinde AdaptyExternalAttributionProvider.appleAds değerini izleyin. Bu değer göründüğünde, getFlow ile paywall’ı yükleyin — Adapty, AA segmentli varyantı döndürür:

final subscription = Adapty().didUpdateProfileStream.listen((profile) async {
  if (!profile.appliedExternalAttributionProviders.contains(AdaptyExternalAttributionProvider.appleAds)) return;
  final paywall = await Adapty().getFlow(placementId: placementId);
  // present the segmented paywall, then cancel the subscription and the timer
});

didUpdateProfileStream bir broadcast stream’dir ve yeniden oynatma yapmaz; bu nedenle getProfile() ile mevcut profili bir kez de doğrudan kontrol edin. Uygulama yeniden başlatıldığında, kaydedilmiş attribution zaten uygulanmış olur ve yeniden emit edilmez.

4. Abonelikle paralel olarak 3–5 saniyelik bir zamanlayıcı başlatın. Zamanlayıcı, AdaptyExternalAttributionProvider.appleAds görünmeden önce tetiklenirse, bunun yerine getFlowForDefaultAudience ile varsayılan kitle paywall’unu yükleyin. İlk çözümlenen paywall’u görüntüleyin ve diğer yolu iptal edin; böylece paywall iki kez çekilmez. Kullanıcının ağ isteği başarısız olduğunda takılıp kalmaması için placement’a bir yedek paywall yapılandırın.

Tam Örnek

Aşağıdaki uygulama, attribution’ı bir zaman aşımıyla yarıştırır, varsayılan kitle paywall’ını paralel olarak önceden getirir ve uygun olan paywall’ı döndürür. Çağıran taraf tek bir fonksiyonu bekler — çağrı noktasında yönetilecek listener ya da durum bayrağı yoktur:

• Attribution, timeout süresi içinde gelirse getFlow aracılığıyla segmente edilmiş paywall’ı döndürür.
• timeout süresi önce dolarsa getFlowForDefaultAudience aracılığıyla önceden getirilmiş varsayılan kitle paywall’ını döndürür.

/// Returns the Apple Ads-segmented paywall if attribution is applied within
/// [timeout], otherwise the default-audience paywall. Call after Adapty().activate().
Future<AdaptyFlow> getFlowOrDefault({
  required String placementId,
  required Duration timeout,
}) {
  // Prefetch the default-audience paywall right away so the timeout path resolves
  // without an extra network round-trip. `getFlowForDefaultAudience` skips the
  // wait for segmentation data. `..ignore()` keeps an unused prefetch from surfacing
  // as an unhandled error; the error still reaches the caller if this paywall wins.
  final defaultPaywall =
      Adapty().getFlowForDefaultAudience(placementId: placementId)..ignore();

  final completer = Completer<AdaptyFlow>();
  late final StreamSubscription<AdaptyProfile> subscription;
  late final Timer timer;

  void resolve(Future<AdaptyFlow> paywall) {
    if (completer.isCompleted) return;
    timer.cancel();
    subscription.cancel();
    completer.complete(paywall);
  }

  void onProfile(AdaptyProfile profile) {
    if (profile.appliedExternalAttributionProviders.contains(AdaptyExternalAttributionProvider.appleAds)) {
      resolve(Adapty().getFlow(placementId: placementId));
    }
  }

  // Attribution path: react to profile updates as attribution is applied.
  subscription = Adapty().didUpdateProfileStream.listen(onProfile);

  // The stream is a broadcast stream and doesn't replay, so check the current
  // profile too — on relaunches attribution is already stored and won't re-emit.
  Adapty().getProfile().then(onProfile).ignore();

  // Timeout path: fall back to the prefetched default-audience paywall.
  timer = Timer(timeout, () => resolve(defaultPaywall));

  return completer.future;
}

Splash ekranınızdan çağırın, ardından tamamlandığında paywallı gösterin:

try {
  final paywall = await getFlowOrDefault(
    placementId: 'YOUR_PLACEMENT_ID',
    timeout: const Duration(seconds: 5),
  );
  // present the paywall
} on AdaptyError catch (adaptyError) {
  // handle the error or show a fallback paywall
} catch (e) {
  // handle the error
}

timeout değerini, kullanıcılarınızı herhangi bir paywall görünmeden önce ne kadar bekletmek istediğinize göre ayarlayın. Kullanıcıların büyük çoğunluğunun Apple Ads attribution verisi olmadığını düşünürsek, hepsi tam timeout süresini bekler; bu yüzden 3 ila 5 saniye makul bir denge noktasıdır. Gelmesi beklenen attribution verisi genellikle uygulama açılışından birkaç saniye içinde ulaşır.

Uygulamanız başka amaçlarla (örneğin, abonelik durumunu kontrol etmek için) zaten didUpdateProfileStream’i dinliyorsa, herhangi bir değişiklik yapmanıza gerek yok. didUpdateProfileStream bir broadcast stream olduğundan, birbirinden bağımsız birden fazla dinleyiciyi destekler ve bunları birbirini etkilemeden kullanabilirsiniz.