UI#
在 SDK 的基础上,我们也提供了 UI 界面。如果选择通过UI接入,若DApp运营在 Telegram内,则用户可以选择唤起移动端App钱包或者停留在Telegram并唤起欧易 Telegram Mini 钱包。
安装及初始化#
请确保更新OKX App到 6.90.1版本或以后版本,即可开始接入:
将 OKX Connect 集成到您的 DApp 中,可以使用 npm:
npm install @okxconnect/ui
npm install @okxconnect/sui-provider
连接钱包之前,需要先创建一个可以提供UI界面的对象,用于后续连接钱包、发送交易等操作。
OKXUniversalConnectUI.init(dappMetaData, actionsConfiguration, uiPreferences, language)
请求参数
- dappMetaData - object
- name - string: 应用名称,不会作为唯一表示
- icon - string: 应用图标的 URL。必须是 PNG、ICO 等格式,不支持 SVG 图标。最好传递指向 180x180px PNG 图标的 url。
- actionsConfiguration - object
- modals - ('before' | 'success' | 'error')[] | 'all' 交易过程中的提醒界面展示模式,默认为'before'
- returnStrategy -string 'none' |
${string}://${string}
; 针对app 钱包,指定当用户签署/拒绝请求时深层链接的返回策略,如果是在telegram中,可以配置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
返回值
- OKXUniversalConnectUI
示例
import { OKXUniversalConnectUI } from "@okxconnect/ui";
const okxUniversalConnectUI = await OKXUniversalConnectUI.init({
dappMetaData: {
icon: "https://static.okx.com/cdn/assets/imgs/247/58E63FEA47A2B7D7.png",
name: "OKX Connect Demo"
},
actionsConfiguration: {
returnStrategy: 'tg://resolve',
modals:"all",
tmaReturnUrl:'back'
},
language: "en_US",
uiPreferences: {
theme: THEME.LIGHT
},
});
连接钱包#
连接钱包去获取钱包地址,作为标识符和用于签名交易的必要参数
okxUniversalConnectUI.openModal(connectParams: ConnectParams)
请求参数
- connectParams - ConnectParams
- namespaces - [namespace: string]: ConnectNamespace ; 请求连接的必要信息,Sui系的key为"sui"
,如果请求的链中,有任何一个链钱包不支持的话,钱包会拒绝连接
- chains: string[]; 链id信息
- optionalNamespaces - [namespace: string]: ConnectNamespace; 请求连接的可选信息, EVM系的key为"eip155",Sui系的key为"sui"
,如果对应的链信息钱包不支持,依然可以连接
- chains: string[]; 链id信息
- sessionConfig: object
- redirect: string 连接成功后的跳转参数,如果是Telegram中的Mini App,这里可以设置为Telegram的deeplink: "tg://resolve"
- namespaces - [namespace: string]: ConnectNamespace ; 请求连接的必要信息,Sui系的key为"sui"
,如果请求的链中,有任何一个链钱包不支持的话,钱包会拒绝连接
返回值
- Promise
<SessionTypes.Struct | undefined>
- topic: string; 会话标识
- namespaces:
Record<string, Namespace>
; 成功连接的namespace 信息- chains: string[]; 连接的链信息
- accounts: string[]; 连接的账户信息
- methods: string[]; 当前namespace下,钱包支持的方法
- defaultChain?: string; 当前会话的默认链
- sessionConfig?: SessionConfig
- dappInfo: object DApp 信息
- name:string
- icon:string
- dappInfo: object DApp 信息
示例
var session = await okxUniversalConnectUI.openModal({
namespaces: {
sui: {
chains: ["sui:mainnet"]
}
}
})
连接钱包并签名#
连接钱包获取钱包地址,并对数据进行签名;签名结果会在"connect_signResponse"的event中回调;
await okxUniversalConnectUI.openModalAndSign(connectParams: ConnectParams, signRequest: RequestParams[])
请求参数
- connectParams - ConnectParams
- namespaces - [namespace: string]: ConnectNamespace ; 请求连接的必要信息,Sui系的key为"sui"
,如果请求的链中,有任何一个链钱包不支持的话,钱包会拒绝连接
- chains: string[]; 链id信息
- optionalNamespaces - [namespace: string]: ConnectNamespace; 请求连接的可选信息,Sui系的key为"sui"
,如果对应的链信息钱包不支持,依然可以连接
- chains: string[]; 链id信息
- sessionConfig: object
- redirect: string 连接成功后的跳转参数,如果是Telegram中的Mini App,这里可以设置为Telegram的deeplink: "tg://resolve"
- namespaces - [namespace: string]: ConnectNamespace ; 请求连接的必要信息,Sui系的key为"sui"
,如果请求的链中,有任何一个链钱包不支持的话,钱包会拒绝连接
- signRequest - RequestParams[]; 请求连接并签名的方法, 同时最多只能支持一个方法
- method: string; 请求的方法名称, Sui支持的方法有:"sui_signMessage" 和 "sui_signPersonalMessage"
- chainId: string; 执行方法所在的链的ID, 该chainId必须包含在上面的namespaces中
- params: unknown[] | Record
<string, unknown>
| object | undefined; 请求的方法对应的参数
返回值
- Promise
<SessionTypes.Struct | undefined>
- topic: string; 会话标识
- namespaces:
Record<string, Namespace>
; 成功连接的namespace 信息- chains: string[]; 连接的链信息
- accounts: string[]; 连接的账户信息
- methods: string[]; 当前namespace下,钱包支持的方法
- defaultChain?: string; 当前会话的默认链
- sessionConfig?: SessionConfig
- dappInfo: object DApp 信息
- name:string
- icon:string
- dappInfo: object DApp 信息
示例
// 先添加签名结果监听
okxUniversalConnectUI.on("connect_signResponse", (signResponse) => {
console.log(signResponse);
});
let suiData = [
76, 111, 103, 105, 110, 32, 119, 105, 116, 104, 32, 66, 108, 117, 101,
109, 111, 118, 101,
];
let uint8Array = new Uint8Array(suiData);
var session = await okxUniversalConnectUI.openModalAndSign({
namespaces: {
sui: {
chains: ["sui:mainnet"]
}
},
sessionConfig: {
redirect: "tg://resolve"
}
},
[
{
chainId: "sui:mainnet",
method: "sui_signMessage",
params: {
message: uint8Array,
}
}
]
)
判断钱包是否已连接#
获取当前是否有连接钱包
返回值
- boolean
示例
okxUniversalConnectUI.connected()
断开连接#
断开已连接钱包,并删除当前会话,如果要切换连接钱包,请先断开当前钱包。
示例
okxUniversalConnectUI.disconnect()
准备交易#
向钱包发送消息的方法,支持签名,交易;当需要钱包确认的方法时候,会弹出提示页面;
首先创建一个OKXSuiProvider对象,构造函数传入okxUniversalConnectUI
import { OKXSuiProvider } from "@okxconnect/sui-provider"
let suiProvider = new OKXSuiProvider(okxUniversalConnectUI)
获取账户信息#
suiProvider.getAccount()
返回值
- Object
- address: string 钱包地址
- publicKey: string 公钥(需要App 6.92.0以后版本支持)
示例
let result = suiProvider.getAccount()
//返回结构
{
"address": "0x7995ca23961fe06d8cea7da58ca751567ce820d7cba77b4a373249034eecca4a",
"publicKey": "tUvCYrG22rHKR0c306MxgnhXOSf16Ot6H3GMO7btwDI=",
}
签名Message#
suiProvider.signMessage(input: SuiSignMessageInput)
请求参数
- SuiSignMessageInput - object
- message: Uint8Array
返回值
- Promise - object
- messageBytes: string
- signature: string
签名PersonalMessage#
suiProvider.signPersonalMessage(input: SuiSignMessageInput)
请求参数
- SuiSignMessageInput - object
- message: Uint8Array
返回值
- Promise - object
- bytes: string
- signature: string
示例
const data = [76, 111, 103, 105, 110, 32, 119, 105, 116, 104, 32, 66, 108, 117, 101, 109, 111, 118, 101];
const uint8Array = new Uint8Array(data);
let input = {
message: uint8Array
}
let signResult1 = await suiProvider.signMessage(input)
let signResult2 = await suiProvider.signPersonalMessage(input)
签交易#
suiProvider.signTransaction(input)
请求参数
// txBytes与txSerialize为transactionBlock的序列化
// 和transactionBlock传入一种即可无需同时传入
interface SuiSignTransactionBlockInput {
transactionBlock: TransactionBlock;
chain: IdentifierString;
txBytes: string?;
txSerialize: string?
}
返回值
- Promise - object
- signature: string,
- transactionBlockBytes: string
签交易并广播上链#
suiProvider.signAndExecuteTransaction(input)
请求参数
// txBytes与txSerialize为transactionBlock的序列化
// 和transactionBlock传入一种即可无需同时传入
interface SuiSignTransactionBlockInput {
transactionBlock: TransactionBlock;
chain: IdentifierString;
txBytes: string?;
txSerialize: string?;
}
返回值
- Promise - object
- confirmedLocalExecution: bool,
- digest: string,
- txBytes: string
示例
// 定义要转移的金额和目标地址
const amount = 109; // 需要转移的金额
const recipientAddress = '0x'; // 目标地址
/// 构造一个转账的交易
const tx = new Transaction();
const [coin] = tx.splitCoins(tx.gas, [amount]);
tx.transferObjects([coin], recipientAddress)
const input = {
transactionBlock: tx,
chain: 'sui:mainnet',
options: {
showEffects: true,
}
}
let signResult1 = await suiProvider.signTransaction(input)
let signResult2 = await suiProvider.signAndExecuteTransaction(input)
Event事件#
// 生成 universalLink
okxUniversalConnectUIv.on("display_uri", (uri) => {
console.log(uri);
});
// session 信息变更会触发该事件;
okxUniversalConnectUI.on("session_update", (session) => {
console.log(JSON.stringify(session));
});
// 断开连接会触发该事件;
okxUniversalConnectUI.on("session_delete", ({topic}) => {
console.log(topic);
});
// 连接并签名时,签名结果会触发该事件;
okxUniversalConnectUI.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
}