UI#

In addition to SDK, we also provide a UI interface. If using the UI connection, and the DApp is operating in Telegram, users can choose to open the mobile App Wallet or stay in Telegram and launch the OKX Mini Wallet.

If you have used Ton Connect before, you can continue to use this document to connect, which can reduce development costs.

If you have used OKX Connect before, you can jump to using ProviderUI to connect, which can reduce development costs and support multiple network requests at the same time.

Install via npm#

npm install @okxconnect/ui

Initialization#

Before connecting to the wallet, you need to create an object for subsequent operations such as connecting to the wallet and sending transactions.

new OKXTonConnectUI(dappMetaData, buttonRootId, actionsConfiguration, uiPreferences, language, restoreConnection)

Request parameters

• metaData - object
  • name - string: The name of the application, will not be used as a unique representation.
  • icon - string: URL of the application icon, must be in PNG, ICO, etc. SVG icons are not supported. It is better to pass a url pointing to a 180x180px PNG icon.
• buttonRootId - string: the HTML element ID of the button used to attach the wallet connection. if not passed, the button will not appear;.
• actionsConfiguration - object
  • modals - ('before' |'success' |'error')[] |'all' The modals for displaying the alert screen during a transaction.
  • returnStrategy -string'none' | ${string}://${string}; Specify the return strategy for deep links when the user signs/rejects the request, if in telegram, configure tg://resolve
  • tmaReturnUrl -string'back' |'none' | ${string}://${string}; Telegram Mini Wallet wallet, when the user signs/rejects the request, the deep link return policy, generally configure back, that means after signing and closing the wallet, it will automatically show the dapp; none means no processing after signing; default is back;
• uiPreferences -object
  • theme - Theme can be: THEME.DARK, THEME.LIGHT,'SYSTEM'.
• language -'en_US’ |'ru_RU’ |'zh_CN’ |'ar_AE’ |'cs_CZ’ |'de_DE’ |'es_ES’ |'es_LAT’ |'fr_FR’ |'id_ID’ |'it_IT’ |'nl_NL’ |'pl_PL’ |'pt_BR’ |'pt_PT’ |'ro_RO’ |'tr_TR’ |'uk_UA’ |'vi_VN’. , defaults to en_US
• restoreConnection?: boolean - Whether to automatically restore the previous connection;

Returns the value

• OKXTonConnectUI

Example

import { OKXTonConnectUI } from "@okxconnect/ui";

const okxTonConnectUI = new OKXTonConnectUI({
    dappMetaData: {
        name: "application name",
        icon: "application icon url"
    },
    buttonRootId:'button-root',
    actionsConfiguration:{
        returnStrategy:'none',
        tmaReturnUrl:'back'
    },
    uiPreferences: {
        theme: THEME.LIGHT
    },
    language:'en_US',
    restoreConnection: true
});

Monitor wallet state changes#

The wallet status are: connect successfully, resume connect successfully, disconnect, etc. You can use this method to get the status. Method details same as OKXTonConnect.onStatusChange

Example

import { Wallet } from "@okxconnect/tonsdk";

const unsubscribe = okxTonConnectUI.onStatusChange((walletInfo: Wallet | null) => {
        console.log('Connection status:', walletInfo);
    }, (err: OKXConnectError) => {
        console.log('Connection status:', err);
    }
)

Call unsubscribe to save resources when you no longer need to listen for updates.

unsubscribe()

Connect to Wallet#

Connecting to a wallet goes to get the wallet address, which serves as the identifier and the necessary parameters used to sign the transaction. The “Connect Button” (added to buttonRootId) automatically handles the click and invokes the connection. If no buttonRootId is added, this method needs to be called.

await okxTonConnectUI.openModal();

Example

okxTonConnectUI.openModal();

Set the tonProof#

Add the connection signature parameter, the If you need to set tonProof, set state:'loading', before the tonProof parameter is ready. When ready, set state to'ready' and add value;. You can also remove the loading state by setting setConnectRequestParameters(null);

Example

okxtonConnectUI.setConnectRequestParameters({ state:'loading' });

const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
  okxtonConnectUI.setConnectRequestParameters(null);
} else {
  okxtonConnectUI.setConnectRequestParameters({
    state: "ready",
    value: { tonProof: tonProofPayload }
  });
}

Close connection popup#

Example

okxTonConnectUI.closeModal();

Get the currently connected Wallet and WalletInfo#

Get information about whether there is a currently connected wallet, and the connected wallet;

Example

const currentWallet  = okxTonConnectUI.wallet;
const currentAccount = okxTonConnectUI.account;
const isConnected    = okxTonConnectUI.connected;

Disconnect#

Example

okxTonConnectUI.disconnect();

Send transaction#

Method for sending a message to a wallet:

sendTransaction(transaction, actionConfigurationRequest): Promise<SendTransactionResponse>

Request parameters

• transaction - object, [parameters same as OKXTonConnect.sendTransaction's transaction](/web3/build/docs/sdks/app-connect-ton-sdk#%E5%8F%91%E9%80%81% E4%BA%A4%E6%98%93)

• actionConfigurationRequest - object

  • modals : ('before' |'success' |'error')[] |'all' Mode of displaying the alert screen during the transaction, defaults to'before'
  • returnStrategy -string'none’ | ${string}://${string}; The return strategy for the deep link in the App wallet when the user signs or rejects the request, if it is a Mini App in Telegram, it can be configured with tg://resolve, and if it's not configured here, the will take the returnStrategy passed by the init method, default is'none’
  • tmaReturnUrl -string'back' |'none' | ${string}://${string}; Telegram Mini Wallet wallet, when the user signs/rejects the request, the deep link return strategy, generally configure back, that is to say, after signing and closing the wallet, it will be displayed automatically. dapp; none means no processing after signing; default is back;

Return Value

• Promise - {boc: string}: Signature Result

import { OKXConnectError, OKX_CONNECT_ERROR_CODES } from "@okxconnect/core";

let transactionRequest = {
    "validUntil": Date.now() / 1000 + 360,
    "from": "0:348bcf827469c5fc38541c77fdd91d4e347eac200f6f2d9fd62dc08885f0415f",
    "messages": [
        {
            "address": "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F",
            "amount": "20000000",
            "stateInit": "base64bocblahblahblah==" //deploy contract
        },
        {
            "address": "0:E69F10CC84877ABF539F83F879291E5CA169451BA7BCE91A37A5CED3AB8080D3",
            "amount": "60000000",
            "payload": "base64bocblahblahblah==" //transfer nft to new deployed account 0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F
        }
    ]
}

okxTonConnectUI.sendTransaction(transactionRequest, {
    modals:'all',
    tmaReturnUrl:'back'
}).then((result) => {
    let boc = result.boc
}).catch((error) => {
    if (error instanceof OKXConnectError && error.code == OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR) {
        //userReject;
    } else {
        //other error;
    }
})

Set ui configuration items#

Support to modify theme, text language setting, also can add these configurations during initialisation;

Example

okxTonConnectUI.uiOptions = {
  language:'zh_CN',
  uiPreferences: {
    theme: THEME.DARK
  }
};

Listening to Events#

When the following events occur, a notification of the corresponding event will be sent, and the Dapp can add listeners as needed to handle the corresponding logic;

event

Example

import { OKX_UI_CONNECTION_AND_TRANSACTION_EVENT } from "@okxconnect/ui";

window.addEventListener(OKX_UI_CONNECTION_AND_TRANSACTION_EVENT.OKX_UI_CONNECTION_STARTED, (event) => {
    if (event instanceof CustomEvent) {
        console.log('Transaction init', event.detail);
    }
});

Event#

// Generate universalLink
universalUi.on("display_uri", (uri) => {
    console.log(uri);
}).
// Session information changes will trigger this event;
universalUi.on("session_update", (session) => {
  console.log(JSON.stringify(session));
});
// Disconnecting triggers this event;
universalUi.on("session_delete", ({topic}) => {
    console.log(topic);
});
// This event is triggered when a connection is made and the signature is signed.
universalUi.on("connect_signResponse", (signResponse) => {
  console.log(signResponse);
});

Error codes#

Exceptions that may be thrown during connection, transaction, and disconnection.

Exception

export enum OKX_CONNECT_ERROR_CODES {
    UNKNOWN_ERROR = 0,
    ALREADY_CONNECTED_ERROR = 11,
    NOT_CONNECTED_ERROR = 12,
    USER_REJECTS_ERROR = 300,
    METHOD_NOT_SUPPORTED = 400,
    CHAIN_NOT_SUPPORTED = 500,
    WALLET_NOT_SUPPORTED = 600,
    CONNECTION_ERROR = 700
}