hm-tracking-sdk 0.1.9 → 0.2.1

package/README.md

@@ -1,449 +1,449 @@
-# HM Tracking SDK 使用文档
-
-本文档详细介绍如何使用 HM Tracking SDK，包括初始化、广告业务和支付业务的完整流程。
-
-## 1. 安装
-
-### 建议通过 npm/yarn 安装正式发布的包：
-
-  ```bash
-  # 使用 yarn
-  yarn add hm-tracking-sdk axios crypto-js
-
-  # 或使用 npm
-  npm i hm-tracking-sdk axios crypto-js
-  ```
-
----
-
-## 2. SDK 初始化
-
-- 接口: init()
-
-  ```ts
-  import { HmTrackingSDK, type SDKInitOptions } from "hm-tracking-sdk";
-
-  const options: SDKInitOptions = {
-    // 可选：不传则使用内置默认地址
-    baseURL: "https://your-api.example.com",
-    // 可选：回调校验用，SDK方会提供
-    appId: "app-xxxxxxx",
-
-    // 可选：本地存储 Key 前缀，避免项目间冲突
-    storageKeyPrefix: "your_app_prefix",
-
-    // 可选：浏览器环境下使用，可显式传入自定义用户
-    customUser: {
-      user: {
-        id: 123456789,
-        first_name: "Test",
-        last_name: "User",
-        username: "test_user",
-        language_code: "zh-hans",
-        photo_url: "https://t.me/i/userpic/320/example.svg",
-      },
-      auth_date: Math.floor(Date.now() / 1000),
-      hash: "your_hash_value",
-    },
-  };
-
-  const sdk = new HmTrackingSDK(options);
-  await sdk.init();
-  ```
-
-- 函数说明：初始化 SDK，先创建 HmTrackingSDK 对象，然后调用 init 方法完成初始化。
-- 参数说明: `SDKInitOptions` 初始化SDK时的可选参数，数据结构及内部结构说明为：
-  
-  ```ts
-    export interface SDKInitOptions {
-      /** 自定义接口地址（可选）。不传则使用默认正式环境 */
-      baseURL?: string;
-      appId?: string;   // 可选：回调校验用，SDK方提供
-      notifyUrl?: string; // 可选：SDK 初始化鉴权成功后的服务端回调地址
-       /** 本地存储 Key 前缀，避免冲突 */
-      storageKeyPrefix?: string;
-      /** 自定义用户信息（可选） */
-      customUser?: TelegramUserInfo;
-      /** 可选：TON Connect manifest 文件地址，规则请看5.1.0；未传则使用默认测试清单 */
-      tonConnectManifestUrl?: string;
-    }
-  ```
-
-  - baseURL（可选）
-    - 说明：后端服务地址；不传则使用 SDK 内置默认地址。
-    - 类型：`string`
-  - appId (可选)
-    - 说明：服务器之间用来鉴权，SDK方提供
-    - 类型：`string`
-  - notifyUrl (可选)
-    - 说明：SDK方服务器回调参数
-    - 类型：`string`
-  - storageKeyPrefix（可选）
-    - 说明：本地缓存命名空间前缀；用于隔离不同项目的存储键。
-    - 类型：`string`
-  - customUser（可选）
-    - 说明：自定义用户数据，仅在非 Telegram 环境可用；若不传，SDK 会自动使用“匿名浏览器用户”（基于 Cookie 生成并持久化随机 userId），从而可以直接完成鉴权与后续请求。
-    - 类型：`TelegramUserInfo`
-  - tonConnectManifestUrl（可选）
-    - 说明：TON Connect manifest 文件地址。若不传，SDK 使用默认测试清单：`https://miniapp.spinfi.me/tonconnect-manifest.json`。当小程序部署后需要改为对应链接，具体见`5.1.0`说明
-    - 类型：`string`
-- 返回值：`Promise<void>`。
-  
-### 2.1 初始化成功通知调用说明（服务端回调）
-
-- 触发时机：当 SDK 调用 `init()` 完成鉴权后，服务端会读取鉴权请求体中的 `notifyUrl`，并向该地址发起一次通知，上报获取到的用户信息。
-- 通知参数：可能是 JSON 对象或一个加密后的字符串。
-  - JSON 示例：
-  
-  ```json
-  {
-    "user": {
-      "id": 7506466780,
-      "first_name": "first",
-      "last_name": "name",
-      "username": "nickname1992",
-      "language_code": "zh",
-      "allows_write_to_pm": true,
-      "is_premium": false,
-      "photo_url": "https://t.me/i/userpic/320/uLzA4KyVzKwd0vi6Uvupe6U2mdnVEQOIbUZbFTQff6B3UhjRpQObL9I8Nq81G0ln.svg"
-    },
-    "auth_date": 1735792133,
-    "hash": "a9d2d7c1b066bebb73c170006dc474061d7601183b388b037936aa7cb6620acf",
-    "chat_instance": "-2254244616056098321",
-    "chat_type": "sender",
-    "start_param": "..."
-  }
-  ```
-
-- 若为加密字符串：请与服务端约定解密方式及签名校验流程。
-
-### 2.2 环境
-
-- Telegram 环境
-  - SDK 自动读取当前Telegram用户的信息。
-  - 无需传入 `customUser`；若 Telegram 用户读取失败，SDK 会抛错提示。
-- 浏览器环境（非 Telegram）
-  - 默认行为：若未传 `customUser`，SDK 会使用“匿名浏览器用户”：
-    - 首次访问生成随机 `userId`，存入 Cookie（如 `tg_tracking_uid`），后续复用。
-    - 便于无登录状态下完成鉴权，拿到 token 后再进行广告或调试。
-  - 自定义用户：也可传入 `customUser` 替代匿名用户。
-
-### 2.3 环境判断
-
-- 接口: isTelegramEnv()
-
-  ```ts
-  import { isTelegramEnv } from "hm-tracking-sdk";
-
-  if (isTelegramEnv()) {
-    // Telegram WebApp 环境
-  } else {
-    // 浏览器/其他环境
-  }
-  ```
-
-  - 函数说明：判断是否是Telegram环境。
-  - 返回值：`boolean`。
-
----
-
-## 3. 获取Telegram用户信息
-
-- 接口: getTelegramUserUnsafe()
-
-  ```ts
-  import { getTelegramUserUnsafe, type TelegramUserInfo } from "hm-tracking-sdk";
-
-  const user: TelegramUserInfo | null = getTelegramUserUnsafe();
-  ```
-
-  - 函数说明：在 Telegram 环境下返回 `TelegramUserInfo`；获取失败返回 `null`。
-  - 返回值：`TelegramUserInfo | null`，数据结构为：
-    
-    ```ts
-    export interface TelegramUserInfo {
-      user: {
-        id: number;
-        first_name?: string;
-        last_name?: string;
-        username?: string;
-        photo_url?: string;
-        language_code?: string;
-        allows_write_to_pm?: boolean;
-        is_premium?: boolean;
-      };
-      auth_date?: number;
-      hash?: string;
-      start_param?: string;
-      chat_type?: string;
-      chat_instance?: string;
-      [key: string]: unknown;
-    }
-    ```
-
-- 环境要求：仅 Telegram WebApp 可用；在浏览器环境（非 Telegram）将返回 `null`。
-
----
-
-## 4. 广告业务
-
-### 4.1 展示广告
-
-- 接口: showHmAdByPosition()
-
-  ```ts
-  await sdk.showHmAdByPosition(adPositionName, {
-    onSuccess: (result) => {
-      console.log("广告观看完成", result);
-    },
-    onError: (error) => {
-      console.error("广告展示失败:", error);
-    },
-  });
-  ```
-
-- 函数说明：根据广告位名称展示广告。
-- 参数说明
-  - adPositionName（必填）
-    - 说明：广告位名称，需要根据业务进行申请，具体请联系SDK开发者，使用示例值进行测试。
-    - 类型：`string`
-    - 示例值：
-      - `game_rewarded_ad_position`
-  - callbacks
-    - 说明：广告展示成功/失败的回调。
-    - 类型：
-  
-      ```ts
-      interface AdCallbacks {
-        onSuccess?: (result?: unknown) => void | Promise<void>;
-        onError?: (error: unknown) => void | Promise<void>;
-      }
-      ```
-      
-- 返回值：`Promise<void>`。失败时抛出异常；如提供 `callbacks`，会触发 `onError`。
-  
-  说明：SDK 会根据根据广告位名称获取相关广告配置并完成展示。
-
----
-
-## 5. 支付业务
-
-支付仅支持在 Telegram WebApp 内使用。
-
-### 5.1 TON钱包相关API
-
-#### 5.1.0 配置 tonconnect-manifest
-
-- 作用
-  - TON Connect 要求每个 dApp（小程序） 提供 `tonconnect-manifest.json`。钱包在连接前会读取该文件以展示 dApp 名称、图标，并校验来源。
-- 托管与访问要求
-  - 将该 JSON 文件托管在公网可访问的 HTTPS 地址（建议：`https://your-domain.com/tonconnect-manifest.json`，放在站点根路径）。
-  - 文件及其中引用的资源（如图标）须可在任意来源公开访问，避免 CORS 限制。
-  - 必须能通过 GET 直接获取，无需鉴权或特殊请求头。
-  - `url` 字段请避免末尾斜杠，例如使用 `https://mydapp.com` 而非 `https://mydapp.com/`。
-- 最小示例
-
-  ```json
-  {
-    "url": "https://your-domain.com",
-    "name": "Your DApp Name",
-    "iconUrl": "https://your-domain.com/icons/tonconnect-icon.png"
-  }
-  ```
-
-- 字段要求
-  - `url`（必填）：应用基础 URL，点击钱包内图标时用于打开应用；避免末尾斜杠。
-  - `name`（必填）：应用名称。
-  - `iconUrl`（必填）：应用图标 URL，仅支持 PNG 或 ICO，不支持 SVG；建议 180x180 PNG。
-  - `termsOfUseUrl`（可选）：条款页 URL。
-  - `privacyPolicyUrl`（可选）：隐私政策 URL。
-- SDK 行为与配置
-  - 默认使用测试清单：`https://miniapp.spinfi.me/tonconnect-manifest.json`。
-  - 生产环境建议通过初始化参数传入：
-
-    ```ts
-    const sdk = new HmTrackingSDK({
-      tonConnectManifestUrl: "https://your-domain.com/tonconnect-manifest.json",
-      // 其他可选项...
-    });
-    ```
-
-- 自检
-  - 在浏览器访问你的 manifest URL，确认返回 200 且 JSON 内容正确。
-  - 打开连接钱包弹窗，应显示你在 manifest 中配置的名称与图标。
-
-#### 5.1.1 钱包是否链接
-
-- 接口: isWalletConnected()
-
-  ```ts
-  sdk.isWalletConnected(): boolean
-  ```
-
-- 函数说明：同步检查是否已连接 TON 钱包；
-- 返回值：`boolean`。
-
-#### 5.1.2 链接钱包
-
-- 接口: connectWallet()
-
-  ```ts
-  sdk.connectWallet(): Promise<boolean>
-  ```
-
-- 函数说明：发起连接 TON 钱包；
-- 返回值：`Promise<boolean>` 表示是否连接成功。
-
-#### 5.1.3 断开钱包链接
-
-- 接口: disconnectWallet()
-
-  ```ts
-  sdk.disconnectWallet(): Promise<boolean>
-  ```
-
-- 函数说明：断开已连接的钱包；
-- 返回值：`Promise<boolean>`，true 表示已断开或原本未连接；false 表示断开失败。
-
-### 5.2 支付
-
-#### 5.2.1 获取支持的支付方式
-
-- 接口: getSupportedPayModes()
-
-  ```ts
-  sdk.getSupportedPayModes(): Promise<MerchantPayModeListData>
-  ```
-
-- 函数说明：获取当前支持的币种及汇率配置；
-- 返回值说明：`Promise<MerchantPayModeListData>`，见下方类型定义。
-
-  ```ts
-  interface MerchantPayModeListData {
-    payModeList: MerchantPayModeItem[];
-  }
-
-  interface MerchantPayModeItem {
-    id: number;
-    title: string;
-    name: string;   // 币种: 'USDT' | 'TON' | 'STARS'
-    rate: number;   // 汇率
-    nameDesc: string;
-  }
-  ```
-
-#### 5.2.2 创建并支付订单
-
-- 接口: payByMerchant()
-
-  ```ts
-
-  // 创建并支付订单
-  const params: MerchantPayCreateRequest = {
-    currencyName: "TON",          // "TON" | "USDT" | "STARS"
-    amount: 10.5,                  // 支付金额
-    outTradeNo: `order_${Date.now()}`, // 自定义订单号
-    notifyUrl: "https://your-server.com/payment-callback",
-    attach: JSON.stringify({ userId: "123", itemId: "456" })
-  };
-  const result: MerchantPayFinishResponseData = await sdk.payByMerchant(params);
-  ```
-
-- 函数说明：创建支付订单并根据币种发起支付流程（STARS、TON/USDT 链上交易）；
-
-- 参数说明：
-  
-  ```ts
-  interface MerchantPayCreateRequest {
-    currencyName: string; // "USDT" | "TON" | "STARS"
-    amount: number;      // 支付金额
-    outTradeNo: string;  // 商户订单号
-    notifyUrl: string;   // 服务端支付回调地址
-    attach: string;      // 附加信息，通常使用 JSON.stringify
-  }
-  ```
-
-- 返回值数据结构：
-  
-  ```ts
-  export interface MerchantPayOrderBase {
-    orderSn: string;
-    transactionSn: string;
-    outTradeNo: string;
-    price: number | string;
-    count: number;
-    totalPrice: number | string;
-    currencyId: number;
-    currencyName: string;
-    currencyRate: number;
-    currencyAmount: number | string;
-    payUrl: string | null;
-    payExpireDatetime: string;
-    payDatetime: string | null;
-    finishDatetime: string | null;
-    description: string;
-    status: number;
-    statusDesc: string;
-    closeCode: string | null;
-    closeCodeDesc: string | null;
-    createDatetime: string;
-    updateDatetime: string;
-    transferHash: string | null;
-    transactionHash: string | null;
-    transactionLt: string | null;
-  }
-  ```
-
-  ```ts
-  // 支付完成回调返回的订单结果
-  type MerchantPayFinishResponseData = MerchantPayOrderBase;
-  ```
-
-#### 5.2.3 查询支付结果
-
-- 接口: merchantPayQueryResult()
-
-  ```ts
-  sdk.merchantPayQueryResult(data: MerchantPayQueryResultRequest): Promise<MerchantPayQueryResultResponseData>
-  ```
-
-- 函数说明：通过系统订单号 `orderSn` 或商户订单号 `outTradeNo` 查询订单最新结果；
-- 参数说明：`MerchantPayQueryResultRequest`，见下方类型:
-  
-   ```ts
-  interface MerchantPayQueryResultRequest {
-    orderSn?: string;
-    outTradeNo?: string;
-  }
-  ```
-
-- 返回值说明：`Promise<MerchantPayQueryResultResponseData>`，同 `MerchantPayOrderBase`。
-
-  ```ts
-  type MerchantPayQueryResultResponseData = MerchantPayOrderBase;
-  ```
-
-#### 5.2.4 支付结果通知（服务端回调）
-
-- 说明：当你的服务接收 `notifyUrl` 的支付结果通知时，应返回统一响应结构，以便平台确认处理状态。
-- 返回值示例：
-
-```json
-{
-  "code": 1,
-  "msg": "通知支付结果成功",
-  "timestamp": 1756442387,
-  "datetime": "2025-08-29T04:39:47.518Z",
-  "data": {}
-}
-```
-
-- 约定说明：
-  - **code**: 1 表示成功；非 1 表示失败
-  - **msg**: 描述信息
-  - **timestamp/datetime**: 服务端时间
-  - **data**: 业务扩展字段（本例为空对象）
-
----
-
-
+# HM Tracking SDK 使用文档
+
+本文档详细介绍如何使用 HM Tracking SDK，包括初始化、广告业务和支付业务的完整流程。
+
+## 1. 安装
+
+### 建议通过 npm/yarn 安装正式发布的包：
+
+  ```bash
+  # 使用 yarn
+  yarn add hm-tracking-sdk axios crypto-js
+
+  # 或使用 npm
+  npm i hm-tracking-sdk axios crypto-js
+  ```
+
+---
+
+## 2. SDK 初始化
+
+- 接口: init()
+
+  ```ts
+  import { HmTrackingSDK, type SDKInitOptions } from "hm-tracking-sdk";
+
+  const options: SDKInitOptions = {
+    // 可选：不传则使用内置默认地址
+    baseURL: "https://your-api.example.com",
+    // 可选：回调校验用，SDK方会提供
+    appId: "app-xxxxxxx",
+
+    // 可选：本地存储 Key 前缀，避免项目间冲突
+    storageKeyPrefix: "your_app_prefix",
+
+    // 可选：浏览器环境下使用，可显式传入自定义用户
+    customUser: {
+      user: {
+        id: 123456789,
+        firstName: "Test",
+        lastName: "User",
+        username: "test_user",
+        languageCode: "zh-hans",
+        photoUrl: "https://t.me/i/userpic/320/example.svg",
+      },
+      authDate: Math.floor(Date.now() / 1000),
+      hash: "your_hash_value",
+    },
+  };
+
+  const sdk = new HmTrackingSDK(options);
+  await sdk.init();
+  ```
+
+- 函数说明：初始化 SDK，先创建 HmTrackingSDK 对象，然后调用 init 方法完成初始化。
+- 参数说明: `SDKInitOptions` 初始化SDK时的可选参数，数据结构及内部结构说明为：
+  
+  ```ts
+    export interface SDKInitOptions {
+      /** 自定义接口地址（可选）。不传则使用默认正式环境 */
+      baseURL?: string;
+      appId?: string;   // 可选：回调校验用，SDK方提供
+      notifyUrl?: string; // 可选：SDK 初始化鉴权成功后的服务端回调地址
+       /** 本地存储 Key 前缀，避免冲突 */
+      storageKeyPrefix?: string;
+      /** 自定义用户信息（可选） */
+      customUser?: TelegramUserInfo;
+      /** 可选：TON Connect manifest 文件地址，规则请看5.1.0；未传则使用默认测试清单 */
+      tonConnectManifestUrl?: string;
+    }
+  ```
+
+  - baseURL（可选）
+    - 说明：后端服务地址；不传则使用 SDK 内置默认地址。
+    - 类型：`string`
+  - appId (可选)
+    - 说明：服务器之间用来鉴权，SDK方提供
+    - 类型：`string`
+  - notifyUrl (可选)
+    - 说明：SDK方服务器回调参数
+    - 类型：`string`
+  - storageKeyPrefix（可选）
+    - 说明：本地缓存命名空间前缀；用于隔离不同项目的存储键。
+    - 类型：`string`
+  - customUser（可选）
+    - 说明：自定义用户数据，仅在非 Telegram 环境可用；若不传，SDK 会自动使用“匿名浏览器用户”（基于 Cookie 生成并持久化随机 userId），从而可以直接完成鉴权与后续请求。
+    - 类型：`TelegramUserInfo`
+  - tonConnectManifestUrl（可选）
+    - 说明：TON Connect manifest 文件地址。若不传，SDK 使用默认测试清单：`https://miniapp.spinfi.me/tonconnect-manifest.json`。当小程序部署后需要改为对应链接，具体见`5.1.0`说明
+    - 类型：`string`
+- 返回值：`Promise<void>`。
+  
+### 2.1 初始化成功通知调用说明（服务端回调）
+
+- 触发时机：当 SDK 调用 `init()` 完成鉴权后，服务端会读取鉴权请求体中的 `notifyUrl`，并向该地址发起一次通知，上报获取到的用户信息。
+- 通知参数：可能是 JSON 对象或一个加密后的字符串。
+  - JSON 示例：
+  
+  ```json
+  {
+    "user": {
+      "id": 7506466780,
+      "firstName": "first",
+      "lastName": "name",
+      "username": "nickname1992",
+      "languageCode": "zh",
+      "allowsWriteToPm": true,
+      "isPremium": false,
+      "photoUrl": "https://t.me/i/userpic/320/uLzA4KyVzKwd0vi6Uvupe6U2mdnVEQOIbUZbFTQff6B3UhjRpQObL9I8Nq81G0ln.svg"
+    },
+    "authDate": 1735792133,
+    "hash": "a9d2d7c1b066bebb73c170006dc474061d7601183b388b037936aa7cb6620acf",
+    "chatInstance": "-2254244616056098321",
+    "chatType": "sender",
+    "startParam": "..."
+  }
+  ```
+
+- 若为加密字符串：请与服务端约定解密方式及签名校验流程。
+
+### 2.2 环境
+
+- Telegram 环境
+  - SDK 自动读取当前Telegram用户的信息。
+  - 无需传入 `customUser`；若 Telegram 用户读取失败，SDK 会抛错提示。
+- 浏览器环境（非 Telegram）
+  - 默认行为：若未传 `customUser`，SDK 会使用“匿名浏览器用户”：
+    - 首次访问生成随机 `userId`，存入 Cookie（如 `tg_tracking_uid`），后续复用。
+    - 便于无登录状态下完成鉴权，拿到 token 后再进行广告或调试。
+  - 自定义用户：也可传入 `customUser` 替代匿名用户。
+
+### 2.3 环境判断
+
+- 接口: isTelegramEnv()
+
+  ```ts
+  import { isTelegramEnv } from "hm-tracking-sdk";
+
+  if (isTelegramEnv()) {
+    // Telegram WebApp 环境
+  } else {
+    // 浏览器/其他环境
+  }
+  ```
+
+  - 函数说明：判断是否是Telegram环境。
+  - 返回值：`boolean`。
+
+---
+
+## 3. 获取Telegram用户信息
+
+- 接口: getTelegramUserUnsafe()
+
+  ```ts
+  import { getTelegramUserUnsafe, type TelegramUserInfo } from "hm-tracking-sdk";
+
+  const user: TelegramUserInfo | null = getTelegramUserUnsafe();
+  ```
+
+  - 函数说明：在 Telegram 环境下返回 `TelegramUserInfo`；获取失败返回 `null`。
+  - 返回值：`TelegramUserInfo | null`，数据结构为：
+    
+    ```ts
+    export interface TelegramUserInfo {
+      user: {
+        id: number;
+        firstName?: string;
+        lastName?: string;
+        username?: string;
+        photoUrl?: string;
+        languageCode?: string;
+        allowsWriteToPm?: boolean;
+        isPremium?: boolean;
+      };
+      authDate?: number;
+      hash?: string;
+      startParam?: string;
+      chatType?: string;
+      chatInstance?: string;
+      [key: string]: unknown;
+    }
+    ```
+
+- 环境要求：仅 Telegram WebApp 可用；在浏览器环境（非 Telegram）将返回 `null`。
+
+---
+
+## 4. 广告业务
+
+### 4.1 展示广告
+
+- 接口: showHmAdByPosition()
+
+  ```ts
+  await sdk.showHmAdByPosition(adPositionName, {
+    onSuccess: (result) => {
+      console.log("广告观看完成", result);
+    },
+    onError: (error) => {
+      console.error("广告展示失败:", error);
+    },
+  });
+  ```
+
+- 函数说明：根据广告位名称展示广告。
+- 参数说明
+  - adPositionName（必填）
+    - 说明：广告位名称，需要根据业务进行申请，具体请联系SDK开发者，使用示例值进行测试。
+    - 类型：`string`
+    - 示例值：
+      - `game_rewarded_ad_position`
+  - callbacks
+    - 说明：广告展示成功/失败的回调。
+    - 类型：
+  
+      ```ts
+      interface AdCallbacks {
+        onSuccess?: (result?: unknown) => void | Promise<void>;
+        onError?: (error: unknown) => void | Promise<void>;
+      }
+      ```
+      
+- 返回值：`Promise<void>`。失败时抛出异常；如提供 `callbacks`，会触发 `onError`。
+  
+  说明：SDK 会根据根据广告位名称获取相关广告配置并完成展示。
+
+---
+
+## 5. 支付业务
+
+支付仅支持在 Telegram WebApp 内使用。
+
+### 5.1 TON钱包相关API
+
+#### 5.1.0 配置 tonconnect-manifest
+
+- 作用
+  - TON Connect 要求每个 dApp（小程序） 提供 `tonconnect-manifest.json`。钱包在连接前会读取该文件以展示 dApp 名称、图标，并校验来源。
+- 托管与访问要求
+  - 将该 JSON 文件托管在公网可访问的 HTTPS 地址（建议：`https://your-domain.com/tonconnect-manifest.json`，放在站点根路径）。
+  - 文件及其中引用的资源（如图标）须可在任意来源公开访问，避免 CORS 限制。
+  - 必须能通过 GET 直接获取，无需鉴权或特殊请求头。
+  - `url` 字段请避免末尾斜杠，例如使用 `https://mydapp.com` 而非 `https://mydapp.com/`。
+- 最小示例
+
+  ```json
+  {
+    "url": "https://your-domain.com",
+    "name": "Your DApp Name",
+    "iconUrl": "https://your-domain.com/icons/tonconnect-icon.png"
+  }
+  ```
+
+- 字段要求
+  - `url`（必填）：应用基础 URL，点击钱包内图标时用于打开应用；避免末尾斜杠。
+  - `name`（必填）：应用名称。
+  - `iconUrl`（必填）：应用图标 URL，仅支持 PNG 或 ICO，不支持 SVG；建议 180x180 PNG。
+  - `termsOfUseUrl`（可选）：条款页 URL。
+  - `privacyPolicyUrl`（可选）：隐私政策 URL。
+- SDK 行为与配置
+  - 默认使用测试清单：`https://miniapp.spinfi.me/tonconnect-manifest.json`。
+  - 生产环境建议通过初始化参数传入：
+
+    ```ts
+    const sdk = new HmTrackingSDK({
+      tonConnectManifestUrl: "https://your-domain.com/tonconnect-manifest.json",
+      // 其他可选项...
+    });
+    ```
+
+- 自检
+  - 在浏览器访问你的 manifest URL，确认返回 200 且 JSON 内容正确。
+  - 打开连接钱包弹窗，应显示你在 manifest 中配置的名称与图标。
+
+#### 5.1.1 钱包是否链接
+
+- 接口: isWalletConnected()
+
+  ```ts
+  sdk.isWalletConnected(): boolean
+  ```
+
+- 函数说明：同步检查是否已连接 TON 钱包；
+- 返回值：`boolean`。
+
+#### 5.1.2 链接钱包
+
+- 接口: connectWallet()
+
+  ```ts
+  sdk.connectWallet(): Promise<boolean>
+  ```
+
+- 函数说明：发起连接 TON 钱包；
+- 返回值：`Promise<boolean>` 表示是否连接成功。
+
+#### 5.1.3 断开钱包链接
+
+- 接口: disconnectWallet()
+
+  ```ts
+  sdk.disconnectWallet(): Promise<boolean>
+  ```
+
+- 函数说明：断开已连接的钱包；
+- 返回值：`Promise<boolean>`，true 表示已断开或原本未连接；false 表示断开失败。
+
+### 5.2 支付
+
+#### 5.2.1 获取支持的支付方式
+
+- 接口: getSupportedPayModes()
+
+  ```ts
+  sdk.getSupportedPayModes(): Promise<MerchantPayModeListData>
+  ```
+
+- 函数说明：获取当前支持的币种及汇率配置；
+- 返回值说明：`Promise<MerchantPayModeListData>`，见下方类型定义。
+
+  ```ts
+  interface MerchantPayModeListData {
+    payModeList: MerchantPayModeItem[];
+  }
+
+  interface MerchantPayModeItem {
+    id: number;
+    title: string;
+    name: string;   // 币种: 'USDT' | 'TON' | 'STARS'
+    rate: number;   // 汇率
+    nameDesc: string;
+  }
+  ```
+
+#### 5.2.2 创建并支付订单
+
+- 接口: payByMerchant()
+
+  ```ts
+
+  // 创建并支付订单
+  const params: MerchantPayCreateRequest = {
+    currencyName: "TON",          // "TON" | "USDT" | "STARS"
+    amount: 10.5,                  // 支付金额
+    outTradeNo: `order_${Date.now()}`, // 自定义订单号
+    notifyUrl: "https://your-server.com/payment-callback",
+    attach: JSON.stringify({ userId: "123", itemId: "456" })
+  };
+  const result: MerchantPayFinishResponseData = await sdk.payByMerchant(params);
+  ```
+
+- 函数说明：创建支付订单并根据币种发起支付流程（STARS、TON/USDT 链上交易）；
+
+- 参数说明：
+  
+  ```ts
+  interface MerchantPayCreateRequest {
+    currencyName: string; // "USDT" | "TON" | "STARS"
+    amount: number;      // 支付金额
+    outTradeNo: string;  // 商户订单号
+    notifyUrl: string;   // 服务端支付回调地址
+    attach: string;      // 附加信息，通常使用 JSON.stringify
+  }
+  ```
+
+- 返回值数据结构：
+  
+  ```ts
+  export interface MerchantPayOrderBase {
+    orderSn: string;
+    transactionSn: string;
+    outTradeNo: string;
+    price: number | string;
+    count: number;
+    totalPrice: number | string;
+    currencyId: number;
+    currencyName: string;
+    currencyRate: number;
+    currencyAmount: number | string;
+    payUrl: string | null;
+    payExpireDatetime: string;
+    payDatetime: string | null;
+    finishDatetime: string | null;
+    description: string;
+    status: number;
+    statusDesc: string;
+    closeCode: string | null;
+    closeCodeDesc: string | null;
+    createDatetime: string;
+    updateDatetime: string;
+    transferHash: string | null;
+    transactionHash: string | null;
+    transactionLt: string | null;
+  }
+  ```
+
+  ```ts
+  // 支付完成回调返回的订单结果
+  type MerchantPayFinishResponseData = MerchantPayOrderBase;
+  ```
+
+#### 5.2.3 查询支付结果
+
+- 接口: merchantPayQueryResult()
+
+  ```ts
+  sdk.merchantPayQueryResult(data: MerchantPayQueryResultRequest): Promise<MerchantPayQueryResultResponseData>
+  ```
+
+- 函数说明：通过系统订单号 `orderSn` 或商户订单号 `outTradeNo` 查询订单最新结果；
+- 参数说明：`MerchantPayQueryResultRequest`，见下方类型:
+  
+   ```ts
+  interface MerchantPayQueryResultRequest {
+    orderSn?: string;
+    outTradeNo?: string;
+  }
+  ```
+
+- 返回值说明：`Promise<MerchantPayQueryResultResponseData>`，同 `MerchantPayOrderBase`。
+
+  ```ts
+  type MerchantPayQueryResultResponseData = MerchantPayOrderBase;
+  ```
+
+#### 5.2.4 支付结果通知（服务端回调）
+
+- 说明：当你的服务接收 `notifyUrl` 的支付结果通知时，应返回统一响应结构，以便平台确认处理状态。
+- 返回值示例：
+
+```json
+{
+  "code": 1,
+  "msg": "通知支付结果成功",
+  "timestamp": 1756442387,
+  "datetime": "2025-08-29T04:39:47.518Z",
+  "data": {}
+}
+```
+
+- 约定说明：
+  - **code**: 1 表示成功；非 1 表示失败
+  - **msg**: 描述信息
+  - **timestamp/datetime**: 服务端时间
+  - **data**: 业务扩展字段（本例为空对象）
+
+---
+
+