UI#

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

通过npm安装#

npm install @okxconnect/ui

初始化#

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

OKXUniversalConnectUI.init(dappMetaData, actionsConfiguration, uiPreferences, language, restoreConnection)

请求参数

• 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
• restoreConnection?: boolean - 是否自动回复之前的连接

返回值

• OKXUniversalConnectUI

示例

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

const universalUi = 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
  },
});

连接钱包#

连接钱包去获取钱包地址，作为标识符和用于签名交易的必要参数

await universalUi.openModal(connectParams: ConnectParams)

请求参数

• connectParams - ConnectParams
  • namespaces - [namespace: string]: ConnectNamespace ; 请求连接的必要信息， EVM系的key为"eip155" ，如果请求的链中，有任何一个链钱包不支持的话，钱包会拒绝连接
    • chains: string[]; 链id信息，EIP155中定义的十进制数字，比如以太坊是eip155:1
    • defaultChain?: string; 默认链
  • optionalNamespaces - [namespace: string]: ConnectNamespace; 请求连接的可选信息， EVM系的key为"eip155"，如果对应的链信息钱包不支持，依然可以连接；如果需要连接自定义网络的话，可以将自定义网络的请求添加到此参数中，如果钱包中已经有该自定义网络，则会在请求结果 session 中返回该自定义链的信息；如果钱包不支持的话，请求结果session 中无该自定义链信息，可以再次调用 request 方法，method 设置为 wallet_addEthereumChain，添加该自定义链
    • chains: string[]; 链id信息

返回值

• 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

示例

var session = await universalUi.openModal({
  namespaces: {
    eip155: {
          // 请按需组合需要的链id传入，多条链就传入多个
          chains: ["eip155:1"],
          defaultChain: "1"
      }
  },
  optionalNamespaces: {
    eip155: {
      chains: ["eip155:43114"]
    }
  }
})

连接钱包并签名#

连接钱包获取钱包地址，并对数据进行签名；签名结果会在"connect_signResponse"的event中回调

await okxUniversalConnectUI.openModalAndSign(connectParams: ConnectParams, signRequest: RequestParams[])

请求参数

• connectParams - ConnectParams
  • namespaces - [namespace: string]: ConnectNamespace ; 请求连接的必要信息， EVM系的key为"eip155" ，如果请求的链中，有任何一个链钱包不支持的话，钱包会拒绝连接
    • chains: string[]; 链id信息，EIP155中定义的十进制数字，比如以太坊是eip155:1
    • defaultChain?: string; 默认链
  • optionalNamespaces - [namespace: string]: ConnectNamespace; 请求连接的可选信息， EVM系的key为"eip155"，如果对应的链信息钱包不支持，依然可以连接；如果需要连接自定义网络的话，可以将自定义网络的请求添加到此参数中，如果钱包中已经有该自定义网络，则会在请求结果 session 中返回该自定义链的信息；如果钱包不支持的话，请求结果session 中无该自定义链信息，可以再次调用 request 方法，method 设置为 wallet_addEthereumChain，添加该自定义链
    • chains: string[]; 链id信息
• signRequest - RequestParams[]; 请求连接并签名的方法, 同时最多只能支持一个方法
  • method: string; 请求的方法名称,EVM系支持的方法有："personal_sign"
  • 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

示例

// 先添加签名结果监听
universalUi.on("connect_signResponse", (signResponse) => {
  console.log(signResponse);
});
var session = await universalUi.openModalAndSign({
  namespaces: {
    eip155: {
      // 请按需组合需要的链id传入，多条链就传入多个
      chains: ["eip155:1"],
      defaultChain: "1"
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ["eip155:43114"]
    }
  },
  sessionConfig: {
    redirect: "tg://resolve"
  }
},[{
  method: "personal_sign",
  chainId: "eip155:1",
  params: [
    "0x4d7920656d61696c206973206a6f686e40646f652e636f6d202d2031373237353937343537313336",
  ],
}])

判断钱包是否已连接#

获取当前是否有连接钱包

返回值

• boolean

示例

universalUi.connected()

准备交易#

向钱包发送消息的方法，支持签名，交易

universalUi.request(requestArguments, chain, actionConfigurationRequest)

请求参数

• requestArguments - object
  • method: string; 请求的方法名
  • params?: unknown[] | Record<string, unknown> | object | undefined; 请求的方法对应的参数
• chain: string; 请求方法执行的链，建议传该参数，如果未传的话，会被设置为当前的defaultChain
• actionConfigurationRequest - object
  • modals : ('before' | 'success' | 'error')[] | 'all' 交易过程中的提醒界面展示模式，如果request 没有设置该参数的，取init 时候添加的参数，如果init 没有也设置该参数，则取默认值：'before'
  • tmaReturnUrl -string 'back' | 'none' | ${string}://${string}; Telegram Mini Wallet 钱包中，用户签署/拒绝请求时深层链接的返回策略，一般配置back,表示签名后关闭钱包，会自动展示出dapp；none 表示签名后不做处理；默认为back
  • returnStrategy -string 'none' | ${string}://${string}; App 钱包中，用户签署或拒绝请求时深层链接的返回策略，如果是Telegram中的Mini App，可以配置tg://resolve，如果这里没有配置的话，会取init方法传递的 returnStrategy，默认为 ‘none’

返回值

返回参数详情同EVM兼容链的发送签名和交易

示例

示例同EVM兼容链的发送签名和交易

let chain = 'eip155:1'
var data = {}

data = {
    "method": "personal_sign",
    "params": [
        "0x506c65617365207369676e2074686973206d65737361676520746f20636f6e6669726d20796f7572206964656e746974792e",
        "0x4B0897b0513FdBeEc7C469D9aF4fA6C0752aBea7"
    ]
}
var personalSignResult = await universalUi.request(data, chain,'all')
//personalSignResult:   0xe8d34297c33a61"

关闭连接弹窗#

示例

universalUi.closeModal()

监听连接弹窗状态变化#

示例

const unsubscribe = universalUi.onModalStateChange((state)=>{
})

不需要监听的时候移除监听

unsubscribe()

获取当前连接的会话信息#

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

示例

universalUi.session

设置ui配置项#

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

示例

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

设置默认网络#

在连接多个网络的状况下,如果开发者没有明确指定当前操作所在网络,则通过默认网络进行交互。

setDefaultChain(chain)

示例

universalUi.setDefaultChain("eip155:1")

断开钱包连接#

示例

universalUi.disconnect()

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

错误码#

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

异常

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
}