Skip to content

Commit

Permalink
Merge pull request #3324 from MicrosoftDocs/user/mikehoffms/dig-goods
Browse files Browse the repository at this point in the history 
Clarify "Provide in-app purchases with the Digital Goods API"
  • Loading branch information
@captainbrosset
captainbrosset authored Dec 20, 2024
2 parents ee73441 + e7192dc commit c53a76c
Showing 1 changed file with 117 additions and 40 deletions.
157 changes: 117 additions & 40 deletions microsoft-edge/progressive-web-apps-chromium/how-to/digital-goods-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ ms.author: msedgedevrel
ms.topic: conceptual
ms.service: microsoft-edge
ms.subservice: pwa
ms.date: 11/25/2024
ms.date: 12/19/2024
---
# Provide in-app purchases with the Digital Goods API

Expand All @@ -24,62 +24,100 @@ The Digital Goods API is an interface between your PWA app and the Microsoft Sto

See:
* [Digital Goods API For Microsoft Store PWA Explainer](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/PwaDigitalGoods/explainer.md)
* [Digital Goods API: Draft Community Group Report](https://wicg.github.io/digital-goods/)
* [Digital Goods API specification](https://wicg.github.io/digital-goods/)


<!-- ====================================================================== -->
## Payment Request API

The Payment Request API⁠⁠ handles the actual payment transaction when a purchase is made by a user. The Payment Request API uses the item details that the Digital Goods API provides, to make the in-app purchase by using whichever billing payment method the user has set up at the Microsoft Store.

See [Payment Request API](https://developer.mozilla.org/docs/Web/API/Payment_Request_API) at MDN.
See:
* [Payment Request API](https://developer.mozilla.org/docs/Web/API/Payment_Request_API) at MDN.


<!-- ====================================================================== -->
## Enable the Digital Goods API

The Digital Goods API is currently available for testing in Microsoft Edge. To test the API, use either of the following ways:
* To test your code locally: [Use a supported preview channel of Microsoft Edge on your dev machine](#use-a-supported-preview-channel-of-microsoft-edge-on-your-dev-machine).
* To test your code in your Microsoft Store PWA: [Register for the origin trial, then use your token at your website](#register-for-the-origin-trial-then-use-your-token-at-your-website).

Details are below.


<!-- ------------------------------ -->
#### Use a supported preview channel of Microsoft Edge on your dev machine

To test the Digital Goods API locally, before deploying your app to production, run Edge Dev or Edge Canary. These preview versions of Edge have the API enabled, as part of a running experiment.

To download a preview (insider) channel of Microsoft Edge, see [Become a Microsoft Edge Insider](https://aka.ms/microsoftedge).


<!-- ------------------------------ -->
#### Register for the origin trial, then use your token at your website

To test the Digital Goods API in production, with your users, use an origin trial token. With this approach, when your users download your PWA from the Microsoft Store, they will have the API enabled.

See:
* [Use origin trials in Microsoft Edge](../../origin-trials/index.md)
* [Digital Goods API](https://developer.microsoft.com/microsoft-edge/origin-trials/trials/4b4a9ead-d912-4349-87b3-25e5e50b4f13) at _Origin Trials_.


<!-- ====================================================================== -->
## Checking whether the Digital Goods API is available

To detect whether you've correctly enabled the API on your website, check for the `getDigitalGoodsService` method in the window object:
To detect whether you've correctly enabled the API on your website by using your origin trial token, check whether the `getDigitalGoodsService` method exists on the `window` object:

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

See also:
* [getDigitalGoodsService() method](https://wicg.github.io/digital-goods/#getdigitalgoodsservice-method) of the `Window` interface.


<!-- ====================================================================== -->
## Connecting to the Microsoft Store Billing service (`getDigitalGoodsService` method)
## Connecting to the Microsoft Store Billing service (`window.getDigitalGoodsService` method)

Use the `getDigitalGoodsService` method to connect to the Microsoft Store Billing service.
Use the `getDigitalGoodsService` method of the `window` object to connect to the Microsoft Store Billing service. A [DigitalGoodsService interface](https://wicg.github.io/digital-goods/#digitalgoodsservice) is returned.

The Digital Goods API was designed to be compatible with various browsers and digital stores, similar to how the Payment Request API is browser-agnostic and can be used with different payment providers. To retrieve an instance of the service for Microsoft Store Billing, pass the string `"https://store.microsoft.com/billing"` as the payment method to the `getDigitalGoodsService` method.

If the method throws an error, the Microsoft Store Billing payment method is not available (such as when the user is accessing your PWA through the browser). Alternatively, consider providing a different payment method for transactions.

```javascript
if (window.getDigitalGoodsService === undefined) {
// Digital Goods API is not supported in this context.
// 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) {
// Our preferred service provider is not available.
// The preferred service provider is not available.
// Use a web-based payment flow instead.
return;
}
```

This payment method `getDigitalGoodsService("https://store.microsoft.com/billing")` is available only for a PWA that's installed from the Microsoft Store, on Windows. No other settings are needed.

See also:
* [getDigitalGoodsService() method](https://wicg.github.io/digital-goods/#getdigitalgoodsservice-method) of the `Window` interface.
* [DigitalGoodsService interface](https://wicg.github.io/digital-goods/#digitalgoodsservice)


<!-- ====================================================================== -->
## Querying item details (`getDetails` method)

Use the `getDetails` method to query item details.
Use the `getDetails` method of the `DigitalGoodsService` interface to query item details.

After connecting the Digital Goods service to Microsoft Store, you can use the API to access product and purchase information. The `getDetails` method lets you get information about the items you’ve set up in the Partner Center. Display information such as the product title, description, and price in your app UI, so the user knows what's available for purchase.

Expand All @@ -105,20 +143,31 @@ The item ID is a string that represents the primary key of the items. In the Mi

The item's `price` is a `PaymentCurrencyAmount` that contains the current price of the item in the user's current region and currency. The `price` is designed to be formatted for the user's current locale by using `Intl.NumberFormat`, as shown above.

See also:

<!-- ------------------------------ -->
#### See also

Digital Goods API specification
* [getDetails() method](https://wicg.github.io/digital-goods/#getDetails-method)

Windows App Development:
* [StoreProduct.InAppOfferToken Property](/uwp/api/windows.services.store.storeproduct.inappoffertoken)
* [PaymentCurrencyAmount dictionary](https://www.w3.org/TR/payment-request/#dom-paymentcurrencyamount) in _Payment Request API_ at W3C.
* [Intl.NumberFormat](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) at MDN.

W3C:
* [PaymentCurrencyAmount dictionary](https://www.w3.org/TR/payment-request/#dom-paymentcurrencyamount)

<!-- ====================================================================== -->
## Purchasing an item (`show` method)
MDN:
* [Intl.NumberFormat](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)

Use the `show` method to purchase an item, after you construct a request that contains the item details.

Once your products and details are displayed to the user, you can implement the purchase flow by using the Payment Request API. When combined with the Digital Goods API, the only required input parameter is `methodData`.
<!-- ====================================================================== -->
## Purchasing an item (`PaymentRequest` constructor and `show` method)

After your products and details are displayed to the user, implement the purchase flow by using the Payment Request API. To purchase an item, first construct a request that contains the item details by using the `PaymentRequest` constructor, and then use the `show` method of the `PaymentRequest` object to start the payment flow.

Use the `supportedMethods` member of the `methodData`⁠⁠ parameter in the `PaymentRequest` to identify Microsoft Store Billing as the payment method with the string `"https://store.microsoft.com/billing"`. Then in the `data` member, pass along the item ID as the `sku`.
When combined with the Digital Goods API, the only required input parameter for the `PaymentRequest` constructor is `methodData`. In the constructor's parameter:
* In the `supportedMethods` member, specify Microsoft Store Billing as the payment method, as the string `'https://store.microsoft.com/billing'`.
* In the `data` member, pass along the `itemId` as the `sku`.

```javascript
const details = await digitalGoodsService.getDetails(['monthly_subscription']);
Expand All @@ -132,33 +181,30 @@ const request = new PaymentRequest([
]);
```

Then call the `show` method to start the payment flow:
Then call the `show` method of the `PaymentRequest` object, to start the payment flow:

```javascript
const response = await request.show();
```

This will display the Store purchase UI to the user, where the user can view details about the product that they're trying to purchase. During this process, the current browser session is temporarily disabled until the purchase flow is complete. The user can either cancel the transaction, or proceed with the payment:
This displays the Store purchase UI to the user, where the user can view details about the product that they're trying to purchase. During this process, the current browser session is temporarily disabled until the purchase flow is complete. The user can either cancel the transaction, or proceed with the payment:

* If the user cancels the payment, the Promise that's returned by the `show` method will be rejected with an error.

* If the user successfully pays and completes the purchase, the Promise will resolve with a `PaymentResponse`.
* If the user successfully pays and completes the purchase, the Promise will resolve with a `PaymentResponse`. In the `details` property of the payment response, a purchase token is returned.

In the `details` property of the payment response, a purchase token is returned.


<!-- ====================================================================== -->
## Acknowledging a purchase

The payment response returns a _purchase token_ string, which can be used for direct communication between your server and the service provider beyond the Digital Goods API. Such communication can allow you to independently verify information about the purchase before granting entitlements.

Some stores might require that you (the developer) acknowledge a purchase after the purchase has succeeded, to confirm that the purchase has been recorded.
See also:
* [Payment Request API](https://developer.mozilla.org/docs/Web/API/Payment_Request_API)
* [PaymentRequest: PaymentRequest() constructor](https://developer.mozilla.org/docs/Web/API/PaymentRequest/PaymentRequest)
* [PaymentRequest: show() method](https://developer.mozilla.org/docs/Web/API/PaymentRequest/show)
* [PaymentResponse](https://developer.mozilla.org/docs/Web/API/PaymentResponse/)
* [PaymentResponse: details property](https://developer.mozilla.org/docs/Web/API/PaymentResponse/details)


<!-- ====================================================================== -->
## Consuming a purchase (`consume` method)

Use the `consume` method to consume a purchase.
Use the `consume` method of the `DigitalGoodsService` interface to consume a purchase.

A _consumable purchase_ is a purchase that's designed to be purchased multiple times. A consumable purchase usually needs to be marked as "consumed" before the purchase can be purchased again by the user. An example of a consumable purchase is an in-game powerup that makes the player stronger for a short period of time.

Expand All @@ -168,11 +214,14 @@ To mark a purchase as "consumed", use the `consume` method:
digitalGoodsService.consume(purchaseToken);
```

See also:
* [consume() method](https://wicg.github.io/digital-goods/#consume-method) of the `DigitalGoodsService` interface.


<!-- ====================================================================== -->
## Checking existing purchases (`listPurchases` method)

Use the `listPurchases` method to check existing purchases. This method returns information about the user's existing purchases. This method allows a client to get a list of items that are currently owned or purchased by the user. This may be necessary, to do either of the following:
Use the `listPurchases` method of the `DigitalGoodsService` interface to check existing purchases. This method returns information about the user's existing purchases. This method allows a client to get a list of items that are currently owned or purchased by the user. This may be necessary, to do either of the following:

* Check for entitlements, such as whether a subscription, promotional code, or permanent upgrade is active.

Expand All @@ -191,11 +240,16 @@ for (const purchase of purchaseList) {

The `listPurchases` method doesn't return consumed products or expired subscriptions.

See also:
* [listPurchases() method](https://wicg.github.io/digital-goods/#listPurchases-method) of the `DigitalGoodsService` interface.


<!-- ====================================================================== -->
## Getting the purchase history (`listPurchaseHistory` method)

Use the `listPurchaseHistory` method to get the purchase history. This method returns a list that shows the most recent purchase made by the user for each item, regardless of whether the purchase is expired, canceled, or consumed. This method returns a list of `PurchaseDetails` containing the `itemId` and `purchaseToken` for each purchase.
Use the `listPurchaseHistory` method of the `DigitalGoodsService` interface to get the purchase history.

This method returns a list of `PurchaseDetails` containing the `itemId` and `purchaseToken` for each purchase. The list includes the most recent purchase made by the user for each item, regardless of whether the purchase is expired, canceled, or consumed.

```javascript
const purchaseList = await digitalGoodsService.listPurchaseHistory();
Expand All @@ -206,17 +260,40 @@ for (const purchase of purchaseList) {
}
```

See also:
* [listPurchaseHistory() method](https://wicg.github.io/digital-goods/#listPurchaseHistory-method) of the `DigitalGoodsService` interface.
* [PurchaseDetails dictionary](https://wicg.github.io/digital-goods/#purchaseDetails-dictionary)


<!-- ====================================================================== -->
## See also
<!-- all links in article: -->

* [Digital Goods API For Microsoft Store PWA Explainer](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/PwaDigitalGoods/explainer.md)
* [StoreProduct.InAppOfferToken Property](/uwp/api/windows.services.store.storeproduct.inappoffertoken)
Origin trials:
* [Use origin trials in Microsoft Edge](../../origin-trials/index.md)
* [Digital Goods API](https://developer.microsoft.com/microsoft-edge/origin-trials/trials/4b4a9ead-d912-4349-87b3-25e5e50b4f13) at _Origin Trials_.

W3C:
* [Digital Goods API: Draft Community Group Report](https://wicg.github.io/digital-goods/)
* [Payment Request API](https://www.w3.org/TR/payment-request/)
* [PaymentCurrencyAmount dictionary](https://www.w3.org/TR/payment-request/#dom-paymentcurrencyamount) in _Payment Request API_.
GitHub:
* [Digital Goods API For Microsoft Store PWA Explainer](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/PwaDigitalGoods/explainer.md)
* [Digital Goods API specification](https://wicg.github.io/digital-goods/)
* [getDigitalGoodsService() method](https://wicg.github.io/digital-goods/#getdigitalgoodsservice-method) of the `Window` interface.
* [DigitalGoodsService interface](https://wicg.github.io/digital-goods/#digitalgoodsservice)
* [getDetails() method](https://wicg.github.io/digital-goods/#getDetails-method)
* [listPurchases() method](https://wicg.github.io/digital-goods/#listPurchases-method)
* [listPurchaseHistory() method](https://wicg.github.io/digital-goods/#listPurchaseHistory-method)
* [consume() method](https://wicg.github.io/digital-goods/#consume-method)
* [PurchaseDetails dictionary](https://wicg.github.io/digital-goods/#purchaseDetails-dictionary)

MDN:
* [Payment Request API](https://developer.mozilla.org/docs/Web/API/Payment_Request_API)
* [PaymentRequest: PaymentRequest() constructor](https://developer.mozilla.org/docs/Web/API/PaymentRequest/PaymentRequest)
* [PaymentRequest: show() method](https://developer.mozilla.org/docs/Web/API/PaymentRequest/show)
* [PaymentResponse](https://developer.mozilla.org/docs/Web/API/PaymentResponse/)
* [PaymentResponse: details property](https://developer.mozilla.org/docs/Web/API/PaymentResponse/details)
* [Intl.NumberFormat](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)

W3C:
* [PaymentCurrencyAmount dictionary](https://www.w3.org/TR/payment-request/#dom-paymentcurrencyamount)

Windows App Development:
* [StoreProduct.InAppOfferToken Property](/uwp/api/windows.services.store.storeproduct.inappoffertoken)

0 comments on commit c53a76c

Please sign in to comment.