Nhận Khoản thanh toán qua Google Play Billing bằng API Hàng hoá kỹ thuật số và API Yêu cầu thanh toán

André Cipriani Bandarra

Nếu ứng dụng của bạn được phân phối thông qua Google Play và bạn muốn bán hàng hoá kỹ thuật số hoặc cung cấp gói thuê bao, thì bạn phải sử dụng Google Play Billing. Google Play Billing cung cấp các công cụ để quản lý danh mục, giá và gói thuê bao, báo cáo hữu ích cũng như quy trình thanh toán do Cửa hàng Play cung cấp mà người dùng đã quen thuộc.

Đối với các ứng dụng được tạo bằng Hoạt động web đáng tin cậy và phân phối thông qua Cửa hàng Google Play, giờ đây, bạn có thể sử dụng API Yêu cầu thanh toán và API Hàng hoá kỹ thuật số để tích hợp với Google Play Billing. Tính năng này có trên Chrome 101 trở lên dành cho Android và ChromeOS.

Trong hướng dẫn này, bạn sẽ tìm hiểu cách thêm tính năng hỗ trợ Google Play Billing vào PWA và đóng gói ứng dụng để phân phối trên Cửa hàng Google Play cho cả ChromeOS và Cửa hàng Play.

Bạn sẽ sử dụng hai API nền tảng web để thêm tính năng hỗ trợ Play Billing vào PWA. Digital Merchandise API dùng để thu thập thông tin về SKU và kiểm tra các giao dịch mua cũng như quyền truy cập trên Cửa hàng Play. Payment Request API (API yêu cầu thanh toán) được dùng để định cấu hình Cửa hàng Google Play làm phương thức thanh toán và hoàn tất quy trình mua hàng.

Cách kiếm tiền từ ứng dụng trên Cửa hàng Play

Ứng dụng của bạn có thể kiếm tiền bằng Google Play Billing trên Cửa hàng Play theo hai cách:

  • Giao dịch mua hàng trong ứng dụng cho phép bán cả hàng hoá ảo lâu bền và tiêu dùng, chẳng hạn như các tính năng bổ sung hoặc loại bỏ quảng cáo.
  • Gói thuê bao, cho phép người dùng liên tục sử dụng nội dung hoặc dịch vụ với một khoản phí định kỳ, chẳng hạn như gói thuê bao tin tức hoặc gói thành viên.

Yêu cầu

Để thiết lập Google Play Billing, bạn cần có:

Cập nhật dự án Bubblewrap

Nếu chưa cài đặt Bubblewrap, bạn cần cài đặt ứng dụng này. Vui lòng xem Hướng dẫn bắt đầu nhanh để biết thông tin chi tiết về cách bắt đầu. Nếu bạn đã cài đặt Bubblewrap, hãy nhớ cập nhật lên phiên bản 1.8.2 trở lên.

Bubblewrap cũng có tính năng đằng sau một lá cờ. Để bật tính năng này, bạn cần sửa đổi cấu hình dự án trong twa-manifest.json, nằm ở thư mục gốc của dự án và bật cả alphaDependencies và tính năng playBilling:

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

Sau khi cập nhật tệp cấu hình, hãy chạy bubblewrap update để áp dụng cấu hình cho dự án, theo sau là bubblewrap build để tạo gói Android mới và tải gói này lên Cửa hàng Play.

Tính năng phát hiện API Hàng hoá kỹ thuật số và phạm vi cung cấp của Google Play Billing

API Hàng hoá kỹ thuật số hiện chỉ được Chrome hỗ trợ khi PWA đang được thực thi bên trong một Hoạt động web đáng tin cậy. Bạn có thể phát hiện xem API này có sẵn hay không bằng cách kiểm tra getDigitalGoodsService trên đối tượng window:

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

Digital Goods API có thể có trong mọi trình duyệt và hỗ trợ nhiều cửa hàng. Để kiểm tra xem một phần phụ trợ cụ thể của cửa hàng có được hỗ trợ hay không, bạn cần gọi getDigitalGoodsService(), truyền mã cửa hàng dưới dạng tham số. Cửa hàng Google Play được xác định bằng chuỗi 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;
  }
}

Truy xuất thông tin chi tiết về một SKU

API Hàng hoá kỹ thuật số cung cấp getDetails(), cho phép truy xuất thông tin như tiêu đề sản phẩm, nội dung mô tả và quan trọng nhất là giá từ phần phụ trợ thanh toán.

Sau đó, bạn có thể sử dụng thông tin này trong giao diện người dùng và cung cấp thêm thông tin chi tiết cho người dùng:

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

Xây dựng quy trình mua

Hàm khởi tạo cho PaymentRequest nhận hai tham số: danh sách phương thức thanh toán và danh sách thông tin thanh toán.

Khi ở trong Hoạt động đáng tin cậy trên web, bạn phải sử dụng phương thức thanh toán qua hệ thống thanh toán của Google Play, bằng cách đặt https://play.google.com/billing làm giá trị nhận dạng và thêm SKU sản phẩm vào làm thành phần dữ liệu:

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

   ...
}

Mặc dù thông tin thanh toán là bắt buộc, nhưng Play Billing sẽ bỏ qua các giá trị đó và sử dụng giá trị được đặt khi tạo SKU trong Play Console, vì vậy, bạn có thể điền các giá trị giả vào:

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

Gọi show() trên đối tượng yêu cầu thanh toán để bắt đầu quy trình thanh toán. Nếu Lời hứa thành công thì có thể là khoản thanh toán đã được thực hiện. Nếu không thành công, có thể người dùng đã huỷ giao dịch thanh toán.

Nếu lời hứa thành công, bạn sẽ cần xác minh và xác nhận giao dịch mua. Để chống gian lận, bạn phải triển khai bước này bằng phần phụ trợ. Hãy xem tài liệu Play Billing để tìm hiểu cách triển khai tính năng xác minh trong phần phụ trợ. Nếu bạn không xác nhận giao dịch mua, sau ba ngày, người dùng sẽ được hoàn tiền và Google Play sẽ thu hồi giao dịch mua đó.

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

Bạn có thể gọi consume() trên purchaseToken để đánh dấu giao dịch mua là đã sử dụng và cho phép mua lại.

Kết hợp mọi thứ lại với nhau, phương thức mua hàng sẽ có dạng như sau:

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

Kiểm tra trạng thái của các giao dịch mua hiện có

API Hàng hoá kỹ thuật số cho phép bạn kiểm tra xem người dùng có quyền nào hiện tại (giao dịch mua trong ứng dụng chưa được sử dụng hoặc gói thuê bao đang hoạt động) từ các giao dịch mua trước đó mà họ đã thực hiện hay không, cho dù là trên một thiết bị khác, từ một lượt cài đặt trước đó, được sử dụng từ một mã khuyến mãi hay chỉ là lần gần đây nhất họ mở ứng dụng.


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

Đây cũng là thời điểm thích hợp để kiểm tra các giao dịch mua đã thực hiện trước đó nhưng chưa được xác nhận. Bạn nên xác nhận giao dịch mua hàng càng sớm càng tốt để đảm bảo quyền của người dùng được phản ánh chính xác trong ứng dụng.

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

Kiểm tra quá trình tích hợp

Trên thiết bị Android phát triển

Bạn có thể bật API Hàng hoá kỹ thuật số trên một thiết bị Android đang phát triển để kiểm thử:

  • Đảm bảo bạn đang sử dụng Android 9 trở lên và đã bật chế độ nhà phát triển.
  • Cài đặt Chrome phiên bản 101 trở lên.
  • Bật các cờ sau trong Chrome bằng cách chuyển đến chrome://flags và tìm cờ theo tên:
    • #enable-debug-for-store-billing
  • Đảm bảo rằng trang web được lưu trữ bằng giao thức https. Việc sử dụng http sẽ khiến API trở thành undefined

Trên thiết bị ChromeOS

API Hàng hoá kỹ thuật số sẽ có trên ChromeOS phiên bản chính thức bắt đầu từ phiên bản 89. Trong thời gian chờ đợi, bạn có thể kiểm thử API Hàng hoá kỹ thuật số:

  • Cài đặt ứng dụng của bạn qua Cửa hàng Play trên thiết bị.
  • Đảm bảo rằng trang web được lưu trữ bằng giao thức https. Việc sử dụng http sẽ khiến API trở thành undefined

Với người dùng thử nghiệm và nhóm đảm bảo chất lượng

Cửa hàng Play cung cấp các tính năng hỗ trợ kiểm thử, bao gồm cả tài khoản kiểm thử người dùng và SKU kiểm thử. Hãy xem tài liệu kiểm thử Google Play Billing để biết thêm thông tin.

Bước tiếp theo là gì?

Như đã thảo luận trong tài liệu này, API Play Billing có các thành phần phía máy khách (do Digital Merchandise API quản lý) và các thành phần phía máy chủ.