Skip to main content

Setup

This guide will walk you through how to install and setup the Immutable Commerce Widget in your application.

Sections

Install Checkout​

The Immutable Commerce Widget 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 Immutable Commerce Widget will be loaded dynamically as a separate bundle into your application when you create the Checkout SDK instance and call the widgets() factory 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​

The Commerce Widget is 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 widget:

  1. You must create an instance of the Checkout SDK first
  2. We recommend creating and initialising the Widget at the beginning of your application

This ensures the Widget is 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 factory to be able to create the Widget
      const factory = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });

      // RECOMMENDED: Create the Commerce Widget once at the start of your application.
      const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE, {
        // provider: web3Provider // pass in a Web3Provider if already connected to a wallet
        config: {
          // pass in the configuration for each flow
          WALLET: {
            showNetworkMenu: true,
            showDisconnectButton: true,
          }
        }
      });

      // Mount the Commerce Widget at the element id provided
      // You can mount and unmount this widget in specific parts of your application as needed.
      widget.mount('mount-point', {
        // the flow to be used
        flow: checkout.CommerceFlowType.CONNECT,
        // ... other params, will depend on the selected flow
      });
    })();
  }, []);

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

Configuration & versioning​

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

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

const checkoutSDK = new checkout.Checkout();

// @ts-ignore
const factory  = await checkoutSDK.widgets({
  config: { 
    language: 'en',
    theme: checkout.WidgetTheme.DARK,
  },
  version: {
    major: 1,
    minor: 2,
    patch: 3,
  },
});
PropertyDescription
configThe config object can be used to configure the Immutable Commerce Widget. This is currently used to set the theme, language, and enable certain features.
versionThe SDK automatically downloads the latest compatible version of the library. However, optionally you can pass the desired version of widgets to load.

Bundle loading​

The Immutable Commerce Widget is built and released with every new Immutable SDK release following the Immutable SDK versioning.

Most 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 the factory function checkout.widgets() is called.

When a breaking change is required in the widget bundle, updates will pause until the package is manually upgraded.

note

Only non breaking changes 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, update config and provider.

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

const checkoutSDK = new checkout.Checkout();

// Get an instance of the factory to be able to create the Widget
// @ts-ignore
const factory = await checkoutSDK.widgets({
  config: {
    language: 'en',
    theme: checkout.WidgetTheme.DARK,
  },
});

// Create a Commerce Widget using the factory
// @ts-ignore
const widget = factory.create(checkout.WidgetType.IMMUTABLE_COMMERCE, {
  // @ts-ignore
  // if application is already connected to a wallet
  provider: web3Provider,

  // optional configuration by flow
  config: {
    WALLET: {
      // showDisconnectButton: true,
      // showNetworkMenu: true,
    },
    SALE: {
      // hideExcludedPaymentTypes: true,
      // waitFulfillmentSettlements: true,
    },
    // SWAP: {},
    // ONRAMP: {},
    // CONNECT: {},
    // BRIDGE: {},
    // ADD_FUNDS: {},
  },
  // @ts-ignore
});


// Use this at anytime to update the provider used by the widget
// after the widget was created.
// @ts-ignore
factory.updateProvider(new Web3Provider(provider));

The create(type, props)

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

Widget Events​

The Immutable Commerce Widget emits events when critical actions are taken by the user or key states are reached. Subscribing to these events allows your application to respond appropriately to changes in the widget's state.

Event TypeDescriptionEvent Payload
CommerceEventType.INITIALISEDThe widget has been initialised.
CommerceEventType.PROVIDER_UPDATEDThe provider has been updated.CommerceProviderUpdatedEvent
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.DISCONNECTEDThe user has disconnected their wallet.
CommerceEventType.USER_ACTIONThe user has taken an action in the flow.CommerceUserActionEvent

For detailed information on the events specific to each flow, please refer to the respective flow's documentation page.

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