Ö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 Ödeme İsteği API'sini ve Dijital Ürünler API'sini 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 reklam kaldırma gibi hem dayanıklı hem de tüketim amaçlı 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

Bubblewrap yüklü değilse 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 kullanıyorsanız 1.8.2 veya sonraki bir sürüme güncellediğinizden emin olun.

Bubblewrap'te de 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.

Digital Goods API ve Google Play Faturalandırma kullanılabilirliğini algılayan özellik

Digital Goods API şu anda yalnızca PWA'nın Güvenilir Web Etkinliği içinde yürütüldüğü durumlarda Chrome tarafından desteklenmektedir. window nesnesinde getDigitalGoodsService olup olmadığını kontrol ederek API'nin kullanılabilir olup olmadığını tespit edebilirsiniz:

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()'ü ç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'nun ayrıntılarını alma

Digital Goods API, ürün başlığı, açıklama ve en önemlisi fiyat gibi bilgilerin ödeme arka ucundan 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 değerini tanımlayıcı olarak ayarlayarak ve ü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ı zorunlu olsa da Play Faturalandırma bu değerleri yoksayıp Play Console'da SKU oluşturulurken ayarlanan değerleri kullanır. Bu nedenle, bu alanlar 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. Sözleşme başarılı olursa ödeme başarılı olmuş demektir. Bu işlem başarısız olursa kullanıcı ödemeyi iptal etmiş olabilir.

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 daha önce yaptığı satın alma işlemlerinden (başka bir cihazda, önceki bir yüklemeden, promosyon koduyla etkinleştirilen veya uygulamayı en son açtığında etkinleştirilen henüz kullanılmamış uygulama içi satın alma işlemleri ya da devam eden abonelikler) yararlanma hakkı olup olmadığını kontrol etmenize olanak tanır.


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 kabul edilmeyen satın alma işlemlerini kontrol etmek için de iyi bir zamandı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 Digital Goods 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 işareti isme göre arayarak Chrome'da aşağıdaki 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.