Dymension Connect

Dymension Connect is a powerful tool that enables seamless asset deposits from various blockchain networks into your RollApp. Leveraging eIBC with Dymension, this framework-agnostic widget is compatible with React, Vue, Angular, or vanilla JavaScript projects.

This section provides a comprehensive guide on integrating the Dymension Connect widget into your application. By following this guide, you'll learn how to:

1. Configure the widget's environment
2. Embed the widget into your application's UI
3. Establish communication between your application and the widget

For the complete source code, visit our GitHub repository.

Integration Steps

1. Configure Environment

Define the connection URL and network ID for your widget instance:

const DYMENSION_CONNECT_URL = "https://portal.dymension.xyz/";
const DYMENSION_CONNECT_NETWORK_ID = "rollapp_1234-1";

Step 2: Embed the Widget

Embed the Dymension Connect Widget into your application using an iframe. This setup enables your users to interact with the widget directly from your UI.

<iframe
    ref={iframeRef}
    onLoad={initModal}
    style={{ display: dymensionConnectOpen ? "block" : "none" }}
    allow="clipboard-read; clipboard-write"
    title="dymension-connect"
    className="dymension-connect-iframe"
    src={`${DYMENSION_CONNECT_URL}/connect?networkId=${DYMENSION_CONNECT_NETWORK_ID}`}
/>

Step 3: Communicate with the Widget

Maximize the utility and adaptability of the Dymension Connect Widget within your application by leveraging direct messaging. This advanced method enables real-time communication with the widget's iframe, allowing you to dynamically adjust its appearance and behavior to suit user interactions and your application's styling needs. Utilize the postMessage API to send messages from your application to the widget, enhancing user experience through customization and control.

const sendMessage = useCallback((message) => {
    iframeRef.current?.contentWindow?.postMessage(
        message,
        DYMENSION_CONNECT_URL
    );
}, []);

sendMessage({
    type: "stylesChange",
    styles: {
        "--control-color-normal": "rgb(31 35 30)",
        "--background-color": "rgb(42 59 42)",
        "--background-color-secondary": "rgb(63 78 63)",
    },
});
sendMessage({ type: "menuAlignChange", align: "center" });
sendMessage({ type: "modalTypeChange", modalType: "wallet-selector" });

Optional messages that can be sent to the widget:

• triggerBoundingRectChange: Adjusts the widget's position by specifying the trigger element's bounding rectangle.

  sendMessage({ type: 'triggerBoundingRectChange', rect: /* DOMRect object */ });
• stylesChange: Modifies the widget's styles to better match your application's theme.

  sendMessage({
      type: "stylesChange",
      styles: {
          "--control-color-normal": "yourValue",
          "--background-color": "yourValue",
          "--background-color-secondary": "yourValue",
          // Add more custom style properties as needed
      },
  });
• modalTypeChange: Switches the widget's modal type, allowing control over the displayed content (e.g., switching between wallet selector and account details).

  sendMessage({
      type: "modalTypeChange",
      modalType: "wallet-selector" /* Or 'account' */,
  });
• menuAlignChange: Alters the alignment of the widget's menu relative to the trigger element, enhancing layout consistency and visual harmony.

  sendMessage({
      type: "menuAlignChange",
      align: "center" /* Or 'left', 'right' */,
  });

Step 4: Listen for Messages from the Widget

To create a fully interactive experience, your application should listen for messages from the Dymension Connect Widget. This allows your app to react to user actions within the widget, such as connecting or disconnecting a wallet. Implement the listener within a useEffect to handle these messages appropriately:

useEffect(() => {
    const handleMessage = (event) => {
        if (event.origin !== DYMENSION_CONNECT_URL) {
            return;
        }
        switch (event.data.type) {
            case "ready":
                setDymensionConnectReady(true);
                break;
            case "close":
                setDymensionConnectOpen(false);
                break;
            case "connect":
                setAddress(event.data.hexAddress);
                sendMessage({ type: "modalTypeChange", modalType: "account" });
                updateTriggerBoundingRect();
                break;
            case "disconnect":
                setAddress("");
                sendMessage({
                    type: "modalTypeChange",
                    modalType: "wallet-selector",
                });
                updateTriggerBoundingRect();
                break;
            default:
                break;
        }
    };

    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
}, [initModal, sendMessage, updateTriggerBoundingRect]);

Optional messages that can be received from the widget:

• ready: Indicates the widget has fully loaded and is ready for user interaction.
• close: Signifies the user has closed the widget, allowing you to hide the widget interface or reset its state.
• connect: Notifies that a user has successfully connected their wallet. This message includes the user's address (bech32 address and hexAddress), enabling you to update the UI or trigger further actions.
• disconnect: Indicates the user has disconnected their wallet. Use this message to clear user data from your UI or revert to a default state.

Listening for these messages and implementing corresponding actions in your application ensures a seamless and responsive experience for users interacting with the Dymension Connect Widget.