Skip to main content

Getting started​

💡Primary Sales Widget Enablement
The Primary Sales Widget is currently in its closed Beta release phase and we anticipate making it available publicly soon.

To gain access to the Primary Sales Widget, please complete the following form and our team will be in contact.

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.

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" />);
}

Parameters​

The mount() expects the following parameters to be passed into the widget.

Widget parameters

Parameters are treated as transient and will be reset after the widget is unmounted.

PropertyDescription
environmentIdThe Environment Id created in Immutable Hub*.
collectionNameThe name of the NFT Collection*.
itemsThe list of items for sale* (max. length 350).
excludePaymentTypesThe list of payment types to be disabled.
excludeFiatCurrenciesList of fiat currencies that should be disabled when paying with card, ISO 4217 formatted.
preferredCurrencyPreferred currency, overrides base currency from configuration
languageThe language to use inside the widget. ie: en, kr, jp, zh
walletProviderNameThe wallet provider name to default to if no web3Provider is passed.
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,
});

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.

Widget parameters
`Configuration` will persist after the widget is unmounted. You can always update a widget's configuration later by calling the `update()` method.
PropertyDescription
waitFulfillmentSettlementsWhether or not wait until each transaction has been confirmed in the blockchain
hideExcludedPaymentTypesWhether to show or hide the payment types disabled by excludePaymentTypes param
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}});

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 TypeDescriptionEvent Payload
SaleEventType.SUCCESSThe primary sales flow completed successfully.SaleSuccess
SaleEventType.FAILUREThere was a problem executing a primary sale transaction or the flow completed unsuccessfully.SaleFailed
SaleEventType.CLOSE_WIDGETThe user clicked the close button on the widget. This should usually be wired up to call the widget's unmount() function.
SaleEventType.TRANSACTION_SUCCESSOne or more transaction were executed successfully on-chain as part of the primary sales flow.SaleTransactionSuccess
SaleEventType.PAYMENT_METHODThe user selected a payment methodSalePaymentMethod
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);

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.

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" />;
}

Disable Payment types​

Select which payment types are available to the buyer by passing in excludePaymentTypes parameter.


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,
  ],
});

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.

Pay with coins only

Due to current limitations with the card payment provider, multiple items can only be purchased with coins.


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,
});
Transaction Limits

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.