Skip to content

Commit

Permalink
take into account PR review remarks
Browse files Browse the repository at this point in the history
  • Loading branch information
levalleux-ludo committed Oct 23, 2023
1 parent 2ef2a07 commit f00836f
Show file tree
Hide file tree
Showing 6 changed files with 56 additions and 53 deletions.
51 changes: 25 additions & 26 deletions docs/redemption-widget.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,13 +66,13 @@ A Seller can specify which exchange is going to be redeemed by the widget, by ad

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

#### rNFTs for a specific seller
#### rNFTs for a/some specific seller(s)

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).
The widget can also be configured to show only the rNFTs emitted by some specific Boson Seller Accounts (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:
To add a Seller filter to the redemption widget, add a *data-seller-ids* tag to the "boson-redeem" button, specifying the list of Boson Seller accounts you're addressing to:
```
<button type="button" id="boson-redeem" data-config-id="production-137-0" data-seller-id="138">Redeem Exchange</button>
<button type="button" id="boson-redeem" data-config-id="production-137-0" data-seller-ids="26,110,138">Redeem Exchange</button>
```

### Integrating the Redemption Widget as an iFrame
Expand All @@ -93,32 +93,31 @@ In which case the page:
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>
<iframe src="https://widgets.bosonprotocol.io/#/redeem?sellerIds=26,110,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
<button class="bosonButton" id="boson-redeem-button" data-config-id="production-137-0" data-seller-ids="26,110,138">Show Redeem</button>
```


| URL parameter | HTML attribute | Required | Default Value | Purpose | Example |
| ------ | -------- | ------- | ------- | ------- | ------- |
| configId | data-config-id | yes | none | the Boson Protocol environment the widget is linked to (see [Boson Environments](../boson-environments.md)) | ```"production-137-0"```
| 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 | ```"0x023456789abcd0213456789abcd213456789abcd"```
| 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) | ```"REDEEM_FORM"```
| exchangeId | data-exchange-id | no | none | The ID of the exchange being redeemed (or cancelled). Relevant when used with widgetAction **different** than SELECT_EXCHANGE. | ```"123"```
| 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. | ```"46,78,90"```
| exchangeState | data-exchange-state | no | "Committed" | State of the exchanges when shown in the Select Exchange step. Relevant when widgetAction is SELECT_EXCHANGE. | ```"Redeemed"```
| 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)) | ```false```
| deliveryInfo | data-delivery-info | no | none | specify the delivery details that shall prefill the Redeem form, or be recapped on Confirm Redeem step. | ```'{"name":"TITI","streetNameAndNumber":"1 grand place","city":"LILLE","state":"NORD","zip":"59000","country":"FR","email":"toto@mail.com","phone":"+33123456789"}'```
| 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)) | ```"https://myshop.com/deliveryInfo"```
| postDeliveryInfoHeaders | data-post-delivery-info-headers | no | none | optionally specifies some request headers that must be added to the ***DeliveryInfo*** HTTP request | ```'{"authorization":"Bearer eyJhbGciOiJIUzL1Ni2sInR5cCI6IkpXVCJ7","another-header":"*****"}'```
| 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 | ```"https://myshop.com/redemptionSubmitted"```
| postRedemptionSubmittedHeaders | data-post-redemption-submitted-headers | no | none | optionally specifies some request headers that must be added to the ***RedemptionSubmitted*** HTTP request | ```'{"authorization":"Bearer eyJhbGciOiJIUzL1Ni2sInR5cCI6IkpXVCJ7","another-header":"*****"}'```
| 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 | ```"https://myshop.com/redemptionConfirmed"```
| postRedemptionConfirmedHeaders | data-post-redemption-confirmed-headers | no | none | optionally specifies some request headers that must be added to the ***RedemptionConfirmed*** HTTP request | ```'{"authorization":"Bearer eyJhbGciOiJIUzL1Ni2sInR5cCI6IkpXVCJ7","another-header":"*****"}'```


### Advanced Redemption Flows
Expand Down
30 changes: 17 additions & 13 deletions docs/redemption-widget/backend-redemption-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,12 @@ If required, every backend request can contain specific headers (for instance us
| parameter | required | purpose |
| ------ | -------- | ------- |
| configId | yes | the Boson Protocol environment the widget is linked to (see [Boson Environments](../boson-environments.md)) |
| sellerId | no | specifies the sellerId to filter the exchanges shown to the user (step #3 below)
| sellerIds | no | specifies the list of sellerIds to filter the exchanges shown to the user (step #3 below)
| postDeliveryInfoUrl | yes - in this present case | this is the URL to which the widget will post the ***DeliveryInfo*** HTTP request with the delivery Details (step #6.2 below)
| sellerIds | no | specifies the list of sellerIds to filter the exchanges shown to the user ([step #3 below](#Select-Exchange))
| postDeliveryInfoUrl | yes - in this present case | this is the URL to which the widget will post the ***DeliveryInfo*** HTTP request with the delivery Details ([step #6.2 below](#postDeliveryInfo))
| postDeliveryInfoHeaders | no | specifies some request headers that must be added to the ***DeliveryInfo*** HTTP request
| postRedemptionSubmittedUrl | no | this is the URL to which the widget will post the ***RedemptionSubmitted*** HTTP request with the delivery Details (step #6.4 below)
| postRedemptionSubmittedUrl | no | this is the URL to which the widget will post the ***RedemptionSubmitted*** HTTP request with the delivery Details ([step #6.4 below](#postRedemptionSubmitted))
| postRedemptionSubmittedHeaders | no | specifies some request headers that must be added to the ***RedemptionSubmitted*** HTTP request
| postRedemptionConfirmedUrl | no | this is the URL to which the widget will post the ***RedemptionConfirmed*** HTTP request with the delivery Details (step #7 below)
| postRedemptionConfirmedUrl | no | this is the URL to which the widget will post the ***RedemptionConfirmed*** HTTP request with the delivery Details ([step #7 below](#postRedemptionConfirmed))
| postRedemptionConfirmedHeaders | no | specifies some request headers that must be added to the ***RedemptionConfirmed*** HTTP request

### Main Flow (continuous)
Expand All @@ -39,22 +38,24 @@ When the Seller website activates the Redemption Widget with the adequate option
![Wallet connection](./../assets/redemption-widget/1-wallet-connection.png)
In case the user wallet is already connected, this step is skipped

<div id="showRedemptionOverview"></div>
2. Redemption Overview

![Redemption Overview](./../assets/redemption-widget/2-redemption-overview.png)


<div id="Select-Exchange"></div>
3. Select Exchange

![Select Exchange](./../assets/redemption-widget/3-select-exchange-filtered.png)

Committed exchanges owned by the connected wallet are shown to the user, that are the rNFT owned by the wallet and that the user can redeem. In this example, the ***sellerId*** parameter is used to show only the exchanges of a unique seller.
Committed exchanges are shown to the user. These are the rNFT owned by the wallet and that the user can redeem. In this example, the ***sellerIds*** parameter is used to show only the exchanges of a unique seller.

The user selects an rNFT and clicks it to show the "Exchange Card". Optionally, the Redeem button can be directly clicked, which leads the user directly to the Redeem Form

4. Exchange Card

![Exchange Card](./../assets/redemption-widget/4-exchange-card-2.png)
This view show details about the exchange, and presents a Redeem button (in case the rNFT is redeemable) that the user can click to jump to the Redeem Form
This view shows details about the exchange, and presents a Redeem button (in case the rNFT is redeemable) that the user can click to jump to the Redeem Form

5. Redeem Form

Expand All @@ -69,6 +70,7 @@ When the Seller website activates the Redemption Widget with the adequate option

First, the user is asked to sign the delivery details with their wallet to allow the backend to verify the request is coming from the real buyer.

<div id="postDeliveryInfo"></div>
6.2 POST DeliveryInfo

Once the message is signed by the wallet an HTTP request ***post DeliverInfo*** is sent to the backend containing the delivery information, details about the redeemed exchange, and the user signature.
Expand All @@ -83,6 +85,7 @@ When the Seller website activates the Redemption Widget with the adequate option

Now the user is asked to click on **Confirm Redemption** to send the Redeem transaction on-chain (to be signed/confirmed by the user with their wallet)

<div id="postRedemptionSubmitted"></div>
6.4 POST Redemption Submitted

Once the Redeem transaction is signed by the wallet and sent on-chain, an HTTP request ***post RedemptionSubmitted*** is sent to the backend containing the details about the redeemed exchange and the expected transaction hash *(Note: the hash of the real transaction may be different than the expected one, for instance in case the wallet resubmits with higher fees, to speed it up)*.
Expand All @@ -93,6 +96,7 @@ When the Seller website activates the Redemption Widget with the adequate option
![Congratulations](./../assets/redemption-widget/7-congratulations-2.jpg)
Once the Redeem transaction is confirmed on-chain, a congratulation message is shown to the user.

<div id="postRedemptionConfirmed"></div>
Once the Redeem transaction is confirmed on-chain, an HTTP request ***post RedemptionConfirmed*** is sent to the backend, containing the details about the redeemed exchange, the effective transaction hash and the blockNumber where the transaction has been validated.

The backend response to this HTTP request has no effect on the widget flow.
Expand All @@ -111,7 +115,7 @@ It is possible to interrupt the redemption flow between the delivery details is

This is useful to allow full redemption to include an additional step or verification between these 2 steps.

Interruption is triggered by the response the backend sends back to the widget when replying to the HTTP ***post DeliverInfo*** request (step #6.2 above).
Interruption is triggered by the response the backend sends back to the widget when replying to the HTTP ***post DeliverInfo*** request ([step #6.2 above](#postDeliveryInfo)).

6. Redeem Confirmation

Expand Down Expand Up @@ -140,13 +144,13 @@ To start the widget directly on the Redemption Confirmation flow, the following
| configId | yes | the Boson Protocol environment the widget is linked to (see [Boson Environments](../boson-environments.md)) |
| exchangeId | yes - in this present case | the ID of the exchange being redeemed.
| widgetAction | yes - in this present case | **"CONFIRM_REDEEM"**: the action the widget is going to jump on
| showRedemptionOverview | yes - in this present case | **false**: to skip the Redemption Overview (step #2 above)
| showRedemptionOverview | yes - in this present case | **false**: to skip the Redemption Overview ([step #2 above](#showRedemptionOverview))
| deliveryInfo | yes - in this present case | the delivery details that have been validated by the eCommerce backend for this redemption, shown to the user before they confirm the redemption.
| postDeliveryInfoUrl | yes - in this present case | this is the URL to which the widget will post the ***DeliveryInfo*** HTTP request with the delivery Details (step #6.2 below)
| postDeliveryInfoUrl | yes - in this present case | this is the URL to which the widget will post the ***DeliveryInfo*** HTTP request with the delivery Details ([step #6.2 above](#postDeliveryInfo))
| postDeliveryInfoHeaders | no | optionally specifies some request headers that must be added to the ***DeliveryInfo*** HTTP request
| postRedemptionSubmittedUrl | no | this is the URL to which the widget will post the ***RedemptionSubmitted*** HTTP request with the delivery Details (step #6.4 below)
| postRedemptionSubmittedUrl | no | this is the URL to which the widget will post the ***RedemptionSubmitted*** HTTP request with the delivery Details ([step #6.4 above](#postRedemptionSubmitted))
| postRedemptionSubmittedHeaders | no | optionally specifies some request headers that must be added to the ***RedemptionSubmitted*** HTTP request
| postRedemptionConfirmedUrl | no | this is the URL to which the widget will post the ***RedemptionConfirmed*** HTTP request with the delivery Details (step #7 below)
| postRedemptionConfirmedUrl | no | this is the URL to which the widget will post the ***RedemptionConfirmed*** HTTP request with the delivery Details ([step #7 above](#postRedemptionConfirmed))
| postRedemptionConfirmedHeaders | no | optionally specifies some request headers that must be added to the ***RedemptionConfirmed*** HTTP request

6. Redeem Confirmation (follow-up)
Expand Down
2 changes: 1 addition & 1 deletion docs/redemption-widget/default-cancellation-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ When the Seller website activates the Redemption Widget with the default options

4. Exchange Card
![Exchange Card](./../assets/redemption-widget/4-exchange-card.png)
This view shows details about the exchange, and present a Cancel button (in case the rNFT is cancellable) that the user can click to jump to the Cancel Form
This view shows details about the exchange, and presents a Cancel button (in case the rNFT is cancellable) that the user can click to jump to the Cancel Form

5. Cancel Form
![Cancel Form](./../assets/redemption-widget/5-cancel-form.png)
Expand Down
8 changes: 4 additions & 4 deletions docs/redemption-widget/default-redemption-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,21 @@ When the Seller website activate the Redemption Widget with the default options,

1. Wallet connection (if needed)
![Wallet connection](./../assets/redemption-widget/1-wallet-connection.png)
In case the user wallet is already connected, this step is ignored
In case the user wallet is already connected, this step is skipped

2. Redemption Overview
![Redemption Overview](./../assets/redemption-widget/2-redemption-overview.png)

3. Select Exchange
![Select Exchange](./../assets/redemption-widget/3-select-exchange.png)

By default, the Committed exchanges are shown to the user, that are the rNFT owned by the wallet and that the user can redeem.
By default, the Committed exchanges are shown to the user. These are the rNFT owned by the wallet and that the user can redeem.

The user select a rNFT and click it to show the "Exchange Card". Optionally, Redeem button can be directly clicked, that lead the user directly to the Redeem Form
The user selects an rNFT and clicks it to show the "Exchange Card". Optionally, the Redeem button can be directly clicked, which leads the user directly to the Redeem Form

4. Exchange Card
![Exchange Card](./../assets/redemption-widget/4-exchange-card.png)
This view show details about the exchange, and present a Redeem button (in case the rNFT is redeemable) that the user click to jump to the Redeem Form
This view shows details about the exchange, and presents a Redeem button (in case the rNFT is redeemable) that the user can click to jump to the Redeem Form

5. Redeem Form
![Redeem Form](./../assets/redemption-widget/5-redeem-form.png)
Expand Down
Loading

0 comments on commit f00836f

Please sign in to comment.