TON Connect SDK 开发指南：从集成到实战应用

·

本文详细介绍了 TON Connect SDK 的核心功能与使用方法，帮助开发者快速实现 DApp 与钱包的高效连接，并支持安全的交易签名操作。

什么是 TON Connect SDK？

TON Connect SDK 是一套开放的协议，允许去中心化应用（DApp）与 TON 区块链上的钱包安全连接。通过标准化流程，开发者可在应用中集成钱包登录及交易功能，提升用户体验并降低开发成本。

如果您之前使用过 TON Connect，可以继续沿用本文档进行对接，这能显著减少开发工作量。

安装 SDK

SDK 支持通过 CDN 或 NPM 两种方式安装。

通过 CDN 安装

将以下代码添加到 HTML 文件中，也可将 latest 替换为特定版本号（例如 1.3.7）：

<script src="https://static.okx.com/cdn/assets/okxweb3/okx-ton-connect/latest.js"></script>

引入后，OKXTonConnectSDK 将作为全局对象使用，可直接引用：

const connector = new OKXTonConnectSDK.OKXTonConnect();

通过 NPM 安装

使用 npm 或 yarn 进行安装：

npm install @okx/okx-ton-connect
# 或
yarn add @okx/okx-ton-connect

安装后在项目中引入：

import { OKXTonConnect } from '@okx/okx-ton-connect';

初始化配置

在连接钱包前，需先创建 SDK 实例：

const connector = new OKXTonConnect({
  metaData: {
    name: "YourDAppName",
    icon: "https://yourapp.com/icon.png"
  }
});

参数说明：

连接钱包

使用 connect 方法连接钱包，以获取钱包地址和交易签名所需参数：

const connectRequest = {
  tonProof: "optional_signature",
  redirect: "optional_deeplink",
  openUniversalLink: true
};
const universalLink = await connector.connect(connectRequest);

参数说明：

最佳实践：

👉 查看实时连接状态与调试工具

连接状态管理

恢复连接

如果用户之前已连接过钱包，可使用此方法恢复连接状态：

await connector.restoreConnection();

断开连接

断开当前连接的钱包并删除会话。如需切换钱包，请先断开当前连接：

await connector.disconnect();

检查连接状态

获取当前是否有已连接的钱包：

const isConnected = connector.connected;

发送交易

使用 sendTransaction 方法向钱包发送交易请求：

const transaction = {
  validUntil: Math.floor(Date.now() / 1000) + 600, // 10分钟后失效
  from: "sender_address",
  messages: [
    {
      address: "recipient_address",
      amount: "1000000000",
      stateInit: "optional_state_init",
      payload: "optional_payload"
    }
  ]
};

const options = {
  onRequestSent: () => {
    console.log("签名请求已发送");
  }
};

const result = await connector.sendTransaction(transaction, options);

监听钱包状态变化

通过 onStatusChange 方法监听钱包状态变化，如连接成功、恢复连接、断开连接等：

const unsubscribe = connector.onStatusChange(
  (walletInfo) => {
    console.log("钱包状态变化:", walletInfo);
  },
  (error) => {
    console.error("监听错误:", error);
  }
);

// 需要时取消监听
unsubscribe();

事件监听系统

当特定事件发生时，SDK 会发送事件通知，DApp 可添加监听器处理相应逻辑：

window.addEventListener('OKX_TON_CONNECTION_COMPLETED', (event) => {
  console.log('钱包连接成功', event.detail);
});

window.addEventListener('OKX_TON_TRANSACTION_SIGNED', (event) => {
  console.log('交易签名成功', event.detail);
});

主要事件类型：

账户与钱包信息获取

获取账户信息

获取当前连接的账户详情：

const account = connector.account;
console.log("当前账户地址:", account.address);

获取钱包信息

获取当前连接的钱包信息：

const walletInfo = connector.wallet;
console.log("钱包名称:", walletInfo.device.appName);
console.log("支持的功能:", walletInfo.features);

错误处理与调试

SDK 提供了完整的错误代码系统，帮助开发者快速定位问题：

try {
  await connector.connect();
} catch (error) {
  switch(error.code) {
    case 'USER_REJECTS_ERROR':
      console.log('用户拒绝了连接请求');
      break;
    case 'NOT_CONNECTED_ERROR':
      console.log('钱包未连接');
      break;
    default:
      console.log('未知错误', error.message);
  }
}

常见问题

如何选择适合的集成方式？

根据您的开发环境选择安装方式：CDN 适合简单页面快速集成，NPM 适合复杂的项目结构。两者在功能上没有差异，均可实现完整的功能对接。

连接时推荐使用哪种唤醒方式？

在移动端环境中推荐使用 Universal Link 直接唤起应用，提供更流畅的用户体验。在桌面端则建议使用二维码方式，兼容性更好。

交易发送后如何确认状态？

可通过监听交易相关事件来获取实时状态更新，同时建议在前端界面提供明确的状态提示，增强用户体验。

如何处理用户拒绝签名的情况？

捕获 USER_REJECTS_ERROR 错误代码，并给用户友好的提示，说明交易需要签名才能继续，避免流程中断。

👉 获取进阶集成方案与最佳实践

支持哪些网络环境？

SDK 支持主网和测试网环境，确保在开发阶段使用测试网进行调试，上线前切换至主网配置。

如何优化移动端体验？

在移动端使用深链接直接唤起钱包应用，减少用户操作步骤。同时合理设置会话有效期，平衡安全性与便利性。

通过本指南，您应该已经掌握了 TON Connect SDK 的核心功能和使用方法。在实际开发中，建议先通过测试网充分验证所有流程，确保生产环境的稳定性和安全性。