Skip to content

Commit

Permalink
improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@levalleux-ludo
levalleux-ludo committed Oct 20, 2023
1 parent 9b4162c commit 8c9e2c8
Show file tree
Hide file tree
Showing 3 changed files with 134 additions and 22 deletions.
77 changes: 68 additions & 9 deletions docs/boson-environments.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,73 @@ In addition, it's possible to deploy your own environment on your local machine.

Each environment (except ***local***) is currently deployed on several configurations, corresponding to different blockchains.

The dApps (Marketplace and Dispute Resolution Center) and widgets are able to switch between configurations of the same environment.

The following table recaps all configurations, per environment

| environment | configuration | blockchain | subgraph |
| ----------- | ------------- | ---------- | -------- |
| local | local-31337-0 | local (testnet) | http://localhost:8000/subgraphs/name/boson/corecomponents/graphql
| testing | testing-80001-0 | Polygon Mumbai (testnet) | https://api.thegraph.com/subgraphs/name/bosonprotocol/mumbai-testing
| testing | testing-5-0 | Ethereum Goerli (testnet) | https://api.thegraph.com/subgraphs/name/bosonprotocol/goerli-testing
| staging | staging-80001-0 | Polygon Mumbai (testnet) | https://api.thegraph.com/subgraphs/name/bosonprotocol/mumbai-staging
| staging | staging-5-0 | Polygon Mumbai (testnet) | https://api.thegraph.com/subgraphs/name/bosonprotocol/goerli-staging
| production | production-137-0 | Polygon | https://api.thegraph.com/subgraphs/name/bosonprotocol/polygon
| production | production-1-0 | Ethereum Mainnet | https://api.thegraph.com/subgraphs/name/bosonprotocol/ethereum
<table>
<tr><th>Environment</th><th></th></tr>
<tr><td>production</td><td>
<table>
<tr><th>Configuration</th><th>Blockchain</th><th>Subgraph</th></tr>
<tr><td>production-137-0 </td><td>Polygon</td><td>https://api.thegraph.com/subgraphs/name/bosonprotocol/polygon</td></tr>
<tr><td>production-1-0 </td><td>Ethereum Mainnet</td><td>https://api.thegraph.com/subgraphs/name/bosonprotocol/ethereum</td></tr>
</table>
<table>
<tr><th>dApps</th><th></th></tr>
<tr><td>Marketplace</td><td>https://bosonapp.io</td></tr>
<tr><td>Dispute Resolution Center</td><td>https://disputes.bosonprotocol.io</td></tr>
</table>
<table>
<tr><th>Widgets</th><th></th></tr>
<tr><td>Redemption</td><td>https://widgets.bosonprotocol.io/#/redeem</td></tr>
<tr><td>Finance</td><td>https://widgets.bosonprotocol.io/#/finance</td></tr></table>
</td></tr>
<tr><td>staging</td><td>
<table>
<tr><th>Configuration</th><th>Blockchain</th><th>Subgraph</th></tr>
<tr><td>staging-80001-0 </td><td>Polygon Mumbai (testnet)</td><td>https://api.thegraph.com/subgraphs/name/bosonprotocol/mumbai-staging</td></tr>
<tr><td>staging-5-0 </td><td>Ethereum Goerli (testnet)</td><td>https://api.thegraph.com/subgraphs/name/bosonprotocol/goerli-staging</td></tr>
</table>
<table>
<tr><th>dApps</th><th></th></tr>
<tr><td>Marketplace</td><td>https://interface-staging.on.fleek.co</td></tr>
<tr><td>Dispute Resolution Center</td><td>https://drcenter-staging.on.fleek.co/</td></tr>
</table>
<table>
<tr><th>Widgets</th><th></th></tr>
<tr><td>Redemption</td><td>https://widgets-staging.on.fleek.co/#/redeem</td></tr>
<tr><td>Finance</td><td>https://widgets-staging.on.fleek.co/#/finance</td></tr></table>
</td></tr>
<tr><td>testing</td><td>
<table>
<tr><th>Configuration</th><th>Blockchain</th><th>Subgraph</th></tr>
<tr><td>testing-80001-0</td><td>Polygon Mumbai (testnet)</td><td>https://api.thegraph.com/subgraphs/name/bosonprotocol/mumbai-testing</td></tr>
<tr><td>testing-5-0 </td><td>Ethereum Goerli (testnet)</td><td>https://api.thegraph.com/subgraphs/name/bosonprotocol/goerli-testing</td></tr>
</table>
<table>
<tr><th>dApps</th><th></th></tr>
<tr><td>Marketplace</td><td>https://interface-test.on.fleek.co</td></tr>
<tr><td>Dispute Resolution Center</td><td>https://drcenter-test.on.fleek.co/</td></tr>
</table>
<table>
<tr><th>Widgets</th><th></th></tr>
<tr><td>Redemption</td><td>https://widgets-test.on.fleek.co/#/redeem</td></tr>
<tr><td>Finance</td><td>https://widgets-test.on.fleek.co/#/finance</td></tr></table>
</td></tr>
<tr><td>local</td><td>
<table>
<tr><th>Configuration</th><th>Blockchain</th><th>Subgraph</th></tr>
<tr><td>local-31337-0 </td><td>local (testnet)</td><td>http://localhost:8000/subgraphs/name/boson/corecomponents/graphql</td></tr>
</table>
<table>
<tr><th>dApps</th><th></th></tr>
<tr><td>Marketplace</td><td>http://localhost:3333</td></tr>
<tr><td>Dispute Resolution Center</td><td>http://localhost:3333</td></tr>
</table>
<table>
<tr><th>Widgets</th><th></th></tr>
<tr><td>Redemption</td><td>http://localhost:3000/#/redeem</td></tr>
<tr><td>Finance</td><td>http://localhost:3000/#/finance</td></tr></table>
</td></tr>
</table>
71 changes: 60 additions & 11 deletions docs/redemption-widget.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

## Redeeming rNFTs using the Boson Widget

With the release of the Boson Redemption Widget Sellers can now offer redemption of their rNFTs on their own domains.
With the release of the Boson Redemption Widget, Sellers can now offer redemption of their rNFTs on their own domains.

Sellers can chose to sell their rNFTs everywhere in the metaverse, in game, on NFT marketplaces, or from the Boson dApp whilst bringing users back to their own domain to redeem their NFTs.

Expand All @@ -24,9 +24,11 @@ To integrate the Boson Redemption Widget, all a seller needs to do is:

2. The Seller then needs to create a button with the fragment identifier *id="boson-redeem"*. When clicked, the redeem modal will popup on the Seller's website.
```
<button type="button" id="boson-redeem">Show Redeem</button>
<button type="button" id="boson-redeem" data-config-id="production-137-0">Show Redeem</button>
```

The ```data-config-id``` parameter specifies the Boson Configuration addressed by the widget (here ***production-137-0*** is the production configuration deployed on the Polygon blockchain). See [Boson Environment](./boson-environments.md) to get more details.

![Redemption Widget Items View](./assets/redemption-widget/redemption_widget_2.png)

## Using the Boson Redemption Button
Expand All @@ -44,35 +46,82 @@ As a seller you can also chose to use the Boson branded "Redeem" Button on your

2. Add the below class name to the "boson-redeem" button:
```
<button type="button" id="boson-redeem" class="bosonButton">Show Redeem</button>
<button type="button" id="boson-redeem" class="bosonButton" data-config-id="production-137-0">Show Redeem</button>
```

![Boson Redeem Button](./assets/redemption-widget/redeem.png)



### Redeeming a specific rNFT
### Redeeming specific rNFTs

The Boson Widget's default behaviour is to show a buyer all of their redeemable vouchers, the widget be configured to direct a buyer to a given rNFT for redemption, this enables different user flows. This the way that the Widget is used on [the Boson dApp](https://bosonapp.io/).
#### A specific rNFT

A Seller can specify which exchange is going to be redeemed by the widget, by:
The Boson Widget's default behaviour is to show a buyer all of their redeemable vouchers. However, the widget can be configured to direct a buyer to a given rNFT for redemption, this enables different user flows. This the way that the Widget is used on [the Boson dApp](https://bosonapp.io/).

1. add a *data-exchange-id* tag to the "boson-redeem" button, specifying the exchangeId of a given exchange:
A Seller can specify which exchange is going to be redeemed by the widget, by adding a *data-exchange-id* tag to the "boson-redeem" button, specifying the exchangeId of a given exchange:
```
<button type="button" id="boson-redeem" data-exchange-id="80">Redeem Exchange 80</button>
<button type="button" id="boson-redeem" data-config-id="production-137-0" data-exchange-id="80">Redeem Exchange 80</button>
```

You can find an example HTML file which embeds the widgets on the the widgets subdomain : https://widgets.bosonprotocol.io/example.html

### Advanced redemption flows
#### rNFTs for a specific seller

The Boson Widget's default behaviour is to show a buyer all of their redeemable vouchers. However, the widget can be configured to show only the rNFTs emitted by a specific Boson Seller Account (typically the seller account the redemption site is referring to).

To add a sellerId filter to the redemption widget, add a *data-seller-id* tag to the "boson-redeem" button, specifying the sellerId of the Boson Seller account you're addressing to:
```
<button type="button" id="boson-redeem" data-config-id="production-137-0" data-seller-id="138">Redeem Exchange</button>
```

### Integrating the Redemption Widget as an iFrame

Instead of using the Redeem Button as shown above, the redemption widget can be embedded in any web page using an iFrame HTML element.

For instance: ```<iframe src="https://widgets.bosonprotocol.io//#/redeem?configId=production-137-0"></iframe>```.

In which case the page:
- does not need to include any specific line (like the ```<script>``` tag for ```boson-widgets.js```
- shall manage itself the logic to show and hide the iFrame, and the parameters to pass to its URL.

Hereafter are detailed examples of redemption flows supported by the widget.
### Redemption Widget Parameters

The following parameters configures the widget. They must be passed in the widget URL (for instance when building an iFrame).
For instance: ```<iframe src="https://widgets.bosonprotocol.io//#/redeem?sellerId=138&configId=production-137-0"></iframe>```.

When using the Redeem Button, as shown above, the parameters must be passed as HTML attributes to the Button tag. For instance: ```<button class="bosonButton" id="boson-redeem-button" data-config-id="production-137-0" data-seller-id="138">Show Redeem</button>```


| URL parameter | HTML attribute | Required | Default Value | Purpose |
| ------ | -------- | ------- | ------- | ------- |
| configId | data-config-id | yes | none | the Boson Protocol environment the widget is linked to (see [Boson Environments](../boson-environments.md)) |
| account | data-account | no | none | the address of the wallet the widget should accept. When specified, the user can't connect any other wallet that the one specified
| widgetAction | data-widget-action | no | "SELECT_EXCHANGE" | the action the widget is going to jump on (SELECT_EXCHANGE, EXCHANGE_DETAILS, REDEEM_FORM, CANCEL_FORM or CONFIRM_REDEEM)
| exchangeId | data-exchange-id | no | none | The ID of the exchange being redeemed (or cancelled). Relevant when used with widgetAction **different** than SELECT_EXCHANGE.
| sellerId | data-seller-id | no | none | Specifies the sellerId to filter the exchanges shown to the user. Relevant when widgetAction is SELECT_EXCHANGE.
| sellerIds | data-seller-ids | no | none | Specifies the list of sellerIds to filter the exchanges shown to the user. Relevant when widgetAction is SELECT_EXCHANGE.
| exchangeState | data-exchange-state | no | "Committed" | State of the exchanges when shown in the Select Exchange step. Relevant when widgetAction is SELECT_EXCHANGE.
| showRedemptionOverview | data-show-redemption-overview | no | true | set to 'false' to skip the Redemption Overview (first step in the [user flow](./redemption-widget/default-redemption-flow.md))
| deliveryInfo | data-delivery-info | no | none | specify the delivery details that shall prefill the Redeem form, or be recapped on Confirm Redeem step.
| postDeliveryInfoUrl | data-post-delivery-info-url | no | none | this is the URL to which the widget will post the ***DeliveryInfo*** HTTP request with the delivery Details (see [Redemption with 3rd party eCommerce backend](./redemption-widget/backend-redemption-flow.md))
| postDeliveryInfoHeaders | data-post-delivery-info-headers | no | none | optionally specifies some request headers that must be added to the ***DeliveryInfo*** HTTP request
| postRedemptionSubmittedUrl | data-post-redemption-submitted-url | no | none | this is the URL to which the widget will post the ***RedemptionSubmitted*** HTTP request with the delivery Details (step #6.4 below)
| postRedemptionSubmittedHeaders | data-post-redemption-submitted-headers | no | none | optionally specifies some request headers that must be added to the ***RedemptionSubmitted*** HTTP request
| postRedemptionConfirmedUrl | data-post-redemption-confirmed-url | no | none | this is the URL to which the widget will post the ***RedemptionConfirmed*** HTTP request with the delivery Details (step #7 below)
| postRedemptionConfirmedHeaders | data-post-redemption-confirmed-headers | no | none | optionally specifies some request headers that must be added to the ***RedemptionConfirmed*** HTTP request


### Advanced Redemption Flows

Hereafter are detailed examples of the redemption flows supported by the widget.

- [Default redemption flow](./redemption-widget/default-redemption-flow.md)
- [Marketplace redemption flow](./redemption-widget/marketplace-redemption-flow.md)
- [Redemption with 3rd party eCommerce backend](./redemption-widget/backend-redemption-flow.md)

Widget also supports other usecases:
The redemption widget can also support other usecases:
- [Default cancellation flow](./redemption-widget/default-cancellation-flow.md)
- [Marketplace cancellation flow](./redemption-widget/marketplace-cancellation-flow.md)
- [Raise a dispute on a redeemed exchange](./redemption-widget/raise-dispute-flow.md)

8 changes: 6 additions & 2 deletions public/scripts/boson-widgets.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,10 @@ const constants = {
loadingId: "bosonLoading",
showRedeemId: "boson-redeem",
showFinanceId: "boson-finance",
configIdTag: "data-config-id",
exchangeIdTag: "data-exchange-id",
sellerIdTag: "data-seller-id",
sellerIdsTag: "data-seller-ids",
exchangeStateTag: "data-exchange-state",
showRedemptionOverviewTag: "data-show-redemption-overview",
widgetActionTag: "data-widget-action",
Expand All @@ -20,8 +23,6 @@ const constants = {
postRedemptionSubmittedHeadersTag: "data-post-redemption-submitted-headers",
postRedemptionConfirmedUrlTag: "data-post-redemption-confirmed-url",
postRedemptionConfirmedHeadersTag: "data-post-redemption-confirmed-headers",
sellerIdTag: "data-seller-id",
configIdTag: "data-config-id",
accountTag: "data-account",
hideModalId: "boson-hide-modal",
hideModalMessage: "boson-close-iframe",
Expand Down Expand Up @@ -126,6 +127,7 @@ function bosonWidgetReload() {
const exchangeId =
showRedeemId.attributes[constants.exchangeIdTag]?.value;
const sellerId = showRedeemId.attributes[constants.sellerIdTag]?.value;
const sellerIds = showRedeemId.attributes[constants.sellerIdsTag]?.value;
const exchangeState =
showRedeemId.attributes[constants.exchangeStateTag]?.value;
const showRedemptionOverview =
Expand Down Expand Up @@ -153,6 +155,7 @@ function bosonWidgetReload() {
bosonWidgetShowRedeem({
exchangeId,
sellerId,
sellerIds,
exchangeState,
showRedemptionOverview,
widgetAction,
Expand Down Expand Up @@ -181,6 +184,7 @@ function bosonWidgetShowRedeem(args) {
const params = buildParams([
{ tag: "exchangeId", value: args.exchangeId },
{ tag: "sellerId", value: args.sellerId },
{ tag: "sellerIds", value: args.sellerIds },
{ tag: "exchangeState", value: args.exchangeState },
{
tag: "showRedemptionOverview",
Expand Down

0 comments on commit 8c9e2c8

Please sign in to comment.