能力中的 API
Digital Goods API
发布于 更新于
Digital Goods API 用来读取商店后端的商品目录和用户购买记录。先调用 window.getDigitalGoodsService(provider) 获取 DigitalGoodsService,再用它的 getDetails()、listPurchases()、listPurchaseHistory() 和 consume() 与提供方通信。实际购买由 Payment Request API 完成,付款方式填写同一个提供方 URL。
Chrome for Developers 指南称该 API 在 Android 与 ChromeOS 的 Chrome 101 及以上版本可用,并且目前只有 Chrome 在 PWA 运行于 Trusted Web Activity 中、以 https://play.google.com/billing 为提供方时支持它。指南还介绍了在开发设备上用于测试的 Chrome 标志。规范是 WICG 草案,其中写明不支持 Digital Goods 的用户代理不应在 Window 上暴露 getDigitalGoodsService(),所以可以用 in 检查做特性检测;在提供方不受支持的环境里,调用仍可能被拒绝。
window.getDigitalGoodsService(serviceProvider)
digitalGoodsService.getDetails(itemIds)digitalGoodsService.listPurchases()digitalGoodsService.listPurchaseHistory()digitalGoodsService.consume(purchaseToken)getDigitalGoodsService() 返回 Promise<DigitalGoodsService>。getDetails() 返回 Promise<sequence<ItemDetails>>,listPurchases() 与 listPurchaseHistory() 返回 Promise<sequence<PurchaseDetails>>,consume() 返回 Promise<undefined>。这些接口都要求 [SecureContext],且仅在 Window 上可用;没有方法需要用户手势,但文档必须与顶层页面同源,且 Permissions Policy 必须允许使用 payment 特性(同站 iframe 需要 allow="payment")。
三个方法接受参数;两个列表方法不接受。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
serviceProvider |
DOMString |
是 | 基于 URL 的支付方式标识符;Google Play 为 "https://play.google.com/billing"。undefined、null 或 "" 会拒绝。 |
itemIds |
sequence<DOMString> |
是 | 在商店控制台配置的商品或订阅 ID。不能为空;结果可能省略未知 ID,顺序也不保证。 |
purchaseToken |
DOMString |
是 | listPurchases() 或购买时 PaymentResponse.details 返回的令牌。不能为空。 |
getDetails() 兑现的 ItemDetails 字典包含以下成员:
| 成员 | 类型 | 必填 | 说明 |
|---|---|---|---|
itemId |
DOMString |
是 | 被请求的 ID。 |
title |
DOMString |
是 | 用于展示的本地化名称。 |
price |
PaymentCurrencyAmount |
是 | 用户所在地区的 { currency, value };用 Intl.NumberFormat 格式化。 |
type |
"product" 或 "subscription" |
否 | 商品种类。 |
description |
DOMString |
否 | 本地化的详细描述。 |
iconURLs |
sequence<DOMString> |
否 | 商品图片。 |
subscriptionPeriod |
DOMString |
否 | ISO 8601 时长,仅订阅。 |
freeTrialPeriod |
DOMString |
否 | 免费试用的 ISO 8601 时长。 |
introductoryPrice |
PaymentCurrencyAmount |
否 | 优惠期内的价格。 |
introductoryPricePeriod |
DOMString |
否 | 优惠期的 ISO 8601 时长。 |
introductoryPriceCycles |
unsigned long long |
否 | 优惠价适用的计费周期数。 |
listPurchases() 与 listPurchaseHistory() 兑现的 PurchaseDetails 字典有两个必填成员 itemId 与 purchaseToken;listPurchaseHistory() 可能包含已消耗或已过期的购买,没有历史记录的商店返回与 listPurchases() 相同的列表。
这些方法报错时会拒绝 Promise,不会同步抛出异常。Chromium 的 OperationError 消息就是 Play Billing 的响应码字面量,这是区分「商品已拥有」与「商店应用缺失」的唯一途径。
| 异常 | 条件 |
|---|---|
InvalidStateError |
在非 fully active 的文档中调用 getDigitalGoodsService()。 |
NotAllowedError |
调用 getDigitalGoodsService() 的文档与顶层源不同源,或 payment Permissions Policy 不允许。 |
TypeError |
getDigitalGoodsService() 的提供方为 undefined、null 或空串;getDetails([]);consume("")。 |
OperationError |
getDigitalGoodsService() 的提供方在当前环境不受支持(不在 TWA 内,或打包时未启用 Play Billing);四个服务方法在商店报错时。Chromium 的消息字符串:unsupported payment method、unsupported context、error、itemAlreadyOwned、itemNotOwned、itemUnavailable、clientAppUnavailable、clientAppError。 |
针对同一提供方的 PaymentRequest.show() 在用户退出 Play 购买面板时以 AbortError 拒绝;那是 Payment Request API 的异常,不属于本 API。
用同一个辅助函数获取服务;不在支持 Play 的 Trusted Web Activity 中时,让它兑现为 null。应用据此改用 Stripe、PayPal 或普通表单显示网页收银台。
获取 Play 服务,不可用时回退到网页收银台
链接到“获取 Play 服务,不可用时回退到网页收银台”一节in 检查只说明浏览器实现了该 API;只有 Promise 兑现才说明这个安装包能连上 Play Billing。两种失败按同一方式处理。
const PLAY_BILLING = 'https://play.google.com/billing';
async function getPlayService() { if (!('getDigitalGoodsService' in window)) return null; try { return await window.getDigitalGoodsService(PLAY_BILLING); } catch (err) { console.info(`Play Billing 不可用(${err.name}: ${err.message})`); return null; }}
const service = await getPlayService();document.querySelector('#web-checkout').hidden = Boolean(service);document.querySelector('#play-checkout').hidden = !service;记录 err.message 能把 Play 响应码(unsupported context、clientAppUnavailable)留在遥测里,而不改变用户看到的内容。
用 getDetails() 按用户区域渲染价格
链接到“用 getDetails() 按用户区域渲染价格”一节price 是 PaymentCurrencyAmount。用 Intl.NumberFormat 格式化价格,无需手动拼接 value 和 currency。结果不包含缺失的 ID,因此应遍历返回的商品,而非请求中的 ID 列表。
async function renderCatalogue(service, ids) { if (!service) return renderWebPrices(ids); // 从你自己的服务器获取 const items = await service.getDetails(ids); const money = new Intl.NumberFormat(navigator.language, { style: 'currency', currency: items[0]?.price.currency ?? 'USD' }); for (const item of items) { const row = document.createElement('li'); row.textContent = `${item.title}: ${money.format(item.price.value)}`; if (item.type === 'subscription' && item.freeTrialPeriod) { row.textContent += `(试用 ${item.freeTrialPeriod})`; } document.querySelector('#catalogue').append(row); }}P7D 之类的试用期是 ISO 8601 时长字符串,需要自行格式化;Chrome 101 的 Intl 没有可用于它的时长格式化器。
用 PaymentRequest 购买,再用 listPurchases() 恢复权益
链接到“用 PaymentRequest 购买,再用 listPurchases() 恢复权益”一节购买流程是 Payment Request:supportedMethods 设为提供方 URL,SKU 放进 data;Play 忽略你仍必须提供的 total。在服务器上确认 purchaseToken:任何三天内未确认的购买,Google Play 都会退款并撤销(Chrome for Developers 指南)。之后的启动里,listPurchases() 返回用户已拥有的内容,包括在其他设备上的购买。
async function buy(service, sku) { if (!service) return startWebCheckout(sku); const request = new PaymentRequest( [{ supportedMethods: PLAY_BILLING, data: { sku } }], { total: { label: 'Total', amount: { currency: 'USD', value: '0' } } }, ); try { const response = await request.show(); const { purchaseToken } = response.details; const verified = await postJson('/play/acknowledge', { sku, purchaseToken }); await response.complete(verified ? 'success' : 'fail'); if (verified) await service.consume(purchaseToken); // 仅限消耗型商品 } catch (err) { if (err.name !== 'AbortError') throw err; // 用户退出了 Play 购买面板 }}
async function restoreEntitlements(service) { if (!service) return []; const owned = await service.listPurchases(); return (await postJson('/play/verify', owned)).filter((p) => p.valid).map((p) => p.itemId);}consume() 只用于设计为可重复购买的商品。规范规定,消耗购买后用户应失去相应权益,所以不要对订阅或永久升级调用它。
另请参阅
链接到“另请参阅”一节- Payment Request API,流程中负责购买的那一半
- Trusted Web Activity(TWA):PWA 进入 Play 商店,该 API 所要求的容器
- 为 PWA 创造收入
- Digital Goods API: getDigitalGoodsService() method(wicg.github.io)
- Receive Payments via Google Play Billing with the Digital Goods API and the Payment Request API(developer.chrome.com)
- Chrome Platform Status: Digital Goods API(chromestatus.com)
规范
| 规范 | 状态 |
|---|---|
| Digital Goods API: getDigitalGoodsService() method | WICG 草案 |