Flow ve paywall'ları alma - Capacitor

Flow’unuzu tasarladıktan sonra onu mobil uygulamanızda gösterebilirsiniz. İlk adım, aşağıda açıklandığı gibi placement ile ilişkili flow veya paywall’ı ve görünüm yapılandırmasını almaktır.

Bu konunun, Adapty’nin builder’larında tasarlanan flow’lar ve paywall’lar için geçerli olduğunu unutmayın. Özel paywall’lar uyguluyorsanız lütfen Mobil uygulamanızda özel paywall’lar için paywall ve ürünleri çekme konusuna bakın.

Başlamadan önce

İhtiyacınız olanlar:

• Adapty Kontrol Paneli’ndeki ürünler: Ürünlerinizi oluşturun.
• Ürünlere sahip bir flow: Bunu Flow & Paywall Builder’da oluşturun ve ona ürünler atayın.
• Bir placement: Placement oluşturun ve flow’unuzu ona atayın.
• Adapty SDK kurulu: Capacitor SDK kurulum kılavuzuna bakın.

Flow/paywall getirme

Bir flow veya paywall’ı builder’da tasarladıysanız, kullanıcıya göstermek için onu mobil uygulama kodunuzda render etmeniz gerekmez. Bu tür bir flow veya paywall, içinde neyin ve nasıl gösterileceğini zaten içerir. Bununla birlikte, placement aracılığıyla ID’sini, görünüm yapılandırmasını almanız ve ardından mobil uygulamanızda sunmanız gerekir.

Flow veya paywall’ı mümkün olduğunca erken — ideal olarak sunmadan çok önce — çekin ve view’unu oluşturun. createFlowView metodu, view yapılandırmasını yükler ve arka planda görsellerini indirip önbelleğe almaya başlar. Bu metodu ne kadar erken çağırırsanız, indirmelerin tamamlanması için o kadar çok zaman kalır. Flow veya paywall’ı sunduğunuzda, yapılandırma ve görseller zaten önbellekte hazır olabilir.

Bir flow veya paywall almak için getFlow metodunu kullanın:

try {
  const flow = await adapty.getFlow({
    placementId: 'YOUR_PLACEMENT_ID',
  });
  // istenen flow/paywall
} catch (error) {
  // hatayı işle
}

Parametreler:

Parametre	Zorunluluk	Açıklama
placementId	zorunlu	İstenen Placement’ın tanımlayıcısı. Bu, Adapty Kontrol Paneli’nde bir placement oluştururken belirttiğiniz değerdir.
fetchPolicy	varsayılan: 'reload_revalidating_cache_data'	İsteğe bağlı params nesnesi içinde iletilir. fetchPolicy, SDK’nın önbelleği kullanıp kullanamayacağını değil, hangi katmanı önce okuyacağını belirler. Varsayılan olarak SDK önce sunucuya gider ve istek başarısız olursa önbelleğe alınmış veriyi döndürür. Bu varyantı öneriyoruz çünkü kullanıcılarınızın her zaman en güncel veriyi almasını sağlar. Ancak kullanıcılarınızın kararsız internet bağlantısıyla uğraştığını düşünüyorsanız 'return_cache_data_else_load' seçeneğini değerlendirin; bu seçenek sırayı tersine çevirir — önce önbelleği okur, yalnızca önbellekte hiçbir şey yoksa sunucuya gider. Kullanıcılar en güncel veriyi almayabilir, ancak internet bağlantıları ne kadar kesintili olursa olsun daha hızlı yükleme süresi yaşarlar. Önbellek düzenli olarak güncellenir, bu nedenle ağ isteklerinden kaçınmak için oturum sırasında kullanmak güvenlidir. Üçüncü bir politika olan 'return_cache_data_if_not_expired_else_load', ikisi arasında yer alır: önbelleğe alınmış kopya, yanında ilettiğiniz maxAgeSeconds değerinden daha tazeyken önce önbelleği okur, daha eski olduğunda sunucuya gider. Önbelleğin uygulama yeniden başlatıldığında bozulmadan kaldığını, yalnızca uygulama yeniden yüklendiğinde veya manuel temizlik yapıldığında silindiğini unutmayın. Adapty SDK, paywallları yerel olarak iki katmanda depolar: yukarıda açıklanan düzenli olarak güncellenen önbellek ve yedek paywalllar. Paywallları daha hızlı getirmek için CDN ve CDN’e erişilemediğinde bağımsız bir yedek sunucu da kullanıyoruz. Bu sistem, internet bağlantısının yetersiz olduğu durumlarda bile güvenilirliği sağlarken her zaman paywalllarınızın en son sürümünü almanızı garanti edecek şekilde tasarlanmıştır.
loadTimeoutMs	varsayılan: 5 sn	İsteğe bağlı params nesnesi içinde iletilir. Bu değer, bu metodun zaman aşımını sınırlar. Zaman aşımına ulaşılırsa önbelleğe alınmış veriler veya yerel yedek döndürülür. Nadir durumlarda bu metodun loadTimeoutMs içinde belirtilenden biraz daha geç zaman aşımına uğrayabileceğini unutmayın; çünkü işlem arka planda farklı isteklerden oluşabilir.

Ürün ID’lerini kodun içine gömmeyин. Kodun içine gömmeniz gereken tek şey placement ID’sidir. Flow’lar ve paywall’lar uzaktan yapılandırıldığından, ürün sayısı ve mevcut teklifler her an değişebilir. Uygulamanız bu değişiklikleri dinamik olarak ele almalıdır; bir paywall bugün iki ürün döndürüyorsa ve yarın üç ürün döndürüyorsa, kod değişikliği yapmadan hepsini gösterin.

Yanıt parametreleri:

Parametre	Açıklama
Flow	Flow’un tanımlayıcılarını (id, variationId), adını, placement’ını, paywall varyasyonlarını (paywalls), remote config’lerini (remoteConfigs) ve bir hasViewConfiguration bayrağını içeren AdaptyFlow nesnesi.

Görünüm yapılandırmasını getirme

Placement Flow & Paywall Builder veya eski Paywall Builder ile tasarlandıysa Adapty, kullanıcı arayüzünü sizin için render eder. createFlowView ile görünümü oluşturun, ardından flow veya paywall’ı gösterin. Placement, Builder arayüzü olmayan özel bir paywall ise bunun yerine kendi render işleminizi yapın.

hasViewConfiguration bayrağı, görünümü oluşturmadan önce ikisini birbirinden ayırt etmenizi sağlar:

if (flow.hasViewConfiguration) {
  const view = await createFlowView(flow);
  await view.present();
} else {
  // Render your own screen from flow.remoteConfigs and flow.paywalls
}

Capacitor SDK’da doğrudan createFlowView çağırın — önce görünüm yapılandırmasını almanız gerekmez.

try {
  const view = await createFlowView(flow);
} catch (error) {
  // handle the error
}

Parametreler:

Parametre	Zorunluluk	Açıklama
flow	zorunlu	İstenen flow/paywall için bir controller elde etmek amacıyla kullanılan AdaptyFlow nesnesi.
locale	isteğe bağlı	Görünümü render etmek için kullanılacak flow yerelleştirmesinin tanımlayıcısı — örneğin en veya pt-br. Belirtilmezse görünüm en dilinde render edilir; flow’un en yerelleştirmesi yoksa flow’un varsayılan yerelleştirmesi kullanılır. Bkz. Yerelleştirmeler ve yerel ayar kodları.
customLayoutId	isteğe bağlı varsayılan: undefined SDK 4.1+	Flow’un layout yapılandırmasındaki bir layout’un özel kimliği. SDK’nın cihaz türü ve ekran boyutuna göre otomatik seçtiği layout yerine belirli bir layout’u render etmek için bu kimliği iletin. Kimlikle eşleşen bir layout bulunamazsa çağrı, no-view-configuration hatası ile başarısız olur. Flow & Paywall Builder henüz özel layout kimliği atamamaktadır, bu nedenle bu değeri ayarlamadan bırakın.
customTags	isteğe bağlı	Uygulamanızın flow’daki özel etiketler için değerleri; her etiketin tam adı ile anahtarlanmış bir nesne olarak. Ayrıntılar için Flow’lara veri iletme bölümünü okuyun.
prefetchProducts	isteğe bağlı	Ekrandaki ürünlerin görüntülenme zamanlamasını optimize etmek için etkinleştirin. true olduğunda AdaptyUI gerekli ürünleri otomatik olarak getirir. Varsayılan: true.
android.enableSafeArea	isteğe bağlı	Yalnızca Android (ios’ta yoksayılır). android anahtarının altında yer alır. true olduğunda flow görünümü güvenli alan dolguları uygular. Varsayılan: true. Varsayılan değer çoğu durum için uygundur.

Görünümü elde ettikten sonra flow/paywall’ı gösterin.

Varsayılan kitle için flow veya paywall getirerek daha hızlı yükleme sağlayın

Genellikle flow’lar ve paywall’lar neredeyse anında getirilir, bu nedenle bu süreci hızlandırmak için endişelenmenize gerek yoktur. Ancak çok sayıda kitle ve placement’ınız varsa ve kullanıcılarınızın internet bağlantısı zayıfsa, bir flow veya paywall getirmek istediğinizden daha uzun sürebilir. Bu gibi durumlarda, hiçbir şey göstermemek yerine sorunsuz bir kullanıcı deneyimi sağlamak amacıyla varsayılan bir flow veya paywall görüntülemek isteyebilirsiniz.

Bunu çözmek için, belirtilen placement’ın All Users kitlesi için flow veya paywall’ı getiren getFlowForDefaultAudience metodunu kullanabilirsiniz. Ancak şunu anlamak kritik önem taşır: önerilen yaklaşım, yukarıdaki Flow/paywall getirme bölümünde ayrıntılı olarak açıklanan getFlow metoduyla flow veya paywall’ı getirmektir.

try {
  const flow = await adapty.getFlowForDefaultAudience({
    placementId: 'YOUR_PLACEMENT_ID',
  });
  // the requested flow/paywall
} catch (error) {
  // handle the error
}

Parametre	Zorunluluk	Açıklama
placementId	zorunlu	Placement tanımlayıcısı. Adapty Kontrol Paneli’nde bir placement oluştururken belirttiğiniz değerdir.
fetchPolicy	varsayılan: 'reload_revalidating_cache_data'	İsteğe bağlı params nesnesi içinde geçirilir. fetchPolicy, SDK’nın önbellekten yararlanıp yararlanamayacağını değil, hangi katmanı önce okuyacağını belirler. Varsayılan olarak SDK önce sunucuya gider; bu istek başarısız olursa önbelleğe alınan verileri döndürür. Kullanıcılarınızın her zaman en güncel verileri almasını sağladığından bu seçeneği öneriyoruz. Ancak kullanıcılarınızın kararsız bir internet bağlantısıyla çalıştığını düşünüyorsanız 'return_cache_data_else_load' seçeneğini değerlendirin. Bu seçenek sırayı tersine çevirir: önce önbelleği okur, hiçbir şey önbellekte yoksa sunucuya gider. Kullanıcılar en güncel veriye her zaman ulaşamayabilir; ancak internet bağlantıları ne kadar düzensiz olursa olsun daha hızlı yükleme süreleri yaşarlar. Önbellek düzenli olarak güncellenir; bu nedenle oturum sırasında ağ isteklerini azaltmak için güvenle kullanılabilir. Üçüncü bir politika olan 'return_cache_data_if_not_expired_else_load' ise ikisi arasında bir denge kurar: önbelleğe alınan kopya, birlikte geçirdiğiniz maxAgeSeconds değerinden daha yeniyse önce önbelleği okur; daha eskiyse sunucuya gider. Önbelleğin uygulama yeniden başlatıldığında korunduğunu ve yalnızca uygulama yeniden yüklendiğinde ya da manuel temizlik yapıldığında silindiğini unutmayın.

Varlıkları özelleştirin

Flow/paywall’unuzdaki görsel ve videoları özelleştirmek için özel varlıklar kullanabilirsiniz.

Hero görsel ve videoların önceden tanımlanmış ID’leri vardır: hero_image ve hero_video. Özel bir varlık paketinde, bu öğeleri ID’leri aracılığıyla hedefleyebilir ve davranışlarını özelleştirebilirsiniz.

Diğer görsel ve videolar için Adapty kontrol panelinde özel bir ID belirlemeniz gerekir.

Örneğin şunları yapabilirsiniz:

• Bazı kullanıcılara farklı bir görsel veya video gösterin.
• Uzak bir ana görsel yüklenirken yerel bir önizleme görseli gösterin.
• Bir video çalıştırmadan önce önizleme görseli gösterin.
• Uygulamayla birlikte gelen medyayı gösterin; böylece ilk ekran indirme yapılmadan render edilir. Bkz. İlk ekran medyasını uygulama paketinden göster.

Özel varlıkları basit bir sözlük aracılığıyla nasıl sağlayabileceğinize dair bir örnek:

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

const view = await createFlowView(flow, { customAssets });

Adapty Kontrol Paneli’ndeki eski Paywall Builder ile paywallınızın görsel tasarımını oluşturduktan sonra, bunu mobil uygulamanızda gösterebilirsiniz. Bu sürecin ilk adımı, aşağıda açıklandığı gibi placement ile ilişkili paywallı ve görünüm yapılandırmasını almaktır.

Bu konunun Paywall Builder ile özelleştirilmiş paywalllarla ilgili olduğunu unutmayın. Özel paywallları getirme hakkında bilgi almak için Mobil uygulamanızda özel paywalllar için paywallları ve ürünleri getirme konusuna başvurun.

Mobil uygulamanızda paywall’ları görüntülemeye başlamadan önce (genişletmek için tıklayın)

1. Adapty Kontrol Paneli’nde ürünlerinizi oluşturun.
2. Adapty Kontrol Paneli’nde bir paywall oluşturun ve ürünleri ekleyin.
3. Adapty Kontrol Paneli’nde placement’lar oluşturun ve paywall’ınızı ekleyin.
4. Mobil uygulamanıza Adapty SDK’yı yükleyin.

Paywall Builder ile Tasarlanmış Paywall’ı Getirme

Paywall Builder ile bir paywall tasarladıysanız, bunu kullanıcıya göstermek için mobil uygulama kodunuzda render etmeniz gerekmez. Böyle bir paywall, hem gösterilecek içeriği hem de nasıl gösterileceğini içerir. Bununla birlikte, paywall’ın ID’sini placement aracılığıyla, görünüm yapılandırmasını ise ayrıca almanız ve ardından mobil uygulamanızda sunmanız gerekir.

En iyi performansı sağlamak için, paywall’u ve onun görünüm yapılandırmasını mümkün olduğunca erken almanız kritik önem taşır; böylece görseller kullanıcıya sunulmadan önce indirilmesi için yeterli zaman olur.

Bir paywall almak için getPaywall metodunu kullanın:

try {
  const paywall = await adapty.getPaywall({
    placementId: 'YOUR_PLACEMENT_ID',
    locale: 'en',
  });
  // istenen paywall
} catch (error) {
  // hatayı işle
}

Parametreler:

Parametre	Zorunluluk	Açıklama
placementId	zorunlu	İstenen Placement’ın tanımlayıcısı. Bu, Adapty Kontrol Paneli’nde bir placement oluştururken belirttiğiniz değerdir.
locale	isteğe bağlı varsayılan: en	Paywall yerelleştirmesinin tanımlayıcısı. Bu parametrenin, eksi (-) karakteriyle ayrılmış bir veya iki alt etiketten oluşan bir dil kodu olması beklenir. İlk alt etiket dil için, ikincisi ise bölge içindir. Örnek: en İngilizce anlamına gelir, pt-br Brezilya Portekizcesini temsil eder. Yerelleştirmeler ve yerel ayar kodları hakkında daha fazla bilgi için ilgili sayfaya bakın.
params	isteğe bağlı	Paywall’ı getirmek için ek parametreler.

Ürün ID’lerini sabit kodlamayın. Sabit kodlamanız gereken tek ID, placement ID’sidir. Paywall’lar uzaktan yapılandırıldığından, ürün sayısı ve mevcut teklifler her an değişebilir. Uygulamanız bu değişiklikleri dinamik olarak ele almalıdır; bir paywall bugün iki ürün, yarın üç ürün döndürüyorsa, kod değişikliği yapmadan hepsini göstermelidir.

Yanıt parametreleri:

Parametre	Açıklama
Paywall	Ürün ID’leri listesi, paywall tanımlayıcısı, remote config ve diğer çeşitli özellikleri içeren bir AdaptyPaywall nesnesi.

Paywall Builder ile tasarlanan paywallın görünüm yapılandırmasını getir

Paywallı getirdikten sonra, Paywall Builder kullanılarak oluşturulduğunu gösteren bir ViewConfiguration içerip içermediğini kontrol et. Bu, paywallı nasıl görüntüleyeceğini belirlemene yardımcı olur. ViewConfiguration mevcutsa Paywall Builder paywallı olarak değerlendir; değilse özel paywall olarak işle.

Capacitor SDK’sında, önce view konfigürasyonunu manuel olarak almadan doğrudan createPaywallView metodunu çağırın.

if (paywall.hasViewConfiguration) {
  try {
    const view = await createPaywallView(paywall);
  } catch (error) {
    // handle the error
  }
} else {
  // use your custom logic
}

Parametreler:

Parametre	Zorunluluk	Açıklama
paywall	zorunlu	İstenen paywall için bir controller elde etmek üzere kullanılan AdaptyPaywall nesnesi.
customTags	isteğe bağlı	Özel etiketlerin ve çözümlenmiş değerlerinin bir sözlüğünü tanımlar. Özel etiketler, paywall içeriğinde yer tutucu olarak işlev görür ve paywall içinde kişiselleştirilmiş içerik sunmak için belirli dizelerle dinamik olarak değiştirilir. Daha fazla ayrıntı için Paywall builder’da özel etiketler konusuna bakın.
prefetchProducts	isteğe bağlı	Ekranda ürünlerin görüntülenme zamanlamasını optimize etmek için etkinleştirin. true olarak ayarlandığında AdaptyUI, gerekli ürünleri otomatik olarak getirir. Varsayılan: false.

Görünüme sahip olduktan sonra paywallı gösterin.

Varsayılan kitle için paywallı daha hızlı getir

Genellikle paywalllar neredeyse anında getirilir, bu yüzden bu süreci hızlandırmak için endişelenmenize gerek yoktur. Ancak çok sayıda kitle ve paywallınız varsa ve kullanıcılarınızın internet bağlantısı zayıfsa, bir paywallı getirmek istediğinizden daha uzun sürebilir. Bu durumlarda, hiç paywall göstermemek yerine sorunsuz bir kullanıcı deneyimi sağlamak için varsayılan bir paywall görüntülemek isteyebilirsiniz.

Bunu çözmek için, belirtilen placement’ın paywall’ını All Users kitlesi için getiren getPaywallForDefaultAudience metodunu kullanabilirsiniz. Ancak şunu bilmeniz önemlidir: önerilen yaklaşım, paywall’ı yukarıdaki Paywall Bilgisini Getirme bölümünde açıklandığı gibi getPaywall metoduyla getirmektir.

try {
  const paywall = await adapty.getPaywallForDefaultAudience({
    placementId: 'YOUR_PLACEMENT_ID',
    locale: 'en',
  });
  // istenen paywall
} catch (error) {
  // hatayı işleyin
}

Parametre	Zorunluluk	Açıklama
placementId	zorunlu	Placement tanımlayıcısı. Adapty Kontrol Paneli’nde bir placement oluştururken belirttiğiniz değerdir.
locale	isteğe bağlı varsayılan: en	Paywall yerelleştirmesinin tanımlayıcısı. Bu parametre, eksi (-) karakteriyle ayrılmış bir veya daha fazla alt etiketten oluşan bir dil kodu olmalıdır. İlk alt etiket dili, ikincisi ise bölgeyi belirtir. Örnek: en İngilizce, pt-br ise Brezilya Portekizcesini temsil eder. Yerel ayar kodları ve bunların nasıl kullanılması gerektiği hakkında daha fazla bilgi için Yerelleştirmeler ve yerel ayar kodları bölümüne bakın.
params	isteğe bağlı	Paywall’ı getirmek için ek parametreler.

Varlıkları özelleştirin

Paywallınızdaki görselleri ve videoları özelleştirmek için özel varlıkları uygulayın.

Hero görseller ve videoların önceden tanımlanmış ID’leri vardır: hero_image ve hero_video. Özel bir varlık paketinde bu öğeleri ID’lerine göre hedefleyerek davranışlarını özelleştirirsiniz.

Diğer görseller ve videolar için Adapty kontrol panelinde özel bir ID ayarlamanız gerekir.

Örneğin şunları yapabilirsiniz:

• Bazı kullanıcılara farklı bir görsel veya video gösterebilirsiniz.
• Uzaktaki ana görsel yüklenirken yerel bir önizleme görseli gösterebilirsiniz.
• Video başlamadan önce bir önizleme görseli gösterebilirsiniz.

İşte özel varlıkları basit bir sözlük aracılığıyla nasıl sağlayabileceğinize dair bir örnek:

const customAssets: Record<string, AdaptyCustomAsset> = {
  'custom_image': { type: 'image', relativeAssetPath: 'custom_image.png' },
  'hero_video': {
    type: 'video',
    fileLocation: {
      ios: { fileName: 'custom_video.mp4' },
      android: { relativeAssetPath: 'videos/custom_video.mp4' }
    }
  }
};

view = await createPaywallView(paywall, { customAssets });