使用 Digital Goods API 和 Payment Request API 通过 Google Play 结算服务接收付款

André Cipriani Bandarra

如果您的应用通过 Google Play 分发，并且您想销售数字商品或提供订阅服务，则必须使用 Google Play 结算服务。Google Play 结算服务提供了一些工具，用于管理目录、价格和订阅、实用的报告以及由用户熟悉的 Play 商店提供支持的结账流程。

对于使用可信 Web 活动构建并通过 Google Play 商店分发的应用，您现在可以使用 Payment Request API 和 Digital Goods API 与 Google Play 结算系统集成。该功能适用于 Android 版和 ChromeOS 版 Chrome 101 及更高版本。

在本指南中，您将了解如何为 PWA 添加 Google Play 结算服务支持，以及如何将其打包，以便在 Google Play 商店上分发，同时适用于 ChromeOS 和 Play 商店。

您将使用两个 Web 平台 API 为 PWA 添加 Play 结算支持。Digital Goods API 用于收集 SKU 信息，并检查 Play 商店中的购买交易和使用权。Payment Request API 用于将 Google Play 商店配置为付款方式并完成购买流程。

如何在 Play 商店中通过应用创收

您的应用可以通过以下两种方式在 Play 商店中使用 Google Play 结算服务创收：

  • 应用内购可用于销售耐用型和消耗型虚拟商品，例如额外功能或广告移除服务。
  • 订阅：让用户可定期付费，持续使用内容或服务，例如新闻订阅或会员服务。

要求

若要设置 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 商店。

检测 Digital Goods API 和 Google Play 结算服务可用性的功能

目前，只有在可信 Web 活动内执行 PWA 时，Chrome 才支持 Digital Goods API。您可以通过检查 window 对象上的 getDigitalGoodsService 来检测该 API 是否可用：

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

Digital Goods API 可能适用于任何浏览器，并支持不同的商店。如需检查是否支持特定的商店后端，您需要调用 getDigitalGoodsService()，并将商店 ID 作为参数传递。Google Play 商店由字符串 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 的构造函数接受两个参数：付款方式列表和付款详情列表。

在可信 Web activity 中，您必须使用 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 结算系统会忽略这些值，并使用在 Play 管理中心内创建 SKU 时设置的值，因此可以填充虚假值：

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

对付款请求对象调用 show() 以启动付款流程。如果 Promise 成功，则表示付款成功。如果失败，则表示用户可能已中止付款。

如果承诺成功，您需要验证并确认购买交易。为了防范欺诈，您必须使用后端实现此步骤。请参阅 Play 结算文档，了解如何在后端实现验证。 如果您不确认购买交易，三日后，用户会收到退款，并且 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
}
...

（可选）可以对 purchaseToken 调用 consume()，以将购买交易标记为已用尽，并允许用户再次购买。

将所有内容整合起来，购买方法应如下所示：

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 设备上

您可以在开发 Android 设备上启用 Digital Goods API 以进行测试：

  • 确保您使用的是 Android 9 或更高版本，且已启用开发者模式。
  • 安装 Chrome 101 或更高版本。
  • 在 Chrome 中，前往 chrome://flags 并按名称搜索 flag，以启用以下 flag：
    • #enable-debug-for-store-billing
  • 确保网站是使用 https 协议托管的。使用 http 会导致 API undefined

在 ChromeOS 设备上

从 ChromeOS 89 开始，Digital Goods API 将在稳定版 ChromeOS 上提供。与此同时，您可以测试 Digital Goods API：

  • 在设备上从 Play 商店安装您的应用。
  • 确保网站是使用 https 协议托管的。使用 http 会导致 API undefined

与测试用户和质量检查团队合作

Play 商店提供了用于测试的功能，包括用户测试账号和测试 SKU。 如需了解详情，请参阅 Google Play 结算服务测试文档。

接下来该怎么做？

如本文档所述，Play 结算服务 API 包含客户端组件（由 Digital Goods API 管理）和服务器端组件。