Capacitor SDK'da mağaza mesajlarını kontrol edin

App Store ve Google Play, zaman zaman kullanıcılarınıza abonelikleriyle ilgili bir mesaj göstermesi gerekebilir:

  • App Store: Fiyat artışına onay isteği, fatura sorunu bildirimi veya geri kazanma teklifi. StoreKit, bu mesajları varsayılan olarak uygulamanız açıkken kendi kendine gösterir.
  • Google Play: Abonelik ödemesinin reddedildiğine ve ödeme yönteminin güncellenmesi gerektiğine dair bildirim. SDK 4.3.0’dan itibaren Adapty SDK, activate işleminden sonra uygulamanızın her Activity başlangıcında (uygulamanın ön plana döndüğü durumlar dahil) bu mesajları varsayılan olarak talep eder.

Bir mesaj, flow’un, onboarding’in veya ödeme ekranının üzerinde görünebilir. Mesajın ne zaman gösterileceğini kendiniz seçmek için Adapty SDK’yı manuel mesaj yönetimine geçirin ve showStoreMessages fonksiyonunu kullanıcıyı rahatsız etmeyecek bir anda çağırın.

Warning

Manuel modda, mağazalar mesajları kendi başlarına göstermez. Uygulamanız hiçbir zaman showStoreMessages çağırmazsa, kullanıcılar fiyat artışı onay talebini, faturalama sorunu bildirimini veya reddedilen ödeme bildirimini asla göremez.

Başlamadan önce

İhtiyacınız olanlar:

  • Adapty Capacitor SDK 4.3.0 veya üzeri: Önceki sürümlerde mağaza mesajları API’si bulunmamaktadır.
  • iOS 16 veya üzeri App Store mesajları için: StoreKit, önceki sürümlerdeki uygulamalara mesaj iletmez. iOS 15’te getPendingStoreMessageTypes ve showStoreMessages fonksiyonları decodingFailed hatasını fırlatır; bu nedenle uygulamanız iOS 15’i destekliyorsa, aşağıdaki örneklerde olduğu gibi hatayı yakalayın.

Manuel işlemeyi etkinleştirme

Mağaza mesajlarını yalnızca uygulamanız showStoreMessages çağırdığında göstermek için, SDK’yı etkinleştirirken storeMessagesHandling değerini 'manual' olarak ayarlayın:


await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    storeMessagesHandling: 'manual', // 'auto' is the default
  },
});

iOS’ta SDK, her App Store mesajını mevcut uygulama oturumu için bekleyen bir listeye ekler. Android’de ise SDK, Google Play mesajlarını kendi başına istemeyi durdurur. Varsayılan 'auto' değeriyle SDK, App Store mesajlarını yakalamaz; bu nedenle iOS’ta getPendingStoreMessageTypes ve showStoreMessages döndürecek veya gösterecek bir şey bulamaz.

Bekleyen mesaj türlerini alma

iOS’ta App Store mesajlarının bekleyip beklemediğini öğrenmek için getPendingStoreMessageTypes fonksiyonunu çağırın. Bu fonksiyon, mesajları göstermeden veya kaldırmadan bekleyen mesajların türlerini döndürür:

try {
  const pendingTypes = await adapty.getPendingStoreMessageTypes();

  if (pendingTypes === null) {
    // Android: Google Play decides whether a message applies when you show it
    await adapty.showStoreMessages();
  } else if (pendingTypes.includes('billing_issue')) {
    // For example, skip the upsell and show the billing message first
  }
} catch (error) {
  // On iOS 15, the call fails with decodingFailed (2006)
}

Android’de bu metot, native SDK çağrılmadan null döner: Google Play bekleyen mesajları bildirmez ve bir mesajın uygulanıp uygulanmayacağına yalnızca uygulamanız talep ettiğinde karar verir. Boş bir dizi, iOS’ta bekleyen mesaj olmadığı anlamına gelir. activate tamamlanana kadar dizi her zaman boştur.

Her App Store mesajı şu türlerden birine sahiptir:

TürMesaj
genericGenel bir App Store mesajı.
price_increase_consentAbonelik fiyat artışını onaylama isteği.
billing_issueAbonelik faturalama sorununa ilişkin bir bildirim. iOS 16.4 ve sonrasında kullanılabilir.
win_back_offerUygun bir geri kazanma teklifi. iOS 18 ve sonrasında kullanılabilir.

Yeni StoreKit mesaj türleri storekit_<number> değeriyle gelir. Bu tablodaki değerlerin dışındaki değerleri, SDK’nın tanımadığı bir tür olarak ele alın.

Mesajları göster

Uygulamanız, mağaza mesajının kullanıcıyı rahatsız etmeyeceği bir noktaya ulaştığında — örneğin kullanıcı bir flow’u kapattıktan veya onboarding’i tamamladıktan sonra — showStoreMessages fonksiyonunu çağırın:

try {
  await adapty.showStoreMessages();
} catch (error) {
  // handle the error
}
  • iOS: SDK, bekleyen mesajları birbiri ardına gösterir. StoreKit bir mesajı gösterdikten sonra SDK, onu bekleyen listesinden kaldırır. StoreKit bir mesajı göstermeyi başaramazsa, SDK mesajı bir sonraki çağrı için saklar ve diğer mesajlarla devam eder.
  • Android: SDK, geçerli Activity için Google Play mesajları ister. Google Play bir mesajın kullanıcıya uygulanıp uygulanmayacağına karar verdiğinden, yapılan istek her zaman mesaj göstermez. Çağrı, Google Play’i beklemeden hemen döner ve Google Play hatalarını bildirmez. Kullanıcı ödeme yöntemini mesajdan düzeltirse SDK, kullanıcının satın alımlarını Adapty ile senkronize eder ve profil dinleyiciniz güncellenmiş access level’ı alır.

Android’de Başlangıçta Mesajları Gösterme

Varsayılan 'auto' modunda, uygulamanızı barındıran Activity, activate çalışmadan önce başlar; bu nedenle bir istek tetiklenmez ve Google Play mesajları başlangıçta görünmez. Başlangıçta göstermek için, yalnızca Android’de activate’ten sonra bir kez showStoreMessages çağırın:


await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY' });

if (Capacitor.getPlatform() === 'android') {
  await adapty.showStoreMessages();
}

iOS’ta bu çağrıyı yapmayın: 'auto' modunda gösterecek hiçbir şey yoktur ve iOS 15’te başarısız olur.

Yalnızca belirli mesaj türlerini göster

Bekleyen App Store mesajlarının yalnızca bir kısmını göstermek için ios.filter parametresine türleri geçin. Diğer mesajlar beklemede kalır:

await adapty.showStoreMessages({
  ios: { filter: ['billing_issue', 'price_increase_consent'] },
});

filter kullanılmazsa SDK, tanımadığı türler dahil tüm bekleyen mesajları gösterir. Boş bir dizi hiçbir mesajı göstermez. Android, filter parametresini dikkate almaz ve tüm Google Play mesajlarını talep eder.

Hatalar

iOS’ta showStoreMessages, aşağıdaki kodlardan biriyle bir AdaptyError fırlatır:

KodAdNeden
2006decodingFailedCihaz iOS 15 veya daha eski bir sürüm çalıştırıyor. Bu metodu yalnızca iOS 16 ve sonrasında çağırın.
3201operationInProgressBaşka bir showStoreMessages çağrısı zaten mesajları gösteriyor ve bu çağrının da gösterilecek mesajları var. İlk çağrı tamamlanana kadar bekleyip tekrar deneyin.
3202resolverFailureSDK, mesajları göstermek için ön planda aktif bir pencere sahnesi bulamadı. Hata öncesinde gösterilen mesajlar bekleyen listesinden çıkarılır. Geri kalanları göstermek için uygulamanız ön plandayken metodu tekrar çağırın.