快上手

这里演示如何检测 UKey Wallet TON Connect Provider、建立会话、读取连接结果并监听钱包状态。

ℹ️

UKey Wallet 实现 TON Connect 2.0 协议，可接入支持 TON Connect 的 DApp 和 SDK。

---

找 Provider

// 检查 UKey Wallet TON provider
const provider = window.$ukey?.tonconnect;

if (!provider) {
  throw new Error("未检测到 UKey Wallet TON provider");
}

// 确认设备与钱包信息
console.log("识别到的设备信息:", provider.deviceInfo);
console.log("识别到的钱包信息:", provider.walletInfo);
console.log("协议版本号:", provider.protocolVersion); // 数值参考片段：2

---

连接账户

// 基础连接方式
const connectEvent = await provider.connect();

if (connectEvent.event === "connect") {
  const addressItem = connectEvent.payload.items.find(
    (item) => item.name === "ton_addr",
  );
  console.log("连接结果:", addressItem.address);
} else {
  console.error("连接未成功:", connectEvent.payload.message);
}

---

使用 Manifest 连接

生产环境应提供 manifest URL，让钱包展示可信的应用名称、图标和隐私链接：

const connectRequest = {
  manifestUrl: "https://sampleapp.example/tonconnect-manifest.json",
  items: [
    { name: "ton_addr" },
    { name: "ton_proof", payload: "demo-proof-check" },
  ],
};

const connectEvent = await provider.connect(2, connectRequest);

if (connectEvent.event === "connect") {
  const addressItem = connectEvent.payload.items.find(
    (i) => i.name === "ton_addr",
  );
  const proofItem = connectEvent.payload.items.find(
    (i) => i.name === "ton_proof",
  );

  console.log("解析出的地址:", addressItem.address);
  console.log("返回的证明数据:", proofItem?.proof);
}

---

Manifest 格式

在应用根目录创建 tonconnect-manifest.json：

{
  "url": "https://sampleapp.example",
  "name": "Your App Name",
  "iconUrl": "https://sampleapp.example/icon.png",
  "termsOfUseUrl": "https://sampleapp.example/terms",
  "privacyPolicyUrl": "https://sampleapp.example/privacy"
}

---

恢复会话

页面刷新后可以尝试恢复之前的会话：

const connectEvent = await provider.restoreConnection();

if (connectEvent.event === "connect") {
  console.log("上一次会话已恢复");
}

---

断连

await provider.disconnect();

---

事件流

provider.listen((event) => {
  console.log("钱包回调事件:", event);
});

// 或者使用专门的事件监听器
provider.on("accountChanged", (address) => {
  if (address) {
    console.log("当前账户已切换为:", address);
  } else {
    console.log("连接已关闭");
  }
});

provider.on("disconnect", () => {
  console.log("钱包会话已断开");
});

---

使用 TON Connect SDK

React 项目可以使用 TON Connect SDK。UKey Wallet 会作为兼容钱包出现在连接流程中：

npm install @tonconnect/ui-react

import { TonConnectUIProvider, TonConnectButton } from "@tonconnect/ui-react";

function TonConnectShell() {
  return (
    <TonConnectUIProvider manifestUrl="https://sampleapp.example/tonconnect-manifest.json">
      <TonConnectButton />
      <YourApp />
    </TonConnectUIProvider>
  );
}

UKey Wallet 会被 TON Connect SDK 自动检测。