Deprecation Notice

As of v1.61.0, orchestration events are no longer needed. Please visit the new Commerce Widget page for details.

Orchestrating widgets

Event orchestration is a way to transition from one widget to another by listening to different orchestration events in your application. The Wallet widget provides entrypoints into other widgets and these will need to be connected together to facilitate a seamless transition from the wallet to other widgets.

Sections

Create the Wallet and Swap widgets
Listen to orchestration events
Sample Code

In this step-by-step guide, we will show you how you can transition from Wallet widget to Swap widget using orchestration events.

Create the Wallet and Swap widgets

To get started, make sure to follow the widget setup guide.

Create the wallet and swap widgets, then mount the wallet in your application:

React
JavaScript

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

 // create Checkout SDK
 const checkoutSDK = new checkout.Checkout();

export function App() {
 const [wallet, setWallet] =
 useState<checkout.Widget<typeof checkout.WidgetType.WALLET>>();
 const [swap, setSwap] =
 useState<checkout.Widget<typeof checkout.WidgetType.SWAP>>();
  
 // Initialise widgets, create wallet widget
  useEffect(() => {
    (async () => {
      const widgets = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });
      const wallet = widgets.create(checkout.WidgetType.WALLET)
      const swap = widgets.create(checkout.WidgetType.SWAP)
      setWallet(wallet);
      setSwap(swap);
      wallet.mount("wallet")
    })();
  }, []);

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

<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
      var checkout;
      (async function () {
        checkout = new ImmutableCheckout.Checkout();

        const widgets = await checkout.widgets({
          config: { theme: ImmutableCheckout.WidgetTheme.DARK },
        });

        const wallet = widgets.create(ImmutableCheckout.WidgetType.WALLET);
        const swap = widgets.create(ImmutableCheckout.WidgetType.SWAP);

        wallet.mount('wallet');
      })();
    </script>
  </body>
</html>

Listen to orchestration events

When a user clicks on Swap IMX option in the Wallet widget, an orchestration event is raised. The orchestration event for Swap widget is request-swap.

Assuming you have created a wallet widget called 'wallet' and a swap widget called 'swap'. Add a listener for the orchestration event 'request-swap', then handle it by unmounting the wallet and mounting the swap with parameters

React
JavaScript

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

// @ts-ignore When creating the widget, pass in the configuration
const wallet = widgets.create(checkout.WidgetType.WALLET,{ 
  config: { theme: checkout.WidgetTheme.DARK }
});
// @ts-ignore
const swap = widgets.create(checkout.WidgetType.SWAP,{ 
  config: { theme: checkout.WidgetTheme.DARK }
});

wallet.addListener(checkout.OrchestrationEventType.REQUEST_SWAP, (data: checkout.RequestSwapEvent) => {
  wallet.unmount();
  swap.mount('swap', { fromTokenAddress: data.fromTokenAddress })
})

wallet.addListener('request-swap', (data) => {
  wallet.unmount();
  swap.mount('swap', {fromContractAddress: data.fromTokenAddress})
})

Once the event is raised and handled, the Swap widget will open with the selected token pre-populated for swap.

Sample Code

When a user clicks on Swap IMX option in the Wallet widget, an orchestration event is raised. The orchestration event for Swap widget is request-swap.

React
JavaScript

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

 // create Checkout SDK
 const checkoutSDK = new checkout.Checkout();

export function App() {
 const [wallet, setWallet] =
 useState<checkout.Widget<typeof checkout.WidgetType.WALLET>>();
 const [swap, setSwap] =
 useState<checkout.Widget<typeof checkout.WidgetType.SWAP>>();
  
 // Initialise widgets, create wallet widget
  useEffect(() => {
    (async () => {
      const widgets = await checkoutSDK.widgets({
        config: { theme: checkout.WidgetTheme.DARK },
      });
      const wallet = widgets.create(checkout.WidgetType.WALLET)
      const swap = widgets.create(checkout.WidgetType.SWAP)
      setWallet(wallet);
      setSwap(swap);   
    })();
  }, []);

  // mount wallet widget and add event listeners
  useEffect(() => {
    if(!wallet || !swap) return;

    wallet.mount("wallet");
    
    wallet.addListener(checkout.WalletEventType.CLOSE_WIDGET, () => {
      wallet.unmount();
    });

    // Add listener for orchestrating wallet with swap
    wallet.addListener(checkout.OrchestrationEventType.REQUEST_SWAP, (data: checkout.RequestSwapEvent) => {
      wallet.unmount();
      swap.mount('swap', { fromTokenAddress: data.fromTokenAddress })
    })

  }, [wallet, swap])

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

<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>
    <div id="swap"></div>
    <script>
      // Initialize Checkout SDK
      var checkout;
      (async function () {
        checkout = new ImmutableCheckout.Checkout();

        const widgets = await checkout.widgets({
          config: { theme: ImmutableCheckout.WidgetTheme.DARK },
        });

        const wallet = widgets.create(ImmutableCheckout.WidgetType.WALLET);
        const swap = widgets.create(ImmutableCheckout.WidgetType.SWAP);

        wallet.mount('wallet');

        wallet.addListener('request-swap', (data) => {
          wallet.unmount();
          swap.mount('swap', { fromTokenAddress: data.fromTokenAddress })
        })
      })();
    </script>
  </body>
</html>

Once the event is raised and listened to, the Swap widget will open with the selected token pre-populated for swap.

Orchestrating widgets

Create the Wallet and Swap widgets​

Listen to orchestration events​

Sample Code​

Create the Wallet and Swap widgets

Listen to orchestration events

Sample Code