Getting started
Once you have completed the widget setup guide, use the WidgetsFactory to create a Primary Sales widget.
In order to mount the widget, call the mount()
function and pass in the id
attribute of the target element you wish to mount it to.
- React
- JavaScript
import { useEffect } from 'react';
import { checkout } from '@imtbl/sdk';
// create Checkout SDK
const checkoutSDK = new checkout.Checkout();
export function App() {
// Initialise widgets, create primary sales widget and mount
useEffect(() => {
(async () => {
const widgets = await checkoutSDK.widgets({
config: { theme: checkout.WidgetTheme.DARK },
});
const saleWidget = widgets.create(checkout.WidgetType.SALE)
saleWidget.mount("primary-sales");
})();
}, []);
return (<div id="primary-sales" />);
}
<html>
<head>
<!-- Load the SDK from jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/@imtbl/sdk/dist/browser/checkout/sdk.js"></script>
</head>
<body>
<div id="primary-sales"></div>
<script>
// Initialize Checkout SDK
var checkout;
(async function () {
checkout = new ImmutableCheckout.Checkout();
const widgets = await checkout.widgets({
config: { theme: ImmutableCheckout.WidgetTheme.DARK },
});
const saleWidget = widgets.create(ImmutableCheckout.WidgetType.SALE);
saleWidget.mount('primary-sales');
})();
</script>
</body>
</html>
Parameters
The mount()
expects the following parameters to be passed into the widget.
Parameters are treated as transient and will be reset after the widget is unmounted.
Property | Description |
---|---|
environmentId | The Environment Id created in Immutable Hub*. |
collectionName | The name of the NFT Collection*. |
items | The list of items for sale* (max. length 350). |
excludePaymentTypes | The list of payment types to be disabled. |
excludeFiatCurrencies | List of fiat currencies that should be disabled when paying with card, ISO 4217 formatted. |
preferredCurrency | Preferred currency, overrides base currency from configuration |
language | The language to use inside the widget. ie: en, kr, jp, zh |
- React
- JavaScript
import { checkout } from '@imtbl/sdk';
// @ts-ignore
const saleWidget = widgets.create(checkout.WidgetType.SALE, {
config: { theme: checkout.WidgetTheme.DARK },
});
const items = [
{
productId: 'x1',
qty: 1,
name: 'super dog',
image: 'http://image.png',
description: 'Super dog description',
},
];
// When calling the mount function, pass in the parameters to use
saleWidget.mount('primary-sales', {
language: 'en',
environmentId: 'abcd-1234',
collectionName: 'super pets',
items: items,
});
const items = [
{
productId: 'x1',
qty: 1,
name: 'super dog',
image: 'http://image.png',
description: 'Super dog description',
},
];
// When calling the mount function, pass in the parameters to use
saleWidget.mount('primary-sales', {
language: 'en',
environmentId: 'abcd-1234',
collectionName: 'super pets',
items: items,
});
Configuration
When you first create the widget, you can pass an optional configuration object to set it up. For example, passing in the theme will create the widget with that theme. If this is not passed the configuration will be set by default.
Property | Description |
---|---|
waitFulfillmentSettlements | Whether or not wait until each transaction has been confirmed in the blockchain |
hideExcludedPaymentTypes | Whether to show or hide the payment types disabled by excludePaymentTypes param |
- React
- JavaScript
import { checkout } from "@imtbl/sdk";
//@ts-ignore When creating the widget, pass in the configuration
const saleWidget = widgets.create(checkout.WidgetType.SALE,
{ config: { theme: checkout.WidgetTheme.DARK }}
);
// Update the widget config by calling update()
saleWidget.update({config: {theme: checkout.WidgetTheme.LIGHT}});
// When creating the widget, pass in the configuration
const saleWidget = widgets.create(ImmutableCheckout.WidgetType.SALE,
{ config: { theme: checkout.WidgetTheme.DARK }}
);
// Update the widget config by calling update()
saleWidget.update({config: { theme: ImmutableCheckout.WidgetTheme.LIGHT }});
For more information on the configurations across all the Checkout Widgets (e.g. theme) review the Configuration section in our Setup page.
Events
Primary Sales widget events are emitted when critical actions have been taken by the user or key states have been reached. Below is a table of the possible events for the Primary Sales widget.
Event Type | Description | Event Payload |
---|---|---|
SaleEventType.SUCCESS | The primary sales flow completed successfully. | SaleSuccess |
SaleEventType.FAILURE | There was a problem executing a primary sale transaction or the flow completed unsuccessfully. | SaleFailed |
SaleEventType.CLOSE_WIDGET | The user clicked the close button on the widget. This should usually be wired up to call the widget's unmount() function. | |
SaleEventType.TRANSACTION_SUCCESS | One or more transaction were executed successfully on-chain as part of the primary sales flow. This is sent when a user is paying with tokens only (not fiat). | SaleTransactionSuccess |
SaleEventType.PAYMENT_METHOD | The user selected a payment method | SalePaymentMethod |
- React
- JavaScript
import { checkout } from "@imtbl/sdk";
// @ts-ignore
const saleWidget = widgets.create(checkout.WidgetType.SALE,
{ config: { theme: checkout.WidgetTheme.DARK }}
);
// add event listeners for the primary sales widget
saleWidget.addListener(checkout.SaleEventType.SUCCESS, (data: checkout.SaleSuccess) => {
console.log("success", data);
});
saleWidget.addListener(checkout.SaleEventType.FAILURE, (data: checkout.SaleFailed) => {
console.log("failure", data);
});
saleWidget.addListener(checkout.SaleEventType.TRANSACTION_SUCCESS, (data: checkout.SaleTransactionSuccess) => {
console.log('tx success', data);
});
saleWidget.addListener(checkout.SaleEventType.PAYMENT_METHOD, (data: checkout.SalePaymentMethod) => {
console.log('payment method selected', data);
});
saleWidget.addListener(checkout.SaleEventType.CLOSE_WIDGET, () => {
saleWidget.unmount();
});
// remove event listeners for the primary sales widget
saleWidget.removeListener(checkout.SaleEventType.SUCCESS);
saleWidget.removeListener(checkout.SaleEventType.FAILURE);
saleWidget.removeListener(checkout.SaleEventType.TRANSACTION_SUCCESS);
saleWidget.removeListener(checkout.SaleEventType.PAYMENT_METHOD);
saleWidget.removeListener(checkout.SaleEventType.CLOSE_WIDGET);
const saleWidget = widgets.create(ImmutableCheckout.WidgetType.SALE);
// add event listeners for the primary sales widget
saleWidget.addListener(ImmutableCheckout.SaleEventType.SUCCESS, (data) => {
console.log('success', data);
});
saleWidget.addListener(ImmutableCheckout.SaleEventType.FAILURE, (data) => {
console.log('failure', data);
});
saleWidget.addListener(ImmutableCheckout.SaleEventType.TRANSACTION_SUCCESS, (data) => {
console.log('tx success', data);
});
saleWidget.addListener(ImmutableCheckout.SaleEventType.PAYMENT_METHOD, (data) => {
console.log('payment method selected', data);
});
saleWidget.addListener(ImmutableCheckout.SaleEventType.CLOSE_WIDGET, (data) => {
console.log('close', data);
});
// remove event listeners for the primary sales widget
saleWidget.removeListener(ImmutableCheckout.SaleEventType.SUCCESS);
saleWidget.removeListener(ImmutableCheckout.SaleEventType.FAILURE);
saleWidget.removeListener(ImmutableCheckout.SaleEventType.TRANSACTION_SUCCESS);
saleWidget.removeListener(ImmutableCheckout.SaleEventType.PAYMENT_METHOD);
saleWidget.removeListener(ImmutableCheckout.SaleEventType.CLOSE_WIDGET);
Code Examples
This code examples gives you a good starting point for integrating the primary sale widget.
Basic setup
Instantiate sale widget and listen to events.
- React
- JavaScript
import { useEffect, useState } from 'react';
import { checkout } from '@imtbl/sdk';
// create Checkout SDK
const checkoutSDK = new checkout.Checkout();
export function App() {
const [saleWidget, setSale] =
useState<checkout.Widget<typeof checkout.WidgetType.SALE>>();
// Initialise widgets, create primary sales widget
useEffect(() => {
(async () => {
const widgets = await checkoutSDK.widgets({
config: { theme: checkout.WidgetTheme.DARK },
});
const saleWidget = widgets.create(checkout.WidgetType.SALE, {
config: { theme: checkout.WidgetTheme.DARK },
});
setSale(saleWidget);
})();
}, []);
// mount primary sales widget and add event listeners
useEffect(() => {
if (!saleWidget) return;
const items = [
{
productId: 'x1',
qty: 1,
name: 'super dog',
image: 'http://image.png',
description: 'Super dog description',
},
];
saleWidget.mount('primary-sales', {
language: 'en',
environmentId: 'abcd-1234',
collectionName: 'super pets',
items: items,
});
saleWidget.addListener(
checkout.SaleEventType.SUCCESS,
(data: checkout.SaleSuccess) => {
console.log('success', data);
}
);
saleWidget.addListener(
checkout.SaleEventType.FAILURE,
(data: checkout.SaleFailed) => {
console.log('failure', data);
}
);
saleWidget.addListener(
checkout.SaleEventType.TRANSACTION_SUCCESS,
(data: checkout.SaleTransactionSuccess) => {
console.log('tx success', data);
}
);
saleWidget.addListener(
checkout.SaleEventType.PAYMENT_METHOD,
(data: checkout.SalePaymentMethod) => {
console.log('payment method selected', data);
}
);
saleWidget.addListener(checkout.SaleEventType.CLOSE_WIDGET, () => {
saleWidget.unmount();
});
}, [saleWidget]);
return <div id="primary-sales" />;
}
<html>
<head>
<!-- Load the SDK from jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/@imtbl/sdk/dist/browser/checkout/sdk.js"></script>
</head>
<body>
<div id="primary-sales"></div>
<script>
// Initialize Checkout SDK
var checkout;
(async function () {
checkout = new ImmutableCheckout.Checkout();
const widgets = await checkout.widgets({
config: { theme: ImmutableCheckout.WidgetTheme.DARK },
});
const saleWidget = widgets.create(ImmutableCheckout.WidgetType.SALE, {
config: { theme: ImmutableCheckout.WidgetTheme.DARK },
});
const items = [
{
productId: 'x1',
qty: 1,
name: 'super dog',
image: 'http://image.png',
description: 'Super dog description',
},
];
saleWidget.mount('primary-sales', {
language: 'en',
environmentId: 'abcd-1234',
collectionName: 'super pets',
items: items,
});
saleWidget.addListener(
ImmutableCheckout.SaleEventType.SUCCESS,
(data) => {
console.log('success', data);
}
);
saleWidget.addListener(
ImmutableCheckout.SaleEventType.FAILURE,
(data) => {
console.log('failure', data);
}
);
saleWidget.addListener(
ImmutableCheckout.SaleEventType.TRANSACTION_SUCCESS,
(data) => {
console.log('tx success', data);
}
);
saleWidget.addListener(
ImmutableCheckout.SaleEventType.PAYMENT_METHOD,
(data) => {
console.log('payment method selected', data);
}
);
saleWidget.addListener(
ImmutableCheckout.SaleEventType.CLOSE_WIDGET,
() => {
saleWidget.unmount();
}
);
})();
</script>
</body>
</html>
Disable Payment types
Select which payment types are available to the buyer by passing in excludePaymentTypes
parameter.
- React
- JavaScript
import { checkout as CheckoutSDK } from '@imtbl/sdk';
// @ts-ignore
const saleWidget = factory.create(CheckoutSDK.WidgetType.SALE, {
config: {
// hide excluded payment types
hideExcludedPaymentTypes: true,
},
});
saleWidget.mount('primary-sales', {
language: 'en',
environmentId: 'abcd-1234',
collectionName: 'super pets',
items: [],
// mount the widget without card payments
excludePaymentTypes: [
CheckoutSDK.SalePaymentTypes.DEBIT,
CheckoutSDK.SalePaymentTypes.CREDIT,
],
});
const saleWidget = factory.create(CheckoutSDK.WidgetType.SALE, {
config: {
// hide excluded payment types
hideExcludedPaymentTypes: true,
},
});
saleWidget.mount('primary-sales', {
language: 'en',
environmentId: 'abcd-1234',
collectionName: 'super pets',
items: [],
// mount the widget without card payments
excludePaymentTypes: [
CheckoutSDK.SalePaymentTypes.DEBIT,
CheckoutSDK.SalePaymentTypes.CREDIT,
],
});
Purchase Multiple Items
You can provide multiple items
up to the recommended transaction limit.
Each entry in the items
array should be a unique SKU. The field qty
is used to specify how many of the item should be minted.
Due to current limitations with the card payment provider, multiple items
can only be purchased with coins.
:::
- React
- JavaScript
import { checkout as CheckoutSDK } from '@imtbl/sdk';
// create a sale widget
// @ts-ignore
const saleWidget = factory.create(CheckoutSDK.WidgetType.SALE, {
config: {
// hide excluded payment types
hideExcludedPaymentTypes: true,
},
});
// define multiple skus to be purchased
const items = [
{
productId: 'sku-dog',
qty: 2,
name: 'super dog',
image: 'http://image.png',
description: 'Loyal dog',
},
{
productId: 'sku-cat',
qty: 1,
name: 'super cat',
image: 'http://image.png',
description: 'Fancy cat',
},
];
// mount the widget without card pay
saleWidget.mount('primary-sales', {
language: 'en',
environmentId: 'abcd-1234',
collectionName: 'super pets',
items,
// if more than 1 sku disable card payments
excludePaymentTypes: items.length > 1 ? [
CheckoutSDK.SalePaymentTypes.DEBIT,
CheckoutSDK.SalePaymentTypes.CREDIT,
] : undefined,
});
// create a sale widget
const saleWidget = factory.create(CheckoutSDK.WidgetType.SALE, {
config: {
// hide excluded payment types
hideExcludedPaymentTypes: true,
},
});
// define multiple skus to be purchased
const items = [
{
productId: 'sku-dog',
qty: 2,
name: 'super dog',
image: 'http://image.png',
description: 'Loyal dog',
},
{
productId: 'sku-cat',
qty: 1,
name: 'super cat',
image: 'http://image.png',
description: 'Fancy cat',
},
];
// mount the widget without card payments
saleWidget.mount('primary-sales', {
language: 'en',
environmentId: 'abcd-1234',
collectionName: 'super pets',
items,
// if more than 1 sku disable card payments
excludePaymentTypes: items.length > 1 ? [
CheckoutSDK.SalePaymentTypes.DEBIT,
CheckoutSDK.SalePaymentTypes.CREDIT,
] : undefined,
});
transaction limit is checked against the total items quantity to be minted.
This is the sum of qty
in the items
array. For this example total quantity will be 2 dog + 1 cat = 3
items minted.