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.
Install Checkout
The Checkout Widgets can be included in your application by first installing the SDK in one of two different ways:
- Install the npm module and import the Checkout SDK
- or...
- 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.
- npm module
- JavaScript via CDN
Prerequisites
Node Version 20 or later
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
- yarn
npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node
yarn add --dev @imtbl/sdk
# if necessary, install dependencies
yarn add --dev typescript ts-node
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:
- npm
- yarn
rm -Rf node_modules
npm cache clean --force
npm i
rm -Rf node_modules
yarn cache clean
yarn install
To add the SDK to an application using the CDN the following script can be placed inside the head tag.
<script src="https://cdn.jsdelivr.net/npm/@imtbl/sdk/dist/browser/checkout/sdk.js"></script>
Quickstart
- React
- JavaScript
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:
- You must create an instance of the Checkout SDK first
- We recommend initialising the widgets at the beginning of your application
- 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" />);
};
The following codeblock demonstrates how to use the widgets in the HTML file of an application by accessing the SDK via the CDN.
- You must create an instance of the Checkout SDK first
- We recommend initialising the widgets at the beginning of your application
- 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.
<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="wallet"></div>
<script>
// Initialize Checkout SDK
const checkout = new ImmutableCheckout.Checkout();
(async function () {
const widgets = await checkout.widgets({
config: { theme: ImmutableCheckout.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(ImmutableCheckout.WidgetType.CONNECT);
const wallet = widgets.create(ImmutableCheckout.WidgetType.WALLET);
const swap = widgets.create(ImmutableCheckout.WidgetType.SWAP);
const bridge = widgets.create(ImmutableCheckout.WidgetType.BRIDGE);
const onramp = widgets.create(ImmutableCheckout.WidgetType.ONRAMP);
// Mount the wallet widget at the element id provided
wallet.mount('wallet');
})();
</script>
</body>
</html>
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,
},
});
Property | Description |
---|---|
config | The config object can be used to configure the widgets. This is currently used to set the theme. |
version | The 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()
.
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.
Method | Parameters | Description |
---|---|---|
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 widgets | To update the wallet provider. This will be reflected on all created widgets |
- React
- JavaScript
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));
const widget = await checkout.widgets();
// Create a wallet widget using the factory
const wallet = widgets.create(ImmutableCheckout.WidgetType.WALLET);
// Update provider
widgets.updateProvider(new Web3Provider(provider));
Widget interface
Method | Parameters | Description |
---|---|---|
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 updated | Update 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 name | Removes an event listener for a widget event |