UI#

在 SDK 的基础上，我们也提供了 UI 界面。如果选择通过UI接入，若DApp运营在 Telegram内，则用户可以选择唤起移动端App钱包或者停留在Telegram并唤起欧易 Telegram Mini 钱包。

如果您之前使用过Ton Connect，可以继续使用此文档连接，可以减少开发成本。

如果您之前使用过OKX Connect，可以跳转去使用ProviderUI进行连接，可以减少开发成本，并且可以支持多个网络同时请求。

通过npm安装#

npm install @okxconnect/ui

初始化#

连接钱包之前，需要先创建一个对象，用于后续连接钱包、发送交易等操作

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

请求参数

metaData - object
- name - string: 应用名称，不会作为唯一表示
- icon - string: 应用图标的 URL。必须是 PNG、ICO 等格式，不支持 SVG 图标。最好传递指向 180x180px PNG 图标的 url。
buttonRootId - string: 用于附加钱包连接按钮的 HTML 元素 ID。如果没有传递，则不会出现按钮;
actionsConfiguration - object
- modals - ('before' | 'success' | 'error')[] | 'all' 交易过程中的提醒界面展示模式。
- returnStrategy -string 'none' | ${string}://${string}; 指定当用户签署/拒绝请求时深层链接的返回策略，如果是在tg中，可以配置tg://resolve
- tmaReturnUrl -string 'back' | 'none' | ${string}://${string}; Telegram Mini Wallet 钱包中，用户签署/拒绝请求时深层链接的返回策略，一般配置back,表示签名后关闭钱包，会自动展示出dapp；none 表示签名后不做处理；默认为back；
uiPreferences -object
- theme - Theme 可以是：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"; , 默认为en_US
restoreConnection?: boolean - 是否自动回复之前的连接；

返回值

OKXTonConnectUI

示例

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
});

监听钱包状态变化#

钱包状态有：连接成功、恢复连接成功、断开连接等，都可以用此方法获取状态。方法详情同OKXTonConnect.onStatusChange

示例

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

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

当不再需要监听更新时，调用unsubscribe节省资源。

unsubscribe()

连接钱包#

连接钱包去获取钱包地址，作为标识符和用于签名交易的必要参数， “连接按钮”（添加于buttonRootId）会自动处理点击并调用连接，如果没有添加buttonRootId 的话，需要调用此方法。

await okxTonConnectUI.openModal();

示例

okxTonConnectUI.openModal();

设置tonProof#

添加连接签名参数, 如果需要设置tonProof，请在准备好tonProof 参数之前，设置state:'loading', 在准备好之后，将state设置为 'ready'并添加value; 也可以通过设置setConnectRequestParameters(null) 移除掉loading 状态

示例

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

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

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

关闭连接弹窗#

示例

okxTonConnectUI.closeModal();

获取当前连接的Wallet和WalletInfo#

获取当前是否有连接钱包，以及已连接的钱包的相关信息

示例

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

断开钱包连接#

示例

okxTonConnectUI.disconnect()

发送交易#

向钱包发送消息的方法：

sendTransaction(transaction, actionConfigurationRequest): Promise<SendTransactionResponse>

请求参数

transaction - object, 参数同OKXTonConnect.sendTransaction的transaction
actionConfigurationRequest - object
- modals : ('before' | 'success' | 'error')[] | 'all' 交易过程中的提醒界面展示模式，默认为'before'
- returnStrategy -string 'none' | ${string}://${string}; App 钱包中，用户签署或拒绝请求时深层链接的返回策略，如果是Telegram中的Mini App，可以配置tg://resolve，如果这里没有配置的话，会取init方法传递的 returnStrategy，默认为 ‘none’
- tmaReturnUrl -string 'back' | 'none' | ${string}://${string}; Telegram Mini Wallet 钱包中，用户签署/拒绝请求时深层链接的返回策略，一般配置back,表示签名后关闭钱包，会自动展示出dapp；none 表示签名后不做处理；默认为back；

返回值

Promise - {boc: string}: 签名结果

示例

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;
    }
})

设置ui配置项#

支持修改主题，文字语言设置，也可以在初始化的时候添加这些配置

示例

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

监听事件#

在以下事件发生时，会发送对应事件通知，Dapp可以根据需要添加监听，来处理对应的逻辑

event事件

事件名称	触发时机
OKX_UI_CONNECTION_STARTED	当用户开始连接钱包时
OKX_UI_CONNECTION_COMPLETED	当用户成功连接钱包时
OKX_UI_CONNECTION_ERROR	当用户取消连接或连接过程中出现错误时
OKX_UI_CONNECTION_RESTORING_STARTED	当 dApp 开始恢复连接时
OKX_UI_CONNECTION_RESTORING_COMPLETED	当 dApp 成功恢复连接时
OKX_UI_CONNECTION_RESTORING_ERROR	当 dApp 无法恢复连接时
OKX_UI_DISCONNECTION	当用户开始断开钱包连接时
OKX_UI_TRANSACTION_SENT_FOR_SIGNATURE	当用户发送交易以供签名时
OKX_UI_TRANSACTION_SIGNED	当用户成功签署交易时
OKX_UI_TRANSACTION_SIGNING_FAILED	当用户取消交易签名或签名过程中出现错误时

示例

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事件#

// 生成 universalLink
universalUi.on("display_uri", (uri) => {
  console.log(uri);
});
// session 信息变更会触发该事件；
universalUi.on("session_update", (session) => {
  console.log(JSON.stringify(session));
});
// 断开连接会触发该事件；
universalUi.on("session_delete", ({topic}) => {
  console.log(topic);
});
// 连接并签名时,签名结果会触发该事件;
universalUi.on("connect_signResponse", (signResponse) => {
  console.log(signResponse);
});

错误码#

在连接，交易，断开连接的过程中可能抛出的异常

异常

错误码	描述
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR	未知异常
OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR	钱包已连接
OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR	钱包未连接
OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR	用户拒绝
OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED	方法不支持
OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED	链不支持
OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED	钱包不支持
OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR	连接异常

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
}