Ödemeleri Digital Goods API ve Payment Request API ile Google Play Faturalandırma üzerinden alma

André Cipriani Bandarra

Uygulamanız Google Play üzerinden dağıtılıyorsa ve dijital ürünler satmak ya da abonelik sunmak istiyorsanız Google Play Faturalandırma'yı kullanmanız gerekir. Google Play Faturalandırma, kataloğunuzu, fiyatlarınızı ve aboneliklerinizi yönetmenize yardımcı olacak araçlar, faydalı raporlar ve kullanıcılarınızın aşina olduğu, Play Store tarafından desteklenen bir ödeme akışı sunar.

Güvenilir Web Etkinlikleri kullanılarak oluşturulan ve Google Play Store üzerinden yayınlanan uygulamalarda artık Google Play Faturalandırma ile entegrasyon için Payment Request API ve Digital Goods API'yi kullanabilirsiniz. Android ve ChromeOS için Chrome 101 ve sonraki sürümlerde kullanılabilir.

Bu kılavuzda, PWA'nıza Google Play Faturalandırma desteğini nasıl ekleyeceğinizi ve hem ChromeOS hem de Play Store için Google Play Store'da dağıtılmak üzere nasıl paketleyeceğinizi öğreneceksiniz.

PWA'nıza Play Faturalandırma desteği eklemek için iki web platformu API'si kullanacaksınız. Digital Goods API, SKU bilgilerini toplamak ve Play Store'daki satın alma işlemlerini ve haklarınızı kontrol etmek için kullanılır. Payment Request API, Google Play Store'u ödeme yöntemi olarak yapılandırmak ve satın alma akışını tamamlamak için kullanılır.

Play Store'daki uygulamalardan para kazanma

Uygulamanızın Play Store'da Google Play Faturalandırma ile para kazanmasının iki yolu vardır:

  • Uygulama içi satın alma işlemleri, ek özellikler veya reklamları kaldırma gibi hem dayanıklı hem de tüketilebilir sanal ürünlerin satışına olanak tanır.
  • Abonelikler, kullanıcılarınıza belirli aralıklarla ödeme yapmaları karşılığında içerik veya hizmetlere sürekli erişim imkanı sunar (ör. haber abonelikleri veya üyelikler).

Şartlar

Google Play Faturalandırma'yı ayarlamak için şunlar gerekir:

Bubblewrap projesini güncelleme

Bubblepack'i yüklemediyseniz yüklemeniz gerekir. Nasıl başlayacağınızla ilgili ayrıntılar için Hızlı Başlangıç Kılavuzu'na bakın. Bubblewrap zaten yüklüyse 1.8.2 veya sonraki bir sürüme güncellediğinizden emin olun.

Bubblewrap'ta da bu özellik bir bayrakla gösterilir. Bu özelliği etkinleştirmek için projenin kökünde bulunan twa-manifest.json dosyasında proje yapılandırmasını değiştirmeniz ve hem alphaDependencies hem de playBilling özelliğini etkinleştirmeniz gerekir:

  ...,
  "enableNotifications": true,
  "features": {
    "playBilling": {
      "enabled": true
    }
  },
  "alphaDependencies": {
    "enabled": true
  },
  ...

Yapılandırma dosyası güncellendikten sonra, yapılandırmayı projeye uygulamak için bubblewrap update'ü, ardından yeni bir Android paketi oluşturmak ve bu paketi Play Store'a yüklemek için bubblewrap build'ü çalıştırın.

Dijital Ürünler API'sinin ve Google Play Faturalandırma'nın kullanılabilirliğini algılama özelliği

Digital Goods API, şu anda yalnızca PWA, Güvenilir Web Etkinliği içinde yürütülüyorken Chrome tarafından desteklenmektedir. window nesnesinde getDigitalGoodsService olup olmadığını kontrol ederek kullanılabilir olup olmadığını tespit etmek mümkündür:

if ('getDigitalGoodsService' in window) {
 // Digital Goods API is supported!
}

Digital Goods API, herhangi bir tarayıcıda kullanılabilir ve farklı mağazaları destekleyebilir. Belirli bir mağaza arka ucunun desteklenip desteklenmediğini kontrol etmek için mağaza kimliğini parametre olarak göndererek getDigitalGoodsService()'yi çağırmanız gerekir. Google Play Store, https://play.google.com/billing dizesi ile tanımlanır:

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service =
        await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing is supported!

  } catch (error) {
    // Google Play Billing is not available. Use another payment flow.
    return;
  }
}

SKU ayrıntılarını alma

Digital Goods API, ödeme arka ucundan ürün başlığı, açıklama ve en önemlisi fiyat gibi bilgilerin alınmasına olanak tanıyan getDetails() sağlar.

Ardından bu bilgileri kullanıcı arayüzünüzde kullanabilir ve kullanıcıya daha fazla ayrıntı sağlayabilirsiniz:

const skuDetails = await service.getDetails(['shiny_sword', 'gem']);
for (item of skuDetails) {
  // Format the price according to the user locale.
  const localizedPrice = new Intl.NumberFormat(
      navigator.language,
      {style: 'currency', currency: item.price.currency}
    ).format(item.price.value);

  // Render the price to the UI.
  renderProductDetails(
        item.itemId, item.title, localizedPrice, item.description);
}

Satın alma akışını oluşturma

PaymentRequest sınıfının kurucusu iki parametre alır: ödeme yöntemlerinin listesi ve ödeme ayrıntılarının listesi.

Güvenilir Web Etkinliği'ndeyken https://play.google.com/billing adresini tanımlayıcı olarak ayarlayıp ürün SKU'sunu veri üyesi olarak ekleyerek Google Play faturalandırma ödeme yöntemini kullanmanız gerekir:

async function makePurchase(service, sku) {
   // Define the preferred payment method and item ID
   const paymentMethods = [{
       supportedMethods: "https://play.google.com/billing",
       data: {
           sku: sku,
       }
   }];

   ...
}

Ödeme ayrıntıları gerekli olsa da Play Faturalandırma bu değerleri yoksayar ve Play Console'da SKU'yu oluştururken ayarlanan değerleri kullanarak sahte değerlerle doldurulabilir:

const paymentDetails = {
    total: {
        label: `Total`,
        amount: {currency: `USD`, value: `0`}
    }
};

const request = new PaymentRequest(paymentMethods, paymentDetails);

Ödeme akışını başlatmak için ödeme isteği nesnesinde show() işlevini çağırın. Promise başarılı olursa ödeme başarılı olmuş olabilir. Ödeme başarılı olmadıysa, kullanıcı muhtemelen ödemeyi iptal etmiştir.

Taahhüt başarılı olursa satın alma işlemini doğrulamanız ve onaylamanız gerekir. Sahtekarlığa karşı koruma sağlamak için bu adımın arka uçunuz kullanılarak uygulanması gerekir. Doğrulamayı arka uçunuza nasıl uygulayacağınızı öğrenmek için Play Faturalandırma belgelerine göz atın. Satın alma işlemini onaylamazsanız üç gün sonra kullanıcıya geri ödeme yapılır ve Google Play satın alma işlemini iptal eder.

...
const request = new PaymentRequest(paymentMethods, paymentDetails);
try {
    const paymentResponse = await request.show();
    const {purchaseToken} = paymentResponse.details;

    // Call backend to validate and acknowledge the purchase.
    if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
        // Optional: tell the PaymentRequest API the validation was
        // successful. The user-agent may show a "payment successful"
        // message to the user.
        const paymentComplete = await paymentResponse.complete('success');
    } else {
        // Optional: tell the PaymentRequest API the validation failed. The
        // user agent may show a message to the user.
        const paymentComplete = await paymentResponse.complete('fail');
    }
} catch(e) {
    // The purchase failed, and we can handle the failure here. AbortError
    // usually means a user cancellation
}
...

İsteğe bağlı olarak, satın alma işlemini kullanılmış olarak işaretlemek ve tekrar satın alınmasına izin vermek için purchaseToken üzerinde consume() çağrılabilir.

Tüm bunları bir araya getirdiğimizde satın alma yöntemi aşağıdaki gibi görünür:

async function makePurchase(service, sku) {
    // Define the preferred payment method and item ID
    const paymentMethods = [{
        supportedMethods: "https://play.google.com/billing",
        data: {
            sku: sku,
        }
    }];

    // The "total" member of the paymentDetails is required by the Payment
    // Request API, but is not used when using Google Play Billing. We can
    // set it up with bogus details.
    const paymentDetails = {
        total: {
            label: `Total`,
            amount: {currency: `USD`, value: `0`}
        }
    };

    const request = new PaymentRequest(paymentMethods, paymentDetails);
    try {
        const paymentResponse = await request.show();
        const {purchaseToken} = paymentResponse.details;

        // Call backend to validate and acknowledge the purchase.
        if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
            // Optional: consume the purchase, allowing the user to purchase
            // the same item again.
            service.consume(purchaseToken);

            // Optional: tell the PaymentRequest API the validation was
            // successful. The user-agent may show a "payment successful"
            // message to the user.
            const paymentComplete =
                    await paymentResponse.complete('success');
        } else {
            // Optional: tell the PaymentRequest API the validation failed.
            // The user agent may show a message to the user.
            const paymentComplete = await paymentResponse.complete('fail');
        }
    } catch(e) {
        // The purchase failed, and we can handle the failure here.
        // AbortError usually means a user cancellation
    }
}

Mevcut satın alma işlemlerinin durumunu kontrol etme

Digital Goods API, kullanıcının başka bir cihazda, önceki bir yüklemede yaptığı, bir promosyon kodundan kullandığı veya yalnızca uygulamayı son açtığı tarih fark etmeksizin önceden yaptığı satın alma işlemlerinden herhangi bir yararlanma hakkına (henüz kullanılmamış uygulama içi satın alma işlemleri veya devam eden abonelikler) sahip olup olmadığını kontrol etmenizi sağlar.


const service =
     await window.getDigitalGoodsService('https://play.google.com/billing');
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

Bu, daha önce yapılan ancak onaylanmayan satın alma işlemlerini kontrol etmek için de iyi bir fırsattır. Kullanıcılarınızın haklarının uygulamanıza doğru şekilde yansıtılmasını sağlamak için satın alma işlemlerini mümkün olan en kısa sürede onaylamanız önerilir.

const service =
     await window.getDigitalGoodsService("https://play.google.com/billing");
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    await verifyOrAcknowledgePurchaseOnBackend(p.purchaseToken, p.itemId);

    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

Entegrasyonunuzu test etme

Geliştirme amaçlı Android cihazda

Test için geliştirme amaçlı bir Android cihazda Dijital Ürünler API'yi etkinleştirmek mümkündür:

  • Geliştirici modunun etkinleştirildiği Android 9 veya sonraki bir sürüm kullandığınızdan emin olun.
  • Chrome 101 veya sonraki bir sürümü yükleyin.
  • chrome://flags adresine gidip bayrağı ada göre arayarak Chrome'da şu işaretleri etkinleştirin:
    • #enable-debug-for-store-billing
  • Sitenin https protokolü kullanılarak barındırıldığından emin olun. http kullanılması, API'nin undefined olmasına neden olur.

ChromeOS cihazda

Digital Goods API, ChromeOS'te 89 sürümünden itibaren kararlı sürümde kullanılabilir. Bu sırada Digital Goods API'yi test edebilirsiniz:

  • Uygulamanızı Play Store'dan cihaza yükleyin.
  • Sitenin https protokolü kullanılarak barındırıldığından emin olun. http kullanılması, API'nin undefined olmasına neden olur.

Test kullanıcıları ve kalite kontrol ekipleriyle

Play Store, kullanıcı test hesapları ve test SKU'ları da dahil olmak üzere test için olanaklar sunar. Daha fazla bilgi için Google Play Faturalandırma test belgelerine göz atın.

Sıradaki durak neresi?

Bu belgede de belirtildiği gibi Play Billing API'nin, Digital Goods API tarafından yönetilen istemci tarafı bileşenleri ve sunucu tarafı bileşenleri vardır.