共用方式為

使用數位商品 API 提供應用程式內購買

  • 發行項

如果您的漸進式 Web 應用程式 (PWA) 列在 Microsoft Store 中，您可以使用數位商品 API 和付款要求 API 來提供應用程式內產品和訂用帳戶。

數位商品 API

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

  • 從 Microsoft Store 後端查詢數位專案的詳細數據，例如專案的名稱、描述和地區價格。
  • 取用或認可購買。
  • 檢查使用者目前擁有的數字專案。
  • 檢查用戶的購買歷程記錄。

請參閱：

付款要求 API

付款要求 API 會在使用者購買時處理實際的付款交易。 付款要求 API 會使用數位商品 API 所提供的專案詳細數據，透過使用者在 Microsoft Store 上設定的任何計費付款方式，進行應用程式內購買。

請參閱：

啟用數位商品 API

數位商品 API 目前可在 Microsoft Edge 中進行測試。 若要測試 API，請使用下列其中一種方式：

詳細數據如下。

在開發電腦上使用支援的 Microsoft Edge 預覽通道

若要在本機測試 Digital Goods API，請在將應用程式部署至生產環境之前，執行 Edge Dev 或 Edge Canary。 這些 Edge 預覽版本已啟用 API，作為執行中實驗的一部分。

若要下載 Microsoft Edge 的預覽 (測試人員) 通道，請參閱成為Microsoft Edge 測試人員。

註冊原始試用版，然後在您的網站上使用您的令牌

若要在生產環境中測試數位商品 API，請與您的使用者一起使用原始試用令牌。 使用此方法時，當您的使用者從 Microsoft Store 下載您的 PWA 時，他們會啟用 API。

請參閱：

檢查數位商品 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 Store 計費服務 (window.getDigitalGoodsService 方法)

getDigitalGoodsService使用物件的 window 方法連接到 Microsoft Store 計費服務。 會傳回 DigitalGoodsService 介面 。

數位商品 API 的設計目的是要與各種瀏覽器和數位存放區相容，類似於付款要求 API 與瀏覽器無關，而且可以與不同的付款提供者搭配使用。 若要擷取 Microsoft Store 帳單的服務實例，請將字串 "https://store.microsoft.com/billing" 作為付款方式傳遞給 getDigitalGoodsService 方法。

如果方法擲回錯誤， (無法使用 Microsoft Store 計費付款方式，例如當使用者透過瀏覽器存取您的 PWA) 時。 或者，請考慮為交易提供不同的付款方式。

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 市集安裝的 PWA。 不需要其他設定。

另請參閱:

查詢方法) (getDetails 項目詳細數據

getDetails使用介面的 DigitalGoodsService 方法來查詢專案詳細數據。

將 Digital Goods 服務連線到 Microsoft Store 之後，您可以使用 API 來存取產品和購買資訊。 方法 getDetails 可讓您取得您在合作夥伴中心設定之專案的相關信息。 在您的應用程式 UI 中顯示產品標題、描述和價格等資訊，讓使用者知道可供購買的專案。

方法 getDetails 會取得專案標識碼的清單，這些標識符會對應至您在合作夥伴中心建立的應用程式內產品和訂用帳戶的產品標識碼。

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

如果專案不存在於伺服器 (，也就是輸入清單與輸出清單) 之間沒有 1：1 對應關係，則傳回 itemDetails 的序列可能會是任何順序，而且可能不包含專案。

項目標識碼是代表專案主鍵的字串。 在 Microsoft Store 中，專案識別碼為 InAppOfferToken。 沒有可取得專案識別碼清單的函式;項目標識碼應該在用戶端程式代碼中硬式編碼，或從您自己的伺服器擷取， (開發人員的伺服器) 。

專案的 price 是 ， PaymentCurrencyAmount 其中包含使用者目前區域和貨幣中專案的目前價格。 price設計成使用 Intl.NumberFormat來格式化使用者目前的地區設定，如上所示。

另請參閱

數位商品 API 規格

Windows App 開發：

W3C：

MDN：

購買專案 (PaymentRequest 建構函式和 show 方法)

向用戶顯示您的產品和詳細數據之後，請使用付款要求 API 實作購買流程。 若要購買專案，請先使用 PaymentRequest 建構函式建構包含專案詳細數據的要求，然後使用 show 物件的 PaymentRequest 方法來啟動付款流程。

與數位商品 API 結合時，建構函式的唯一 PaymentRequest 必要輸入參數是 methodData。 在建構函式的 參數中：

  • 在 成員中 supportedMethods ，將 Microsoft Store 帳單] 指定為付款方式，作為字串 '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();

這會向用戶顯示市集購買UI，用戶可以在其中檢視他們嘗試購買之產品的詳細數據。 在此程式期間，目前的瀏覽器會話會暫時停用，直到購買流程完成為止。 使用者可以取消交易，或繼續付款：

  • 如果使用者取消付款，則方法傳 show 回的承諾將會遭到拒絕，並出現錯誤。

  • 如果使用者成功支付並完成購買，Promise 將會使用 PaymentResponse來解析。 details在付款響應的 屬性中，會傳回購買令牌。

另請參閱:

使用購買 (consume 方法)

consume使用 介面的 DigitalGoodsService 方法來取用購買。

消費性購買是設計成多次購買的購買。 消費性購買通常必須標示為「已取用」，使用者才能再次購買。 消費性購買的範例是遊戲內的增強功能，可讓玩家在短時間內變得更強大。

若要將購買標示為「已取用」，請使用 方法 consume ：

digitalGoodsService.consume(purchaseToken);

另請參閱:

檢查現有購買 (listPurchases 方法)

listPurchases使用介面的 DigitalGoodsService 方法來檢查現有的購買專案。 這個方法會傳回使用者現有購買專案的相關信息。 此方法可讓用戶端取得使用者目前擁有或購買的項目清單。 若要執行下列其中一項作業，可能需要這麼做：

  • 檢查權利，例如訂用帳戶、促銷碼或永久升級是否作用中。

  • 從購買期間的網路中斷復原，例如購買專案但尚未認可時。

方法會 listPurchases 傳回專案標識碼和購買令牌。 在授與權利之前，您應該使用直接開發人員對提供者 API 來驗證傳回的專案標識碼或傳回的購買令牌，如下所示：

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 方法來取得購買記錄。

這個方法會傳回包含每個購買之 itemId 和 purchaseToken 的PurchaseDetails清單。 此清單包含使用者針對每個專案所進行的最近購買，不論購買是否已過期、取消或已取用。

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 開發：