Upgrade/downgrade subscriptions

Photo by Paul Hanaoka on Unsplash

In app purchase entegrasyonu olan bir uygulamanız varsa ve abonelik hizmeti sağlıyorsanız kullanıcılarınıza farklı abonelik planları sunabilirsiniz.

Yazının devamını okumadan önce kafanızda basitçe şekillenmesi amacıyla aşağıdaki videoyu izlemenizi öneririm.

Upgrade/downgrade nedir?

Basit bir örnek vermek gerekirse aylık 10 tl olan ve yıllık 100 tl olan iki farklı subscription tier tanımlayabilirsiniz. Kullanıcınız ihtiyacı dahilinde uygun olan tierdaki subscriptionı satın alabilir. Mevcutta aylık 10 tl olan tierı kullanan kullanıcınız isteği dahilinde yıllık 100 tl olan tiera geçebilir.

Upgrade/downgrade yaparken developerlar olarak kullanımını tercih ettiğimiz duruma bağlı olarak farklı proration modelar üzerinden seçim yapabiliyoruz. 4 farklı proration mode mevcut:

1. IMMEDIATE_WITH_TIME_PRORATION:
   Varsayılan modedur. Abonelik hemen upgrade ya da downgrade olur. Kalan süre, fiyat farkına göre ayarlanır ve bir sonraki fatura tarihi kaydırılarak yeni aboneliğe eklenir.
2. IMMEDIATE_AND_CHARGE_PRORATED_PRICE: Abonelik hemen yükseltilir ve faturalandırma döngüsü aynı kalır. Kalan süre için fiyat farkı daha sonra kullanıcıya fatura edilir.
3. IMMEDIATE_WITHOUT_PRORATION: Abonelik hemen yükseltilir veya düşürülür ve abonelik yenilendiğinde yeni fiyat alınır. Fatura döngüsü aynı kalır.
4. DEFERRED:
   Abonelik, yalnızca yenilenme zamanı geldiğinde yükseltilir veya düşürülür.

Proration modelarının ne anlama geldiğini daha iyi anlamak adına birkaç usecase üzerinden geçebiliriz.

Diyelim ki bir A kullanıcısı bir app üzerinden abonelik hizmeti satın almış olsun. Bu hizmet yalnızca text içeriklerine erişimi sağlayan Tier 1 aboneliği olsun. Bu hizmet kullanıcımıza ayda 2 tl’ye malolsun ve her ayın başında yenilenebilir olsun.

A kullanıcısının 15 Nisan’da abonelik hizmetini aylık olan Tier 1'den yıllık olan ve text içeriğine ek olarak video içeriklerine de erişmeye izin veren 36 tl tutarındaki Tier 2'ye upgrade etmeyi seçtiğini düşünelim. Developerımız upgrade işlemi için bir proration mode seçmiş olsun. Her bir proration modun A kullanıcımızın aboneliğini ne şekilde etkileyebileceğini gelin beraber inceleyelim.

1. IMMEDIATE_WITH_TIME_PRORATION:
   A kullanıcısının Tier 1 aboneliği hemen sona erer. Tam bir ay için (1–30 Nisan) ödeme yaptığı ancak abonelik süresinin yarısında abonelik planı yükseldiği için, aylık aboneliğin yarısı (1 tl) yeni aboneliğine uygulanır. Ancak, bu yeni aboneliğin yıllık maliyeti 36 tl olduğundan, 1 tl kredi bakiyesi yalnızca 10 günü (16–25 Nisan) öder, bu nedenle 26 Nisan’da yeni bir abonelik için 36 tl ve sonraki her yıl 26 Nisan’da 36 tl olarak ücretlendirilir.
2. IMMEDIATE_AND_CHARGE_PRORATED_PRICE:
   Belli bir zaman dilimi başına (bu case için aylık düşünebiliriz) Tier 2 abonelik fiyatı (36 tl yıllık / 3 tl aylık), Tier 1 abonelik fiyatından (2 tl aylık) yüksek olduğu için bu mod kullanılabilir. A kullanıcısının Tier 1 aboneliği hemen sona erer. Tam bir ay ödediği ancak yalnızca yarısını kullandığı için, aylık aboneliğin yarısı (1 tl) yeni aboneliğine uygulanır. Ancak, bu yeni aboneliğin maliyeti yıllık 36 tl yani aylık 3 tl olduğu için, kalan 15 gün 1,5 tldir. Bu nedenle yeni aboneliği için 0,50 tl ve 1 Mayıs’ta 35,50 tl daha tahsil edilir. Bundan sonraki yıllarda, A kullanıcısından her yıl 36 tl ücret alınır.
3. IMMEDIATE_WITHOUT_PRORATION:
   A kullanıcısının Tier 1 aboneliği, herhangi bir ek ücret olmaksızın anında Tier 2'ye yükseltilir ve 1 Mayıs’ta yeni abonelik için 36 tl ve sonraki her yıl 1 Mayıs’ta 36 tl olarak ücretlendirilir.
4. DEFERRED:
   A kullanıcısının Tier 1 aboneliği 30 Nisan’da sona erene kadar devam eder. 1 Mayıs’ta, Tier 2 aboneliği yürürlüğe girer ve A kullanıcısından yeni abonelik planı için her yıl 36 tl alınır.

Uygulamamıza bu özelliği nasıl entegre edebileceğimize bakalım. Burdaki süreç default satın alma akışının başlatılmasıyla aynı gibi görünüyor. Ancak upgrade/downgrade sırasında bizden ayrıca mevcut abonelik, geçilecek olan abonelik ve proration mode gibi bilgileri sağlamamız isteniyor.

// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync()
val flowParams = BillingFlowParams.newBuilder()
        .setOldSku(previousSku, purchaseTokenOfOriginalSubscription)
        .setReplaceSkusProrationMode(desiredProrationMode)
        .setSkuDetails(upgradeOrDowngradeSkuDetails)
        .build();
val responseCode = billingClient.launchBillingFlow(activity, flowParams)

• Immediate proration modelar için, PurchasesUpdatedListener içerisinde yeni purchase’i anında yakalayabildiğimiz gibi, BillingClient.queryPurchases metodu ile de alabiliyor olacağız. Ayrıca her yeni subscription purchase işlemini başarıyla tamamladıktan sonra yaptığımız gibi acknowledge işlemi yapmamız gerekiyor. Bunu Google Play Billing Library kullanarak BillingClient.acknowledgePurchase() metodu ile ya da Google Play Developer API kullanarak Purchases.subscriptions:acknowledge ile gerçekleştirebiliriz.

Bir kullanıcı upgrade/downgrade ya da subscription değişikliği yaptığında eski subscriptionı invalidate olur ve yeni purchase token ile yepyeni bir purchase create edilir. Google Play Developer API’dan dönen subscription resource bize ilgili upgrade/downgrade işleminin ilişkili olduğu eski purchase bilgisini içeren linkedPurchaseToken değerini verir. Bu alanı baz alarak, eski subscription bilgisi üzerinden varolan user accountına ulaşarak yeni yapılan purchase bilgisinin aynı kullanıcıyla eşleştirilmesi sağlanabilir. Ayrıca acknowledge işlemini de bu aşamada yapmamız gerekiyor.

Subscription resource içeriği aşağıdaki gibidir:

{
  "kind": "androidpublisher#subscriptionPurchase",
  ...
  "expiryTimeMillis": next_renewal_date,
  "autoRenewing": true,
  "linkedPurchaseToken": old_purchase_token
  ...
  "paymentState": 1  # Payment received
}

• Deferred proration mode içinse, uygulamanız içerisinde PurchasesUpdatedListener tetiklenerek boş bir purchase listesi ve upgrade/downgrade işleminin başarılı olup olmadığına dair bir status değeri yakalanır. Değişiklik geçerli oluncaya kadar queryPurchases metodunda mevcutta varolan subscription bilgisi döner. Ancak upgrade/downgrade edilmiş yeni plan geçerli olmaya başlandığı andan itibaren backendinize SUBSCRIPTION_RENEWED notificationı gönderilir (bakınız real time developer notifications) ve yeni subsription bilgisi queryPurchases metoduyla dönmeye başlar. Bu notificationı dinlemek ve ardından purchase’i Purchases.subscriptions:acknowledge kullanarak acknowledge etmek öneriliyor. (Not: Acknowledge işlemini 3 gün içinde yapmamanız durumunda kullanıcıya geri ödeme yapılıyor. Kullanıcınızın uygulamayı açması ve BillingClient.acknowledgePurchase() yoluyla acknowledge yapma yoluna gitmemeniz gerektiği, çünkü kullanıcınızın, plan değişikliğinin geçerli hale gelmesinden sonraki üç gün içinde uygulamayı açmayabilme ihtimalinin olduğu dökümantasyonda belirtiliyor.)

Trial /Introductory Price teklifleri İçeren Aboneliklerde Upgrade İşlemi

Kullanıcınız upgrade/downgrade işlemi seçimi yaptığı zaman Google Play Console üzerinden mevcuttaki abonelik için daha önce oluşturmuş olduğunuz free trial seçeneği geçerliliğini korur.

• Eğer kullanıcınızın mevcut olan tüm subscriptionlar içerisinde yalnızca bir kez free trial kullanabilme hakkı olacaksa, upgrade/downgrade değişikliği sonrasında free trial ya da introductory price kullanım hakkı olmayacaktır.
• Ancak her bir subscription başına free trial sağlıyorsanız, kullanıcınızın plan değişikliğine trial ya da introductory price dahil olabilir.

Hem eski hem yeni planda free trial kullanımı sağlanması ve tüm subscriptionlar içerisinde tek bir free trial kullanımı sağlanması durumlarında farklı proration modelar için sürecin nasıl ilerleyeceğine bakalım.

1. IMMEDIATE_WITH_TIME_PRORATION:

• App içerisinde tek bir free trial sağlanıyorsa: Kullanıcı ücretsiz denemeyi hemen kaybeder. Kalan ücretsiz deneme süresi, fiyat farkına göre yeni planın eşdeğer bir ücretsiz süresine dönüştürülür.
• Her bir abonelik için birer free trial sağlanıyorsa: Kullanıcı önceki ücretsiz denemeyi kaybeder ancak yeni ücretsiz denemeyi hemen başlatır. Ek olarak, eski planın kalan ücretsiz deneme süresi, yeni planın eşdeğer bir ücretsiz süresine dönüştürülür ve yeni ücretsiz denemeye eklenir.

2. IMMEDIATE_AND_CHARGE_PRORATED_PRICE: Kullanıcıya app çapında tek bir free trial ya da her bir abonelik için ayrı birer free trial sağlanması durumu değiştirmez.
Kullanıcı ücretsiz denemeyi hemen kaybeder. Kalan süre için fiyat farkı daha sonra kullanıcıya fatura edilir. Bir sonraki fatura tarihi değişmeden kalır. Not: Bu seçenek yalnızca zaman birimi başına fiyatın arttığı bir abonelik yükseltmesi için kullanılabilir.

3. IMMEDIATE_WITHOUT_PRORATION: Kullanıcıya app çapında tek bir free trial ya da her bir abonelik için ayrı birer free trial sağlanması durumu değiştirmez. Kullanıcı hemen yeni plana yükseltilir. Önceki fatura dönemi sona erene kadar yeni plana ücretsiz deneme erişimini korur.

4. DEFERRED: Kullanıcıya app çapında tek bir free trial ya da her bir abonelik için ayrı birer free trial sağlanması durumu değiştirmez. Kullanıcı, bir sonraki fatura tarihine kadar eski aboneliğe ücretsiz deneme erişimini korur.

Yine bir usecase örneğiyle süreci daha net anlamaya çalışalım.

Öncelikle kullanıcımıza subscriptionlar içerisinde yalnızca bir kez free trial kullanım hakkı verdiğimizi varsayalım.

Diyelim ki yine bir A kullanıcısı bir app üzerinden abonelik hizmeti satın almış olsun. Bu hizmet yalnızca text içeriklerine erişimi sağlayan Tier 1 aboneliği olsun. Bu hizmet kullanıcımıza ayda 10 tl’ye malolsun ve kullanıcımız 1 Nisan’da abone olmuş olsun. Yeni abone kullanıcı olarak 30 günlük free trial teklifini kullansın ve dolayısıyla ilk ödemesi 1 Mayıs’ta gerçekleşecek olsun.

A kullanıcısının 15 Nisan’da abonelik hizmetini aylık olan Tier 1'den yıllık olan ve text içeriğine ek olarak video içeriklerine de erişmeye izin veren yine aylık olan 20 tl tutarındaki Tier 2'ye upgrade etmeyi seçtiğini düşünelim. Bu tiera geçişinde de yine free trial hakkına sahip olduğunu varsayalım.

Her bir proration mode için free trial geçişinin nasıl olacağına bir bakalım.

1. IMMEDIATE_WITH_TIME_PRORATION:
   A kullanıcısı hemen Tier 2'ye yükseltilir. Kullanıcı, abonelik döneminin yarısında yükselttiğinden, yeni aboneliğine ayın aboneliğinin yarısı (15 günlük 10 tl değerinde) uygulanır. Ancak, bu yeni aboneliğin maliyeti ayda 20 tl olduğundan, 15 günlük bakiye yalnızca 7,5 günü öder. Kullanıcımız, Tier 2 için başka bir ücretsiz deneme kullanmaya sahip değil, bu nedenle 22 Nisan’dan itibaren her ay 20 tl olarak ücretlendirilir.
2. IMMEDIATE_AND_CHARGE_PRORATED_PRICE:
   Belli bir zaman dilimi başına (bu case için yine aylık düşünebiliriz) Tier 2 abonelik fiyatı (20 tl aylık), Tier 1 abonelik fiyatından (10 tl aylık) yüksek olduğu için bu mod kullanılabilir. A kullanıcısının aboneliği hemen Tier 2'ye yükseltilir ve ücretsiz denemesini(free trial) kaybeder. A kullanıcısının bir sonraki fatura tarihi 1 Mayıs olduğundan, Nisan ayının 1. yarısını karşılamak için kendisinden 10 tl olan tutar tahsil edilir ve ardından 1 Mayıs’tan itibaren her ay 20 tl ödemesi gerekir.
3. IMMEDIATE_WITHOUT_PRORATION:
   A kullanıcısının Tier 1 aboneliği, anında Tier 2'ye yükseltilir. Kullanıcı, 30 Nisan’a kadar ücretsiz deneme süresi hakkını korur ve artık Tier 2 içeriğine erişebilir olur. 1 Mayıs’tan itibaren her ay yeni abonelik için 20 tl olarak ücretlendirilir.
4. DEFERRED:
   A kullanıcısının Tier 1 aboneliği 1 Mayıs’a kadar devam eder. 1 Mayıs’ta, Tier 2 aboneliği yürürlüğe girer ve kullanıcıdan her ayın ilk günü 20 tl ücret alınır.

Bu defa kullanıcımıza her bir subscription özelinde birer free trial kullanım hakkı verdiğimizi varsayalım.

1. IMMEDIATE_WITH_TIME_PRORATION:
   A kullanıcısı hemen Tier 2'ye yükseltilir. Kullanıcı, abonelik döneminin yarısında yükselttiğinden, yeni aboneliğine ayın aboneliğinin yarısı (15 günlük 10 tl değerinde) uygulanır. Ancak, bu yeni aboneliğin maliyeti ayda 20 tl olduğundan, 15 günlük bakiye yalnızca 7,5 günü öder. Kullanıcımız, Tier 2 için başka bir ücretsiz deneme hakkına sahip, bu nedenle 37,5 gün daha ücretlendirilmez. 22 Mayıs’tan itibaren her ay 20 tl olarak ücretlendirilir.
2. IMMEDIATE_AND_CHARGE_PRORATED_PRICE:
   Belli bir zaman dilimi başına (bu case için yine aylık düşünebiliriz) Tier 2 abonelik fiyatı (20 tl aylık), Tier 1 abonelik fiyatından (10 tl aylık) yüksek olduğu için bu mod kullanılabilir. A kullanıcısının aboneliği hemen Tier 2'ye yükseltilir ve ücretsiz denemesini(free trial) kaybeder. A kullanıcısının bir sonraki fatura tarihi 1 Mayıs olduğundan, Nisan ayının 2. yarısını karşılamak için kendisinden 10 tl olan tutar tahsil edilir ve ardından 1 Mayıs’tan itibaren her ay 20 tl ödemesi gerekir.
3. IMMEDIATE_WITHOUT_PRORATION:
   A kullanıcısının Tier 1 aboneliği, anında Tier 2'ye yükseltilir. Kullanıcı, 30 Nisan’a kadar ücretsiz deneme süresi hakkını korur ve artık Tier 2 içeriğine erişebilir olur. 1 Mayıs’tan itibaren her ay yeni abonelik için 20 tl olarak ücretlendirilir.
4. DEFERRED:
   A kullanıcısının Tier 1 aboneliği 1 Mayıs’a kadar devam eder. 1 Mayıs’ta, Tier 2 aboneliği yürürlüğe girer ve kullanıcıdan her ayın ilk günü 20 tl ücret alınır.

Proration Mode için Google’ın önerdikleri

Referanslar

https://developer.android.com/google/play/billing/subscriptions#change

https://developer.android.com/google/play/billing/subscriptions#upgrade-free-trial

https://developer.android.com/google/play/billing/subscriptions#upgrade-downgrade