共用方式為

提供數位商品 API 的應用內購買

如果您的 Progressive Web App (PWA) 列於 Microsoft Store，您可以透過 Digital Goods API 和 Payment Request API 提供應用程式內產品與訂閱。

數位商品 API

數位商品 API 是你 PWA 應用程式與 Microsoft Store 之間的介面。 數位商品 API 支援：

  • 從 Microsoft Store 後端查詢數位商品的詳細資訊，例如商品名稱、描述及區域價格。
  • 消費或確認購買。
  • 檢查用戶目前擁有的數位物品。
  • 正在檢查使用者的購買紀錄。

請參閱：

付款請求 API

付款請求 API 負責用戶購買時的實際付款交易。 付款請求 API 利用 Digital Goods API 提供的商品細節，透過使用者在 Microsoft Store 設定的帳單付款方式進行應用程式內購買。

請參閱：

啟用數位商品 API

數位商品 API 目前已適用於 Microsoft Edge 的所有通路。 測試 API 時，請確保你的 Edge 版本是 134.0.3124.51 或更高。

檢查數位商品 API 是否可用

要偵測你網站上是否有 API 存取權，請檢查該方法是否 getDigitalGoodsService 存在於物件上 window ：

if ('getDigitalGoodsService' in window) {
  // The Digital Goods API is supported.
} else {
  console.log('DigitalGoodsService is not available.');
  // Use another payment method.
}

另請參閱:

連接Microsoft門市帳單服務 (window.getDigitalGoodsService 方法)

使用 getDigitalGoodsService 物件的方法 window 連接 Microsoft Store 帳單服務。 會回傳一個 DigitalGoodsService 介面 。

數位商品 API 設計上可相容多種瀏覽器與數位商店，類似支付請求 API 的瀏覽器無關性，可與不同支付供應商共用。 若要取得 Microsoft Store Billing 的服務實例，請將該字串 "https://store.microsoft.com/billing" 作為支付方式傳遞給該 getDigitalGoodsService 方法。

若該方法出現錯誤， (例如使用者透過瀏覽器) 存取你的 PWA， Microsoft Store Billing 付款方式將無法使用。 或者，考慮提供不同的付款方式。

if (window.getDigitalGoodsService === undefined) {
  // The Digital Goods API isn't supported in this context.
  return;
}
try {
  const digitalGoodsService = await window.getDigitalGoodsService("https://store.microsoft.com/billing");
  // Use the service here.
  ...
} catch (error) {
  // The preferred service provider is not available.
  // Use a web-based payment flow instead.
  return;
}

此付款方式 getDigitalGoodsService("https://store.microsoft.com/billing") 僅適用於從 Windows 上安裝的 Microsoft Store 的 PWA。 不需要其他設定。

另請參閱:

查詢項目細節 (getDetails 方法)

使用 getDetails 介面的方法 DigitalGoodsService 來查詢項目細節。

將數位商品服務連接到 Microsoft Store 後，你可以使用 API 存取產品與購買資訊。 這個 getDetails 方法讓你能在合作夥伴中心取得你已設定的項目資訊。 在應用程式介面中顯示產品名稱、描述和價格等資訊，讓使用者知道有哪些商品可供購買。

此 getDetails 方法會取得一份項目 ID 清單，對應於您在合作夥伴中心建立的應用程式內產品與訂閱的產品 ID。

const itemDetails = await digitalGoodsService.getDetails(['shiny_sword', 'gem', 'monthly_subscription']);

for (item of itemDetails) {
  const priceStr = new Intl.NumberFormat(
      locale,
      {style: 'currency', currency: item.price.currency}
    ).format(item.price.value);

  // Do something with the item's data, such as displaying it in the PWA's UI.
  displayProductItem(item.itemId, item.title, priceStr, item.description);
}

回傳 itemDetails 的序列可以是任意順序，如果該項目不存在於伺服器 (，也就是說輸入清單與輸出清單) 之間沒有 1：1 對應，則可能不包含該項目。

項目 ID 是一個字串，代表項目的主鍵。 在 Microsoft Store 中，項目 ID 為 InAppOfferToken。 沒有函式可以取得項目 ID 清單;物品 ID 應該硬編碼在客戶端程式碼中，或是從你自己的伺服器 (開發者的伺服器) 取得。

該物品 price 的 a PaymentCurrencyAmount 包含該物品在使用者當前地區和貨幣中的價格。 設計 price 上可依 Intl.NumberFormat使用者目前所在地進行格式化，使用上述方式。

另請參閱

數位商品 API 規範

Windows App 開發：

W3C：

MDN：

購買 (PaymentRequest 建構器與 show 方法)

當您的產品與詳細資料顯示給使用者後，請使用付款請求 API 來實現購買流程。 購買物品時，首先使用建構子構造包含物品細節 PaymentRequest 的請求，然後使用 show 物件的方法 PaymentRequest 開始付款流程。

與 Digital Goods API 結合時，建構子唯一需要的輸入參數 PaymentRequest 為 methodData。 在構造子參數中：

  • 在成員中 supportedMethods ，請指定 Microsoft Store Billing 作為支付方式，字串 'https://store.microsoft.com/billing'。
  • 在構 data 件中，將 傳遞 itemId 為 sku。
const details = await digitalGoodsService.getDetails(['monthly_subscription']);
const item = details[0];

const request = new PaymentRequest([
  {
    supportedMethods: 'https://store.microsoft.com/billing',
    data: { sku: item.itemId }
  }
]);

接著呼叫 show 物件的方法 PaymentRequest ，開始支付流程：

const response = await request.show();

這會顯示商店購買介面，使用者可以查看他們想購買的產品細節。 在此過程中，目前的瀏覽器會被暫時停用，直到購買流程完成。 使用者可以選擇取消交易，或繼續付款：

  • 如果使用者取消付款，該方法回傳 show 的 Promise 會以錯誤方式被拒絕。

  • 若用戶成功付款並完成購買，承諾會以 PaymentResponse。 在 details 支付回應的屬性中，會返回購買代幣。

另請參閱:

消費 (consume 方法)

使用 consume 介面的方式 DigitalGoodsService 來消費消費。

消耗 品購買 是指設計成可以多次購買的購買。 消耗品購買通常需要標記為「已消費」，使用者才能再次購買該購買。 消耗品購買的例子是遊戲中的強化道具，能讓玩家在短時間內變得更強。

要將購買標記為「已消費」，請使用 consume 以下方法：

digitalGoodsService.consume(purchaseToken);

另請參閱:

檢查現有購買紀錄 (listPurchases 方法)

使用 listPurchases 介面的方法 DigitalGoodsService 來檢查現有的購買紀錄。 此方法會回傳使用者現有購買的資訊。 此方法允許用戶端取得目前擁有或購買的項目清單。 這可能是必要的，以進行以下任一：

  • 檢查是否有資格，例如訂閱、促銷代碼或永久升級是否有效。

  • 從購買過程中網路中斷的恢復，例如商品已購買但尚未確認。

此 listPurchases 方法會回傳物品 ID 和購買代幣。 在授予權利之前，您應該使用直接開發者對提供者的 API 驗證退回的商品 ID 或退回的購買代幣，如下所示：

const purchaseList = await digitalGoodsService.listPurchases();

for (const purchase of purchaseList) {
  // Handle the purchase data in your PWA.
  verifyAndGrantEntitlement(purchase.itemId, purchase.purchaseToken);
}

此 listPurchases 方法不會退還已消費的產品或過期的訂閱。

另請參閱:

取得購買紀錄 (listPurchaseHistory 方法)

使用 listPurchaseHistory 介面的方法 DigitalGoodsService 來取得購買紀錄。

此方法回傳包含 的 PurchaseDetails 清單，包含每筆購買的 與 itemIdpurchaseToken 。 清單包含使用者對每項商品最近一次的購買，無論購買是否已過期、取消或已消費。

const purchaseList = await digitalGoodsService.listPurchaseHistory();

for (const purchase of purchaseList) {
  // Handle the expired purchase data in your PWA.
  verifyAndCheckExpiredEntitlement(purchase.itemId, purchase.purchaseToken);
}

另請參閱:

另請參閱

GitHub：

MDN：

W3C：

Windows App 開發：

  • Last updated on