PWA'nızda Play Faturalandırma'yı uygulama

PWA'nız Google Play'de listeleniyorsa ve uygulama içi ürünler veya abonelikler satarak para kazanmak istiyorsanız Play politikası, Play Faturalandırma'yı uygulamanızı zorunlu kılar. PWA'nızda uygulamanız gereken iki API vardır: Digital Goods API ve Payment Request API.

Digital Goods API

Digital Goods API, uygulamanız ile Google Play arasındaki arayüzdür. Bu API, Play Console'da uygulama içi ürünleriniz ve abonelikleriniz için girdiğiniz dijital ürünleri ve ayrıntıları almanıza, ayrıca kullanıcının yaptığı mevcut satın alma işlemlerini almanıza olanak tanır. Play Console'a henüz uygulama içi ürün veya abonelik eklemediyseniz Play faturalandırma için Play Console kurulumu bölümündeki adımları uyguladığınızdan emin olun.

30 Kasım 2021'de ChromeOS 96, Digital Goods API 2.0 uygulamasıyla birlikte yayınlandı.

Digital Goods API'nin ilk sürümünün kaynak denemesi 30 Ocak 2022'de sona erdi. Bu nedenle, artık kullanımdan kaldırıldı ve yalnızca API'nin v2 sürümü kullanılabilir.

23 Haziran 2022'de ChromeOS 103, Digital Goods API 2.1 uygulamasıyla birlikte yayınlandı. Bu sürümde, yalnızca yeni yöntemler ve ek alanlar (listPurchaseHistory() ve itemType) yer alır ve herhangi bir uyumsuzluk yaratan değişiklik yoktur.

Kaynak denemesine kaydolma

Not: Digital Goods API şu anda Origin Trial (geliştiricilerin yeni Web API'lerine erken erişmesini sağlayan bir mekanizma) aracılığıyla kullanılabilir. Digital Goods API v2 deneme sürümüne kaydolmanız ve kaynağınızdaki tüm sayfalarda sağlamanız gereken bir jeton istemeniz gerekir.

Deneme sürecine kaydolduktan sonra, jetonunuzun çalışacağı garanti edilen son tarih olan "Geçerlilik Bitiş Tarihi" gösterilir. Denemeye katılmaya devam etmek için bu tarih yaklaştığında jetonlarınızı yenilemeyi unutmayın. Kaynak denemesi olarak sunulan API'ler değişebilir. Bu nedenle, katıldığınız kaynak denemelerindeki en son değişikliklerden haberdar olmanız gerekir. Sorun yaşarsanız Digital Goods API dokümanlarına bakın.

Payment Request API

Satın alma işlemi yapıldığında gerçek ödeme işlemi Payment Request API tarafından gerçekleştirilir. Uygun ödeme yöntemi (bizim durumumuzda Google Play Faturalandırma) kullanılarak uygulama içi satın alma işleminin yapılması için Dijital Ürünler API'sinin sağladığı öğe ayrıntılarını kullanır.

Digital Goods API'yi özellik algılama

getDigitalGoodsService yönteminin window nesnesinde olup olmadığını kontrol ederek API'yi web sitenizde doğru şekilde etkinleştirip etkinleştirmediğinizi kaynak denemesi aracılığıyla tespit edebilirsiniz.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
} else {
  console.log('DigitalGoodsService is not available.');
  // Use another payment method
}

Google Play Faturalandırma Hizmeti'ne bağlanma

Digital Goods API, Payment Request API'nin tarayıcıdan bağımsız olması ve farklı ödeme sağlayıcılarla kullanılabilmesi gibi çeşitli tarayıcılar ve dijital mağazalarla uyumlu olacak şekilde tasarlanmıştır. Google Play Faturalandırma ile ilişkili hizmetin bir örneğini almak için "https://play.google.com/billing" dizesini getDigitalGoodsService()'ye ödeme yöntemi olarak iletin.

Yöntem hata verirse Google Play Faturalandırma ödeme yöntemi kullanılamaz (ör. kullanıcı, PWA'nıza tarayıcı üzerinden erişiyordur). Bunun yerine, işlemler için başka bir ödeme yöntemi sunmanız gerekir.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service = await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing service is available
  } catch (error) {
    // Google Play Billing service is not available. Use another payment flow.
  }
}

Öğe ayrıntılarını alma

Dijital Ürünler hizmetini Google Play'e bağladıktan sonra ürünler ve satın alma işlemleri hakkında bilgi almak için API'yi kullanabilirsiniz.

getDetails() yöntemi, Play Console'da ayarladığınız öğeler hakkında bilgi almanızı sağlar. Ürün başlığı, açıklama ve fiyat gibi bilgiler, uygulamanızın kullanıcı arayüzünde kullanıcıya gösterilmelidir. Böylece kullanıcılar, satın alabilecekleri ürünleri ve fiyatlarını bilir.

getDetails() yöntemi, Play Console'da oluşturduğunuz uygulama içi ürünlerin ve aboneliklerin ürün kimliklerine karşılık gelen öğe kimliklerinin bir listesini gerektirir.

const itemDetails = await service.getDetails(['product_1', 'product_2', 'product_3']);
for (const item of itemDetails) {
  // Display item information to user
  displayItem(item.title, item.description, item.price);
}

Kullanıcının yerel ayarı için uygun fiyatı almak üzere bazı ek biçimlendirme işlemleri yapmanız gerekir:

const localePrice = new Intl.NumberFormat(navigator.language, {
  style: 'currency',
  currency: item.price.currency,
}).format(item.price.value);

Not: Digital Goods API, öğe kimliklerinin listesini alabileceğiniz bir yöntem sunmaz. Bunun yerine, bunları istemcinize sabit kodlamanız veya arka uç sunucunuzdan getirmeniz gerekir. Google Play Developer API, arka uçtan öğe kimlikleri listesini sorgulamanıza olanak tanır. (Önemli Play Faturalandırma bileşenlerini arka uç sunucunuza uygulama hakkında daha fazla bilgi edinin. Hangi çözümü seçerseniz seçin, öğe kimliklerinin Play Console'daki öğe kimlikleriyle tutarlı olduğundan emin olun.

API'nin 2.1 sürümünde, getDetails() tarafından döndürülen alanlardan biri itemType'dir. Bu, ilgili öğenin uygulama içi ürün mü yoksa abonelik mi olduğunu belirtmek için değerin ”product” veya ”subscription” olduğu bir enum'dur. İki ürün türü arasında ayrım yapabilmek, her ürün türüne farklı işlemler uygulamanız gerektiğinde faydalı olabilir. Örneğin, kullanıcıların abone olabileceği belirli bir sayfanız ve diğer abonelik dışı ürünler için başka bir sayfanız olabilir. Ayrıca, arka uçta kullanılacak uygun Google Play Developer API REST kaynağını (purchases.products veya purchases.subscriptions) öğrenmek için de yararlıdır.

Öğe satın alma

Ürünleriniz ve ayrıntılarınız kullanıcıya gösterildikten sonra, Payment Request API ile satın alma akışını oluşturabilirsiniz. Digital Goods API ile birlikte kullanıldığında yalnızca bir giriş parametresi gerekir: methodData.

Play Faturalandırma yalnızca tek bir öğenin satın alınmasına izin verir. Öğenin fiyatı ve ayrıntıları Play sunucusu tarafından zaten bilindiğinden details parametresi gerekli değildir. Daha ayrıntılı bilgi için açıklayıcı metne bakın.

Google Play Faturalandırma'yı ödeme yöntemi olarak tanımlamak için PaymentRequest içindeki supportedMethods üyesi methodData parametresini "https://play.google.com/billing" dizesiyle birlikte kullanın. Ardından, data üyesinde öğe kimliğini sku olarak iletin.

const paymentMethodData = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
    },
  },
];

Ardından ödeme isteğini oluşturun ve ödeme akışını başlatmak için show() işlevini çağırın:

const request = new PaymentRequest(paymentMethodData);
const paymentResponse = await request.show();

Bu işlem, kullanıcının satın almaya çalıştığı ürünle ilgili ayrıntıları göreceği Play satın alma kullanıcı arayüzünü gösterir. İşlemi iptal edebilir veya ödemeye devam edebilirler. Kullanıcı ödemeyi iptal ederse show() tarafından döndürülen söz hata ile reddedilir. Müşteri ödemeyi başarıyla yapıp satın alma işlemini tamamladığında söz PaymentResponse ile sonuçlanır. Ödeme yanıtının details özelliğinde bir satın alma jetonu döndürülür.

Sahtekarlığı önlemek için satın alma işlemini ve satın alma jetonunu arka uç sunucunuzda doğrulamanız çok önemlidir. Kullanıcıları ve ilişkili satın alma jetonlarını takip etmeniz de önerilir. Doğrulamayı arka uç sunucunuzda nasıl uygulayacağınızı öğrenin.

Satın alma işlemi doğrulandıktan sonra, ödeme akışını tamamlamak ve faturalandırma kullanıcı arayüzünü kapatmak için ödeme yanıtında complete() işlevini çağırın. Ödeme sürecinin durumunu belirtmek için isteğe bağlı bir result dizesi de iletebilirsiniz. Tarayıcı, bu sonuçla ilgili kullanıcıya herhangi bir gösterge sağlayıp sağlamayacağına kendisi karar verir. Chrome, kullanıcı tarafından görülebilen herhangi bir ipucu oluşturmaz. Bu nedenle, PWA'nızda kendi hata veya başarı mesajlarınızı göstermeniz önerilir.

/* Changes were recently made so that the PaymentResponse `details` property returns the purchase token as `purchaseToken` instead of `token`. Note that `token` will be deprecated at some point in the future. To ensure that your app won't be affected by this, make the change to `purchaseToken` in your client code and use the latest version of Bubblewrap (v1.13.5 and later) to update and generate a new app package to upload to the Play Console. */
const { purchaseToken } = paymentResponse.details;

let paymentComplete;
if (validatePurchaseOnBackend(purchaseToken)) {
  paymentComplete = await paymentResponse.complete('success');
  // Let user know their purchase transaction has successfully completed and been verified
} else {
  paymentComplete = await paymentResponse.complete('fail');
  // Let user know their purchase transaction failed to verify
}

Abonelik yükseltme ve düşürme

Bu satın alma akışı hem uygulama içi ürünler hem de abonelik satın alma işlemleri için aynıdır. Ancak abonelikler için Google Play'de uygulayabileceğiniz ek satın alma seçenekleri (yükseltme ve düşürme) bulunur. Ödeme yöntemi için data oluştururken yükseltme veya düşürme akışını başlatmak için aşağıdakileri iletmeniz gerekir:

• sku: Bu, yükseltilecek veya düşürülecek yeni aboneliğin öğe kimliğidir.
• oldSku: Bu, kullanıcının mevcut aboneliğinin öğe kimliğidir.
• purchaseToken: Bu, kullanıcının mevcut aboneliğinin satın alma jetonudur. Daha önce de belirtildiği gibi, satın alma jetonlarını arka uçta takip etmeniz önerilir. Bu ve diğer senaryolarda, kullanıcıları mevcut satın alma işlemleri ve satın alma jetonlarıyla da ilişkilendirmeniz gerekir.
• prorationMode: Yeni abonelik, kullanıcının mevcut aboneliğinin yerini aldığında bu şekilde ücretlendirilir.

Orantılı Ödeme Modu	Açıklama
immediateAndChargeProratedPrice	Abonelik hemen yükseltilir ve faturalandırma dönemi aynı kalır. Kalan dönem için fiyat farkı daha sonra kullanıcıdan alınır.
immediateAndChargeFullPrice	Abonelik yükseltilir veya aboneliğin sürümü düşürülür ve kullanıcıdan yeni hak için hemen tam fiyat alınır. Önceki abonelikten kalan değer, yeni abonelik için kalan süreye göre orantılı olarak hesaplanır. Bu orantılı ödeme modu, Google Play Faturalandırma Kitaplığı 4.0 sürümüne kısa süre önce eklendi. Bu özellik, Bubblewrap'in 1.13.5 sürümünden itibaren kullanılabilir.
immediateWithoutProration	GEÇİCİ OLARAK DEVRE DIŞI BIRAKILDI Bu orantılı ödeme modunda, kullanıcıların bir fatura dönemi boyunca ek ödeme yapmadan yükseltilmiş abonelik alabileceği olası bir sahtekarlık yolu vardır. Düzeltme üzerinde çalışırken bu modu geçici olarak devre dışı bıraktığımızı lütfen unutmayın.
immediateWithTimeProration	Abonelik hemen yükseltilir veya düşürülür. Kalan süre, fiyat farkına göre ayarlanır ve bir sonraki fatura tarihi ileri alınarak yeni aboneliğe eklenir. Bu varsayılan davranıştır.
deferred	Abonelik yalnızca yenilendiğinde üst veya alt sürüme geçirilir. Bu özellik, özellikle sürüm düşürme işlemleri için yararlıdır.
unknownSubscriptionUpgradeDowngradePolicy	Politika ayarlanmadı. Bu işlem önerilmez.

Google Play Faturalandırma Kitaplığı referans belgelerinden farklı oranlama modları hakkında daha fazla bilgi edinin. Abonelik yükseltme ve düşürme ile orantılı ödeme modu önerileri hakkında daha fazla bilgi için Android geliştirici belgelerine göz atın.

Bu ek alanların kullanımı aşağıdaki gibi görünür:

const paymentMethod = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
      oldSku: oldPurchase.itemId,
      purchaseToken: oldPurchase.purchaseToken,
      prorationMode: 'immediateAndChargeProratedPrice',
    },
  },
];

Burada item, kullanıcının yükseltmeye veya düşürmeye çalıştığı yeni aboneliğin ItemDetails, oldPurchase ise kullanıcının mevcut aboneliğinin PurchaseDetails değeridir.

Satın alma işlemini onaylama

Kullanıcı bir öğe satın aldıktan sonra, ona uygun hakları (satın aldığı öğeye veya içeriğe erişim) vermeniz gerekir. Ardından satın alma işlemini onaylayın. Satın alma işlemini onayladığınızda Google Play, satın alma işlemini aldığınızı ve uygun şekilde işlediğinizi anlar.

Not: Satın alma işlemi, satın alma zamanından itibaren 72 saat içinde onaylanmazsa ödeme kullanıcıya iade edilir ve satın alma işlemi iptal edilir. Satın alma jetonu artık geçerli olmayacağından mevcut satın alma işlemlerini sorguladığınızda iptal edilen satın alma işlemi döndürülmez. Bu sayede, ağ hatası nedeniyle öğelerine erişim izni verilmeyen kullanıcılardan yanlışlıkla ücret alınmaz.

Google Play Developer API'yi kullanarak arka uç sunucunuzdaki satın alma işlemlerini onaylamanız gerekir. Yetki verme ve satın alma işlemini onaylama işlemlerini arka uç sunucunuzda birlikte yapmanızı öneririz.

1. Kullanıcı istemci tarafında satın alma işlemi yaptıktan sonra satın alma jetonunu ve öğe kimliğini arka uç sunucunuza bir istekte gönderin.
2. Satın alma işlemini doğrulamak için arka uçta aşağıdaki işlevi çağırarak satın alma işlemiyle ilgili ayrıntıları alın:
   • Uygulama içi öğeler için purchases.products.get.
   • Abonelikler için purchases.subscriptions.get.
3. Arka uç veritabanınızda uygun yetkiyi verin.
4. Ardından, aşağıdaki numarayı arayarak satın alma işlemini onaylayın:
   • Uygulama içi öğeler için purchases.products.acknowledge.
   • Abonelikler için purchases.subscriptions.acknowledge.

Satın alma işlemini kullanma

Satın alma işlemini onayladığınızda Google Play, kullanıcının artık öğenin sahibi olduğunu ve öğeyi tekrar satın almasına izin verilmemesi gerektiğini anlar. Kullanıcının yalnızca bir kez satın alması ve sonsuza kadar sahip olması gereken bir öğe (ör. oyun karakteri görünümü) tüketilebilir öğe değildir.

Alternatif olarak, öğe, kullanıcının aynı anda yalnızca bir tane kullanabileceği bir şey olabilir. Ardından, kullanıcının başka bir öğe satın alabilmesi için bu öğeyi kullanması gerekir. Kullanıcı öğeyi "kullandığında", Google Play'e kullanıcının öğeyi tükettiğini bildirmek için consume() yöntemini çağırmanız gerekir. Google Play, öğeyi kullanıcının tekrar satın alabilmesi için kullanılabilir hale getirir.

Kullanıcının birden fazla kez sahip olmasına izin verdiğiniz öğeler, önce kullanılmaları gerekmeden tekrar tekrar satın alınabilmelidir (bunlara tekrarlanabilir öğeler diyoruz). Benzer şekilde, Google Play'in kullanıcının bu öğeleri tekrar satın almasına izin vermesi için öğelerin "tüketilmesi" gerekir. Bu nedenle, kullanıcı öğeyi henüz kullanmamış olsa bile öğeyi kullanılmış olarak işaretlemek için consume() yöntemini çağırmanız gerekir.

// After the user purchases the item, send the purchase token and item ID to your backend to grant the entitlement and acknowledge it right away

. . .
// When the user uses the item or if it is a repeatable item, consume it so it’s available for purchase again.
service.consume(purchaseToken);
}

Mevcut satın alma işlemlerini kontrol etme

Son önemli kullanıcı akışı, kullanıcılarınıza mevcut abonelikleri veya sahip oldukları öğeleri bildirmek için mevcut satın alma işlemlerini (henüz kullanılmamış uygulama içi ürünler ve devam eden abonelikler) kontrol etmektir. Bu mevcut satın alma işlemleri, uygulama içinde veya Play Store'da herhangi bir cihazda yapılan önceki Google Play satın alma işlemlerinden oluşur. Play Store'da uygulama dışında yapılan satın alma işlemlerine uygulama dışı satın alma işlemleri denir.

Mevcut satın alma işlemlerini alırken onay durumunu da kontrol etmeli ve daha önce yapılmış ancak uygun şekilde onaylanmamış satın alma işlemlerini onaylamalısınız. Kullanıcının haklarının güncel olması ve uygulamaya doğru şekilde yansıtılması için satın alma işlemlerinin mümkün olan en kısa sürede onaylanması önerilir.

Digital Goods API listPurchases() yöntemi, satın alımların her biri için itemId ve purchaseToken değerlerini içeren PurchaseDetails listesini döndürür. Satın alma işlemlerinin durumunu kontrol etmek ve bunları uygun şekilde onaylamak için arka uç sunucunuzda Google Play Developer API'yi kullanmanız gerekir. Şunları yapmanız gerekir:

1. Kullanıcının satın alma listesini almak için Digital Goods API listPurchases() yöntemini istemci tarafında çağırın.
2. Her satın alma işlemi için purchaseToken ve itemId değerlerini arka uçunuza iletin.
3. Uygunsa arka uç veritabanınızda hak verin.
4. Ardından arayın ve acknowledgementState işaretini kontrol edin.
   • Uygulama içi öğeler için purchases.products.get.
   • Abonelikler için purchases.subscriptions.get.
5. Değer 0 ise (henüz onaylanmamış) aşağıdaki işlevi çağırın:
   • Uygulama içi öğeler için purchases.products.acknowledge.
   • Abonelikler için purchases.subscriptions.acknowledge.

Hak verme işleminden önce arka uç sunucunuzdaki satın alma işlemlerini doğrulama hakkında daha fazla bilgi edinin.

İşlem geçmişi

listPurchases, kullanıcının mevcut satın alımlarıyla ilgili bilgileri döndürürken listPurchaseHistory() yöntemi (API'nin 2.1 sürümünde) satın alımın süresinin dolup dolmadığına, iptal edilip edilmediğine veya kullanılıp kullanılmadığına bakılmaksızın, kullanıcının her öğe için yaptığı en son satın alımı döndürür. listPurchaseHistory() yöntemi, her satın alma işlemi için itemId ve purchaseToken değerlerini içeren bir PurchaseDetails listesi döndürür. Daha fazla bilgi almak için bu listeyi arka uç sunucunuzdaki Google Play Developer API ile birlikte kullanmanız gerekir.

Uygulama dışı satın alma işlemleri

Uygulama dışı satın alma işlemleri, normal uygulama içi satın alma akışında yapılmayan satın alma işlemleridir. Bu işlemler genellikle uygulamanızda değil, Play Store'da gerçekleşir. Kullanıcıların uygulama dışı satın alma işlemi yapmasının iki temel yolu vardır:

• Promosyon kodu kullanma: Play Store kullanıcı menüsünde "Fırsatlar ve bildirimler" -> "Promosyon kodunu kullan" veya "Ödemeler ve abonelikler" -> "Hediye kodunu kullan" seçeneğinde.
• Yeniden abone olma: Play Store kullanıcı menüsünde "Ödemeler ve abonelikler" -> "Abonelikler" bölümünde. Kullanıcılar, farklı uygulamalardaki tüm aboneliklerini buradan yönetebilir. Süresi dolmuş veya iptal edilmiş aboneliklerde kullanıcılar "Yeniden abone ol" seçeneğini görür.

Kullanıcılar Play Store'dan yeniden abone olduklarında satın alma işlemleri otomatik olarak onaylanmaz. Bu durum, kullanıcılara geri ödeme yapılmasına neden olabilir. Bu davranış, kullanıcılar uygulamayı kullanmak için açtıklarında abonelik ücreti alınması gerektiğinden kasıtlı olarak uygulanır. Kullanıcı, uygulamayı açmasını hatırlatan "Aboneliği onayla" gibi bir mesaj görebilir.

Kullanıcı uygulamayı başlattıktan sonra bu satın alma işlemlerinin onaylanmasını sağlamak geliştirici olarak sizin sorumluluğunuzdadır. Bu nedenle, mevcut satın alma işlemlerini kontrol etmenizi (genellikle uygulama ilk kez başlatıldığında) ve henüz onaylanmamış satın alma işlemlerini onaylamanızı öneririz.

Kullanıcıların abonelikleri yönetmesine izin verme

İyi bir kullanıcı deneyimi için kullanıcılara aboneliklerini uygulama içinde yönetme ve iptal etme olanağı sunmanız önemlidir. Bir ayarlar sayfasında veya menüsünde, kullanıcıyı uygulamanızın Play Store'daki abonelik yönetimi sayfasına yönlendirecek bir derin bağlantı oluşturmanızı öneririz. Aşağıdaki URL'yi uygun "alt ürün kimliği" ve "uygulama paketi adı" ile değiştirin:

https://play.google.com/store/account/subscriptions?sku=sub-product-id&package=app-package-name

Sonraki adımlar

Bu kullanıcı akışları ve kod snippet'leri, Play Faturalandırma'yı uygulamak için PWA'nızda Digital Goods API ve Payment Request API'nin nasıl kullanılacağını gösteren temel bir uygulamadır. API'leri, uygulamanızın bağlamına ve kullanım alanlarına uygun şekilde kullanmanız gerekir. Uçtan uca uygulama örneği için açık kaynaklı örneğimize göz atın.

Ardından, uygulamanızın güvenliğini sağlamak ve kullanıcılarınızın haklarıyla ilgili her zaman güncel kalmak için Play Faturalandırma'nın önemli bileşenlerini arka uç sunucunuza nasıl uygulayacağınızı inceleyin.