รับการชำระเงินผ่านการเรียกเก็บเงินของ Google Play ด้วย Digital Goods API และ Payment Request API

อันเดร ซิปรีอานี่ บันดาร์ร่า

หากมีการจัดจำหน่ายแอปผ่าน Google Play และคุณต้องการขายสินค้าดิจิทัลหรือมอบข้อเสนอ คุณต้องใช้ Google Play Billing การเรียกเก็บเงินของ Google Play มีเครื่องมือสำหรับจัดการแคตตาล็อก ราคา และการสมัครใช้บริการ รายงานที่มีประโยชน์ รวมถึงขั้นตอนการชำระเงินที่ขับเคลื่อนโดย Play Store ซึ่งเป็นที่ที่ผู้ใช้คุ้นเคยอยู่แล้ว

สำหรับแอปที่สร้างขึ้นโดยใช้กิจกรรมบนเว็บที่เชื่อถือได้และนำส่งผ่าน Google Play Store ตอนนี้คุณสามารถใช้ Payment Request API และ Digital Goods API เพื่อผสานรวมกับ Google Play Billing ได้แล้ว ใช้ได้ใน Chrome 101 ขึ้นไปสำหรับ Android และ ChromeOS

ในคู่มือนี้ คุณจะได้ทราบวิธีเพิ่มการรองรับการเรียกเก็บเงินของ Google Play ลงใน PWA และจัดแพ็กเกจเพื่อการจัดจำหน่ายใน Google Play Store สำหรับทั้ง ChromeOS และ Play Store

คุณจะใช้ API ของแพลตฟอร์มเว็บ 2 รายการเพื่อเพิ่มการรองรับการเรียกเก็บเงินของ Play ไปยัง PWA Digital Goods API ใช้เพื่อรวบรวมข้อมูล SKU และตรวจสอบการซื้อและการให้สิทธิ์จาก Play Store Payment Request API ใช้เพื่อกำหนดค่า Google Play Store เป็นวิธีการชำระเงินและเพื่อดำเนินการขั้นตอนการซื้อให้เสร็จสมบูรณ์

วิธีสร้างรายได้จากแอปพลิเคชันบน Play Store

แอปพลิเคชันจะสร้างรายได้ด้วย Google Play Billing ใน Play Store ได้ 2 วิธีดังนี้

  • การซื้อในแอปช่วยให้ขายสินค้าเสมือนได้ทั้งแบบระยะยาวและระยะสั้น เช่น ฟีเจอร์เพิ่มเติม หรือการนำโฆษณาออก
  • การสมัครใช้บริการ ให้ผู้ใช้เข้าถึงเนื้อหาหรือบริการอย่างต่อเนื่องโดยมีค่าธรรมเนียมตามรอบ เช่น การสมัครรับข้อมูลข่าวหรือการเป็นสมาชิก

ข้อกำหนด

ในการตั้งค่าการเรียกเก็บเงินของ Google Play คุณจะต้องมีสิ่งต่อไปนี้

อัปเดตโปรเจ็กต์ Bubblewrap

หากคุณไม่ได้ติดตั้ง Bubblewrap คุณจะต้องติดตั้ง ดูรายละเอียดเกี่ยวกับวิธีเริ่มต้นใช้งานได้จากคู่มือเริ่มใช้งานฉบับย่อ หากคุณมี Bubblewrap อยู่แล้ว ให้อัปเดต เป็นเวอร์ชัน 1.8.2 ขึ้นไป

นอกจากนี้ Bubblewrap ยังมีฟีเจอร์เบื้องหลังธงอีกด้วย หากต้องการเปิดใช้ คุณจะต้องแก้ไขการกำหนดค่าโปรเจ็กต์ใน twa-manifest.json ซึ่งอยู่ที่รูทของโปรเจ็กต์และเปิดใช้ทั้ง alphaDependencies และฟีเจอร์ของ playBilling ดังนี้

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

เมื่ออัปเดตไฟล์การกำหนดค่าแล้ว ให้เรียกใช้ bubblewrap update เพื่อใช้การกำหนดค่ากับโปรเจ็กต์ ตามด้วย bubblewrap build เพื่อสร้างแพ็กเกจ Android ใหม่และอัปโหลดแพ็กเกจนี้ไปยัง Play Store

ฟีเจอร์ที่ตรวจหา Digital Goods API และความพร้อมใช้งานของ Google Play Billing

ปัจจุบัน Chrome Goods API จะรองรับ API สินค้าดิจิทัลเฉพาะเมื่อเรียกใช้ PWA ภายในกิจกรรมบนเว็บและเว็บที่เชื่อถือได้ และสามารถตรวจสอบได้ว่ามี API ดังกล่าวหรือไม่โดยการตรวจหา getDigitalGoodsService ในออบเจ็กต์ window ดังนี้

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

Digital Goods API อาจมีให้บริการในทุกเบราว์เซอร์และรองรับร้านค้าที่แตกต่างกัน หากต้องการตรวจสอบว่าระบบรองรับแบ็กเอนด์ของร้านค้าหนึ่งๆ หรือไม่ คุณจะต้องเรียกใช้ getDigitalGoodsService() ส่งรหัส Store เป็นพารามิเตอร์ Google Play Store จะระบุ ด้วยสตริง https://play.google.com/billing:

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

Digital Goods API ให้บริการ getDetails() ซึ่งให้คุณดึงข้อมูล เช่น ชื่อผลิตภัณฑ์ คำอธิบาย และที่สำคัญที่สุดคือราคาจากแบ็กเอนด์การชำระเงิน

คุณสามารถใช้ข้อมูลนี้ในอินเทอร์เฟซการใช้งาน และให้รายละเอียดเพิ่มเติมแก่ผู้ใช้ได้ ดังนี้

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);
}

สร้างขั้นตอนการซื้อ

เครื่องมือสร้างสำหรับ PaymentRequest จะมีพารามิเตอร์ 2 ตัว ได้แก่ รายการวิธีการชำระเงินและรายการรายละเอียดการชำระเงิน

เมื่ออยู่ในกิจกรรมบนเว็บและเว็บที่เชื่อถือได้ คุณต้องใช้วิธีการชำระเงินแบบเรียกเก็บเงินของ Google Play โดยตั้งค่า https://play.google.com/billing เป็นตัวระบุ และเพิ่ม SKU ของผลิตภัณฑ์เป็นสมาชิกข้อมูล โดยมีขั้นตอนดังนี้

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

   ...
}

แม้ว่าจะต้องระบุรายละเอียดการชำระเงิน แต่การเรียกเก็บเงินของ Play จะไม่สนใจค่าเหล่านั้นและใช้ค่าที่ตั้งไว้เมื่อสร้าง SKU ใน Play Console เพื่อให้สามารถเติมค่าปลอมได้

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

เรียก show() ในออบเจ็กต์คำขอการชำระเงินเพื่อเริ่มขั้นตอนการชำระเงิน หาก Promise ประสบความสำเร็จ นั่นอาจเป็นการชำระเงินที่สำเร็จ หากไม่สำเร็จ ผู้ใช้อาจล้มเลิกการชำระเงิน

หากสัญญาสำเร็จ คุณจะต้องยืนยันและรับทราบการซื้อ คุณต้องทำขั้นตอนนี้โดยใช้แบ็กเอนด์เพื่อป้องกันการประพฤติมิชอบ อ่าน เอกสารเกี่ยวกับการเรียกเก็บเงินของ Play เพื่อดูวิธีใช้การยืนยันในระบบแบ็กเอนด์ หากคุณไม่รับทราบการซื้อ หลังจากผ่านไป 3 วัน ผู้ใช้จะได้รับเงินคืนและ Google Play จะเพิกถอนการซื้อนั้น

...
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
}
...

(ไม่บังคับ) อาจมีการเรียก consume() ใน purchaseToken เพื่อทําเครื่องหมายการซื้อว่าใช้ไปแล้วและอนุญาตให้ซื้ออีกครั้ง

เมื่อรวมข้อมูลทุกอย่างเข้าด้วยกัน วิธีการซื้อจะมีลักษณะดังนี้

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
    }
}

ตรวจสอบสถานะของการซื้อที่มีอยู่

Digital Goods API ให้คุณตรวจสอบได้ว่าผู้ใช้มีการให้สิทธิ์อยู่บ้างหรือไม่ (การซื้อในแอปที่ยังไม่ได้ใช้หรือการสมัครใช้บริการต่อเนื่อง) จากการซื้อที่ดำเนินการไปแล้วก่อนหน้านี้ ไม่ว่าจะใช้อุปกรณ์อื่น จากการติดตั้งก่อนหน้า แลกจากรหัสโปรโมชัน หรือเพิ่งเปิดแอปครั้งล่าสุด


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}`);
}

นอกจากนี้ นี่ยังเป็นโอกาสที่ดีในการตรวจสอบการซื้อที่ดำเนินการไปแล้วก่อนหน้านี้แต่ยังไม่ตอบรับ ขอแนะนำให้รับทราบการซื้อโดยเร็วที่สุดเพื่อให้มั่นใจว่าการให้สิทธิ์ของผู้ใช้แสดงอย่างถูกต้องในแอป

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}`);
}

ทดสอบการผสานรวม

ในอุปกรณ์ Android ที่กำลังพัฒนา

คุณเปิดใช้ Digital Goods API ในอุปกรณ์ Android เวอร์ชันพัฒนาเพื่อทำการทดสอบได้โดยทำดังนี้

  • ตรวจสอบว่าคุณใช้ Android 9 ขึ้นไปและเปิดใช้โหมดนักพัฒนาซอฟต์แวร์แล้ว
  • ติดตั้ง Chrome 101 ขึ้นไป
  • เปิดใช้การตั้งค่าสถานะต่อไปนี้ใน Chrome โดยไปที่ chrome://flags และค้นหาแฟล็กตามชื่อ:
    • #enable-debug-for-store-billing
  • ตรวจสอบว่าเว็บไซต์โฮสต์โดยใช้โปรโตคอล HTTPS การใช้ http จะทำให้ API มีสถานะ undefined

ในอุปกรณ์ ChromeOS

Digital Goods API จะมีให้บริการใน ChromeOS เวอร์ชันเสถียรตั้งแต่เวอร์ชัน 89 เป็นต้นไป ในระหว่างนี้ คุณอาจทดสอบ Digital Goods API ได้โดยทำดังนี้

  • ติดตั้งแอปจาก Play Store ในอุปกรณ์
  • ตรวจสอบว่าเว็บไซต์โฮสต์โดยใช้โปรโตคอล HTTPS การใช้ http จะทำให้ API มีสถานะ undefined

กับผู้ใช้ทดสอบและทีม QA

Play Store ให้บริการทดสอบต่างๆ ซึ่งรวมถึงบัญชีทดสอบของผู้ใช้และ SKU ทดสอบ ดูข้อมูลเพิ่มเติมได้ที่เอกสารประกอบการทดสอบของ Google Play Billing

ไปที่ไหนต่อ

Play Billing API มีองค์ประกอบฝั่งไคลเอ็นต์ซึ่งจัดการโดย Digital Goods API และคอมโพเนนต์ฝั่งเซิร์ฟเวอร์ดังที่กล่าวไว้ในเอกสารนี้