Skip to main content

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.

import { useEffect } from 'react';
import { checkout } from '@imtbl/sdk';

// Create a Checkout SDK instance
const checkoutSDK = new checkout.Checkout();

export function App() {
  // Initialise the Commerce Widget
  useEffect(() => {
    (async () => {
      // Create a factory
      const factory = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK, language: 'en' },
      });

      // Create a widget
      const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE);

      // Mount a SALE flow, optionally pass any SaleWidgetParams
      widget.mount('mount-point', {
        flow: checkout.CommerceFlowType.SALE,
      });
    })();
  }, []);

  return <div id="mount-point" />;
}

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.

PropertyTypeDescription
flowCommerceFlowType.SALEThe flow type to be used.
environmentIdstringThe Environment Id created in Immutable Hub*.
itemsSaleItem[]The list of items for sale* (max. length 350).
collectionNamestringThe name of the NFT Collection*.
excludePaymentTypesSalePaymentTypesThe list of payment types to be disabled.
excludeFiatCurrenciesstring[]List of fiat currencies that should be disabled when paying with card, ISO 4217 formatted.
preferredCurrencystringPreferred currency, overrides base currency from configuration
languageWidgetLanguageThe language to use inside the widget. ie: en, kr, jp, zh
import { checkout } from '@imtbl/sdk';

// @ts-ignore
const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE, {
  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,
// set flow to SALE and pass in the parameters to use
widget.mount('mount-point', {
  flow: checkout.CommerceFlowType.SALE,
  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';

// When creating the widget, pass in the configuration
// @ts-ignore
const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE, {
  config: {
    language: 'en',
    theme: checkout.WidgetTheme.DARK,

    // sale widget configuration options
    SALE: {},
  },
});

// Update the widget config by calling update()
// @ts-ignore
widget.update({
  config: {
    theme: checkout.WidgetTheme.LIGHT,
    SALE: {},
  },
});

For more information on the configurations across all the Commerce Widgets (e.g. theme) review the Configuration section in our Setup page.

Events​

The Commerce Widget emit events events when critical actions have been taken by the user or key states have been reached. Below is a table outlining the key events associated with a SALE flow.

Event TypeDescriptionEvent Payload
CommerceEventType.CLOSEThe user clicked the close button on the widget. This should usually be wired up to call the widget's unmount() function.
CommerceEventType.SUCCESSThe user has completed the flow successfully.CommerceSuccessEvent
CommerceEventType.FAILUREThere has been an error in the flow.CommerceFailureEvent
CommerceEventType.USER_ACTIONThe user has taken an action in the flow.CommerceUserActionEvent
import { checkout } from '@imtbl/sdk';

//@ts-ignore
const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE, {
  config: { theme: checkout.WidgetTheme.DARK },
});

// Add event listeners for the SALE flow

widget.addListener(
  checkout.CommerceEventType.SUCCESS,
  (payload: checkout.CommerceSuccessEvent) => {
    // narrow the event to a successfull sale event
    if (payload.type === checkout.CommerceSuccessEventType.SALE_SUCCESS) {
      const { transactionHash } = payload.data;
      console.log('successfull sale', transactionHash);
    } if (payload.type === checkout.CommerceSuccessEventType.SALE_TRANSACTION_SUCCESS) {
      const { paymentMethod, transactions } = payload.data;
      console.log('successfull sale transaction', paymentMethod, transactions);
    }
  }
);

widget.addListener(
  checkout.CommerceEventType.FAILURE,
  (payload: checkout.CommerceFailureEvent) => {
    // narrow the event to a failed sale event
    if (payload.type === checkout.CommerceFailureEventType.SALE_FAILED) {
      const { reason, timestamp } = payload.data;
      console.log('sale failed', reason, timestamp);
    }
  }
);

widget.addListener(
  checkout.CommerceEventType.USER_ACTION,
  (payload: checkout.CommerceUserActionEvent) => {
    if (payload.type === checkout.CommerceUserActionEventType.PAYMENT_METHOD_SELECTED) {
      const { paymentMethod } = payload.data;
      console.log('Payment method selected:', paymentMethod);
    }
  }
);

widget.addListener(checkout.CommerceEventType.CLOSE, () => {
  widget.unmount();
  console.log('widget closed');
});

// Remove event listeners for the  SALE  flow

widget.removeListener(checkout.CommerceEventType.SUCCESS);
widget.removeListener(checkout.CommerceEventType.FAILURE);
widget.removeListener(checkout.CommerceEventType.USER_ACTION);
widget.removeListener(checkout.CommerceEventType.CLOSE);

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 [widget, setWidget] =
    useState<checkout.Widget<typeof checkout.WidgetType.IMMUTABLE_COMMERCE>>();

  // Initialise widget and mount a SALE flow
  useEffect(() => {
    (async () => {
      const widgets = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });
      const checkoutWidget = widgets.create(checkout.WidgetType.IMMUTABLE_COMMERCE);
      setWidget(checkoutWidget);
    })();
  }, []);

  // mount primary sales widget and add event listeners
  useEffect(() => {
    if (!widget) return;

    const items = [
      {
        productId: 'x1',
        qty: 1,
        name: 'super dog',
        image: 'http://image.png',
        description: 'Super dog description',
      },
    ];

    widget.mount('mount-point', {
      flow: checkout.CommerceFlowType.SALE,
      language: 'en',
      environmentId: 'abcd-1234',
      collectionName: 'super pets',
      items: items,
    });

    widget.addListener(
      checkout.CommerceEventType.SUCCESS,
      (payload: checkout.CommerceSuccessEvent) => {
        // narrow the event to a successfull sale event
        if (payload.type === checkout.CommerceSuccessEventType.SALE_SUCCESS) {
          const { transactionHash } = payload.data;
          console.log('successfull sale', transactionHash);
        } if (payload.type === checkout.CommerceSuccessEventType.SALE_TRANSACTION_SUCCESS) {
          const { paymentMethod, transactions } = payload.data;
          console.log('successfull sale transaction', paymentMethod, transactions);
        }
      }
    );

    widget.addListener(
      checkout.CommerceEventType.FAILURE,
      (payload: checkout.CommerceFailureEvent) => {
        // narrow the event to a failed sale event
        if (payload.type === checkout.CommerceFailureEventType.SALE_FAILED) {
          const { reason, timestamp } = payload.data;
          console.log('sale failed', reason, timestamp);
        }
      }
    );

    widget.addListener(
      checkout.CommerceEventType.USER_ACTION,
      (payload: checkout.CommerceUserActionEvent) => {
        if (payload.type === checkout.CommerceUserActionEventType.PAYMENT_METHOD_SELECTED) {
          const { paymentMethod } = payload.data;
          console.log('Payment method selected:', paymentMethod);
        }
      }
    );

    widget.addListener(checkout.CommerceEventType.CLOSE, () => {
      widget.unmount();
      console.log('widget closed');
    });

    // clean up event listeners
    return () => {
      widget.removeListener(checkout.CommerceEventType.SUCCESS);
      widget.removeListener(checkout.CommerceEventType.CLOSE);
      widget.removeListener(checkout.CommerceEventType.FAILURE);
      widget.removeListener(checkout.CommerceEventType.USER_ACTION);
    };
  }, [widget]);

  return <div id="mount-point" />;
}

Disable Payment types​

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

import { checkout } from '@imtbl/sdk';

// create a sale widget
// @ts-ignore
const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE, {
  config: {
    language: 'en',
    theme: checkout.WidgetTheme.DARK,

    // sale widget configuration options
    SALE: {
      hideExcludedPaymentTypes: true
    },
  },
});

widget.mount('mount-point', {
  language: 'en',
  environmentId: 'abcd-1234',
  collectionName: 'super pets',
  items: [],

  // mount the widget without card payments
  excludePaymentTypes: [
    checkout.SalePaymentTypes.DEBIT,
    checkout.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 } from '@imtbl/sdk';

// create a sale widget
// @ts-ignore
const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE, {
  config: {
    language: 'en',
    theme: checkout.WidgetTheme.DARK,

    // sale widget configuration options
    SALE: {},
  },
});

// 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
widget.mount('mount-point', {
  flow: checkout.CommerceFlowType.SALE,
  language: 'en',
  environmentId: 'abcd-1234',
  collectionName: 'super pets',
  items,
  // if more than 1 sku disable card payments
  excludePaymentTypes: items.length > 1 ? [
    checkout.SalePaymentTypes.DEBIT,
    checkout.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.

IMX Whitepaper • IMX Tokenomics • Block Explorer • Careers • Contact Us