Skip to main content
Deprecation Notice

As of v1.61.0, widgets have been moved into the Immutable Commerce Widget. Please visit the new Commerce Widget page for the latest updates and information.

Setup

This guide will walk you through how to install and setup the Checkout widgets for your application.

Sections

Install Checkout​

The Checkout Widgets can be included in your application by first installing the SDK in one of two different ways:

  1. Install the npm module and import the Checkout SDK
  • or...
  1. Load the SDK via a CDN by pasting a script tag into your application.

The Checkout Widgets will be loaded dynamically as a separate bundle into your application when you create the Checkout instance and call the widgets() function.

Prerequisites​

Node Version 20 or later
Immutable's Typescript SDK requires **Node v20** (Active LTS version) or **higher**. Node v20 can be installed via `nvm`.

To install nvm follow these instructions. Once installed, run:

nvm install --lts
  • (Optional) To enable Code Splitting (importing only the SDK modules you need) there are additional prerequisites.

Install the Immutable SDK​

Run the following command in your project root directory.

npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node
Troubleshooting

The Immutable SDK is still in early development. If experiencing complications, use the following commands to ensure the most recent release of the SDK is correctly installed:

rm -Rf node_modules
npm cache clean --force
npm i

Quickstart​

Checkout widgets are designed to be used on the client-side only. The window and document objects are required.

The following code snippet shows the recommened way to intiaise and create the widgets:

  1. You must create an instance of the Checkout SDK first
  2. We recommend initialising the widgets at the beginning of your application
  3. We recommend creating all of the widgets that you need in your app at the beginning of your application

This ensures that all widgets are correctly synced with the provider once the user connects their wallet.

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

// Create an instance of the Checkout SDK and configure the environment SANDBOX / PRODUCTION
const checkoutSDK = new checkout.Checkout({
  baseConfig: {environment: config.Environment.SANDBOX },
  bridge: { enable: true },
  swap: { enable: true },
  onRamp: { enable: true }
});

export const App = () => {
  useEffect(() => {
    (async () => {
      // Get an instance of the widgets factory to be able to create widgets
      const widgets = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });

      // RECOMMENDED - create all of the widgets once at the start of your application
      // use the created widgets throughout your application to mount and unmount in specific parts of your application
      const connect = widgets.create(checkout.WidgetType.CONNECT);
      const wallet = widgets.create(checkout.WidgetType.WALLET); // you can optionally pass in additional config per widget
      const swap = widgets.create(checkout.WidgetType.SWAP);
      const bridge = widgets.create(checkout.WidgetType.BRIDGE);
      const onramp = widgets.create(checkout.WidgetType.ONRAMP);

      // Mount the wallet widget passing the element id of where to mount the widget
      wallet.mount('wallet');
    })();
  }, []);

  return (<div id="wallet" />);
};

Widget configuration & versioning​

The checkout.widgets() function can be provided config and a version, which can be used to configure the theme and the specific version to use.

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

const checkoutSDK = new checkout.Checkout();

// @ts-ignore
const widgets  = await checkoutSDK.widgets({
  config: { 
    theme: checkout.WidgetTheme.DARK
  },
  version: {
    major: 1,
    minor: 2,
    patch: 3,
  },
});
PropertyDescription
configThe config object can be used to configure the widgets. This is currently used to set the theme.
versionThe Checkout Widgets follow the Semantic Versioning as per the Immutable SDK package. The SDK automatically downloads the latest version of the widgets library. A different version can be optionally provided than the one loaded as part of the NPM package.

Bundle loading​

The Checkout Widgets are built and released with every new Immutable SDK release following the Immutable SDK versioning. Minor patches are automatically applied to ensure continued and seamless improvements to the product for our partners, as our SDK will load the widgets bundle from https://cdn.jsdelivr.net when checkout.widgets() is called. If a specific version is required then the version can be set when calling checkout.widgets().

note

Only minor and patch versions are seamlessly applied to prevent disruptions in your application.

Widget factory​

The checkout.widgets() function returns a widget factory object that can be used to create any widget or update the provider.

MethodParametersDescription
create(type, props)type: the widget type to instantiate
props: the widget configurations and provider to create the widget		To create a specific widget
updateProvider(provider)provider: the Web3Provider object to update all the widgetsTo update the wallet provider. This will be reflected on all created widgets
import { Web3Provider } from "@ethersproject/providers";
import { checkout } from "@imtbl/sdk";

const checkoutSDK = new checkout.Checkout();

// @ts-ignore
const widgets = await checkoutSDK.widgets({config: {theme: checkout.WidgetTheme.DARK}});
// Create a wallet widget using the factory
const wallet = widgets.create(checkout.WidgetType.WALLET);

// @ts-ignore -  Update provider
widgets.updateProvider(new Web3Provider(provider));

Widget interface​

MethodParametersDescription
mount(id, params)id: ID of the DOM element where the widget will be mounted
params: the specific widget parameters		Mount a widget to a DOM reference element
unmount()Unmount a widget and reset parameters
update(props)props: the widget specific properties including configuration and provider to be updatedUpdate the widget configuration
addListener(type, callback)type: the widget specific event name
callback:(data): function to execute when the event is received		Add a listener for a widget event
removeListener(type)type: the widget specific event nameRemoves an event listener for a widget event

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