Web SDK / Benefits list

Embed the benefits list

The benefits list shows a holder the benefits your distributor offers, one card per benefit: the ones they can claim now, the locked ones with the one sentence that says why, and the ones already claimed or redeemed. It is drawn inside your page from the rows you pass it, in the shape of the distributor API's benefits list.

View as .md

The script

Yutai serves the SDK's script at the address below: the script loads once, then the element is written with its facts as attributes.

The script is served today.

Embed code

<script src="https://yutai.com/sdk/v1/yutai-sdk-web.min.js"></script>

<yutai-benefits-list
  benefits='[
    {
      "benefitId": "bft_01H8Z2N9P4QX7K3M5A0V8D9T2W",
      "name": "Season voucher",
      "type": "VOUCHER",
      "delivery": "CODE",
      "state": "eligible",
      "sourceMode": "SIMULATED"
    },
    {
      "benefitId": "bft_01H8Z2N9P4QX7K3M5A0V8D9T2X",
      "name": "Lounge access",
      "type": "ACCESS",
      "delivery": "VENUE_REDEMPTION",
      "state": "locked",
      "lockedReason": "This benefit opens after 30 days of tenure.",
      "sourceMode": "SIMULATED"
    },
    {
      "benefitId": "bft_01H8Z2N9P4QX7K3M5A0V8D9T2Y",
      "name": "Welcome points",
      "type": "POINTS",
      "delivery": "POINTS_CREDIT",
      "state": "claimed",
      "sourceMode": "SIMULATED"
    }
  ]'
></yutai-benefits-list>

The sample

The sample renders the same list from the same element and the same three rows the embed above writes: one eligible, one locked, one claimed.

Sample rows: a simulated holder's benefits, not a real holder's.

The attribute

The list's facts arrive as one attribute: the rows, in the distributor API's own shape, as JSON text. Set it again with new rows and the list draws them at once.

The attributes the list takes
Attribute	What to pass
`benefits`	Required. The holder's benefit rows as a JSON array, at most 500 rows, each with the fields below. The list draws one card per row, in the order given. A row the list cannot draw is refused, naming the row by its position, and the list keeps its last good paint.

benefits: Required. The holder's benefit rows as a JSON array, at most 500 rows, each with the fields below. The list draws one card per row, in the order given. A row the list cannot draw is refused, naming the row by its position, and the list keeps its last good paint.

The row fields

Each row carries the fields of one benefit in the distributor API's benefits list, under the names its schema gives them. The list draws the name, the state and the locked sentence, and passes over the rest, so a row can be handed over unchanged.

The fields of one benefit row
Field	What it carries
`benefitId`	Required. The benefit's id, like "bft_01H8Z2N9P4QX7K3M5A0V8D9T2W". The claim event carries it back.
`name`	Required. The words the benefit's card names it by.
`type`	The benefit's type, one of DISCOUNT_CODE, EXPERIENCE, POINTS, VOUCHER, ACCESS, DIGITAL_COLLECTIBLE or STOCK_REWARD. The distributor API's rows carry it; the list does not draw it.
`delivery`	How the benefit is delivered, one of `CODE`, `POINTS_CREDIT`, `VENUE_REDEMPTION`, `CHAIN_MINT` or `TOKEN_TRANSFER`. The distributor API's rows carry it; the list does not draw it.
`state`	Required. Where the holder stands with the benefit, one of eligible, locked, claimed, redeemed or unavailable. Only an eligible card carries the claim press.
`lockedReason`	Required on a locked row, and only there: the one sentence the holder reads about why the benefit is locked. A row in any other state that carries it is refused.
`sourceMode`	The data mode the row was read in, one of SIMULATED, SANDBOX or LIVE. The distributor API's rows carry it; the list does not draw it.

benefitId: Required. The benefit's id, like "bft_01H8Z2N9P4QX7K3M5A0V8D9T2W". The claim event carries it back.
name: Required. The words the benefit's card names it by.
type: The benefit's type, one of DISCOUNT_CODE, EXPERIENCE, POINTS, VOUCHER, ACCESS, DIGITAL_COLLECTIBLE or STOCK_REWARD. The distributor API's rows carry it; the list does not draw it.
delivery: How the benefit is delivered, one of CODE, POINTS_CREDIT, VENUE_REDEMPTION, CHAIN_MINT or TOKEN_TRANSFER. The distributor API's rows carry it; the list does not draw it.
state: Required. Where the holder stands with the benefit, one of eligible, locked, claimed, redeemed or unavailable. Only an eligible card carries the claim press.
lockedReason: Required on a locked row, and only there: the one sentence the holder reads about why the benefit is locked. A row in any other state that carries it is refused.
sourceMode: The data mode the row was read in, one of SIMULATED, SANDBOX or LIVE. The distributor API's rows carry it; the list does not draw it.

The claim event

A press on an eligible card is your distributor's own action: the list tells your page which benefit was pressed, and your page claims it.

The claim event and its detail
Name	What it carries
`yutai-claim`	Fired once each time the holder presses the claim on an eligible card. It bubbles and crosses the element's shadow root, so a listener on your document hears it. The list writes nothing itself: the claim is your action.
`detail.benefitId`	The pressed row's benefitId, exactly as your benefits attribute gave it.

yutai-claim: Fired once each time the holder presses the claim on an eligible card. It bubbles and crosses the element's shadow root, so a listener on your document hears it. The list writes nothing itself: the claim is your action.
detail.benefitId: The pressed row's benefitId, exactly as your benefits attribute gave it.

Claim listener

document.addEventListener("yutai-claim", (event) => {
  const { benefitId } = event.detail;
  // Claim the benefit through your own server, then give the list its new rows.
});

The claim itself is your own call: the API reference carries the claim calls, the benefits module's claim sheet runs one for the holder, and Errors and limits explains a refusal.