hm-tracking-sdk 0.1.6 → 0.1.9

package/README.md

@@ -26,6 +26,8 @@
   const options: SDKInitOptions = {
     // 可选：不传则使用内置默认地址
     baseURL: "https://your-api.example.com",
+    // 可选：回调校验用，SDK方会提供
+    appId: "app-xxxxxxx",
 
     // 可选：本地存储 Key 前缀，避免项目间冲突
     storageKeyPrefix: "your_app_prefix",
@@ -34,12 +36,13 @@
     customUser: {
       user: {
         id: 123456789,
-        firstName: "Test",
-        lastName: "User",
+        first_name: "Test",
+        last_name: "User",
         username: "test_user",
-        languageCode: "zh-hans",
+        language_code: "zh-hans",
+        photo_url: "https://t.me/i/userpic/320/example.svg",
       },
-      authDate: new Date().toISOString(),
+      auth_date: Math.floor(Date.now() / 1000),
       hash: "your_hash_value",
     },
   };
@@ -55,12 +58,14 @@
     export interface SDKInitOptions {
       /** 自定义接口地址（可选）。不传则使用默认正式环境 */
       baseURL?: string;
-      appId?: string;   // 可选：回调校验用
+      appId?: string;   // 可选：回调校验用，SDK方提供
       notifyUrl?: string; // 可选：SDK 初始化鉴权成功后的服务端回调地址
        /** 本地存储 Key 前缀，避免冲突 */
       storageKeyPrefix?: string;
       /** 自定义用户信息（可选） */
       customUser?: TelegramUserInfo;
+      /** 可选：TON Connect manifest 文件地址，规则请看5.1.0；未传则使用默认测试清单 */
+      tonConnectManifestUrl?: string;
     }
   ```
 
@@ -68,7 +73,7 @@
     - 说明：后端服务地址；不传则使用 SDK 内置默认地址。
     - 类型：`string`
   - appId (可选)
-    - 说明：服务器之间用来鉴权
+    - 说明：服务器之间用来鉴权，SDK方提供
     - 类型：`string`
   - notifyUrl (可选)
     - 说明：SDK方服务器回调参数
@@ -79,6 +84,9 @@
   - 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 初始化成功通知调用说明（服务端回调）
@@ -88,7 +96,23 @@
   - JSON 示例：
   
   ```json
-  {"id":"7506466780","first_name":"hong","last_name":"tang","nickname":"hongtang","username":"tanghong1992","language_code":"zh","allows_write_to_pm":1,"auth_date":"2025-04-08T02:08:53.000Z","hash":"a9d2d7c1b066bebb73c170006dc474061d7601183b388b037936aa7cb6620acf","chat_instance":"-2254244616056093259","is_premium_user":0,"photo_url":"https://t.me/i/userpic/320/uLzA4KyVzKwd0vi6Uvupe6U2mdnVEQOIbUZbFTQff6B3UhjRpQObL9I8Nq81G0ln.svg"}
+  {
+    "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": "..."
+  }
   ```
 
 - 若为加密字符串：请与服务端约定解密方式及签名校验流程。
@@ -138,14 +162,21 @@
     
     ```ts
     export interface TelegramUserInfo {
-      id?: number;
-      first_name?: string;
-      last_name?: string;
-      username?: string;
-      language_code?: string;
-      allows_write_to_pm?: boolean;
+      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;
     }
     ```
@@ -201,6 +232,46 @@
 
 ### 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()

package/dist/browser/index.es.js

@@ -4374,18 +4374,19 @@ function getTelegramUserUnsafe() {
     return !r.user || !r.user.id ? null : {
       user: {
         id: r.user.id,
-        firstName: r.user.first_name || "",
-        lastName: r.user.last_name || "",
+        first_name: r.user.first_name || "",
+        last_name: r.user.last_name || "",
         username: r.user.username,
-        languageCode: r.user.language_code,
-        isPremium: r.user.is_premium || !1,
-        allowsWriteToPm: r.user.allows_write_to_pm || !1
+        photo_url: r.user.photo_url,
+        language_code: r.user.language_code,
+        allows_write_to_pm: r.user.allows_write_to_pm || !1,
+        is_premium: r.user.is_premium || !1
       },
-      authDate: (/* @__PURE__ */ new Date()).toISOString(),
+      auth_date: r.auth_date,
       hash: r.hash || "",
-      startParam: r.start_param,
-      chatType: r.chat_type,
-      chatInstance: r.chat_instance
+      start_param: r.start_param,
+      chat_type: r.chat_type,
+      chat_instance: r.chat_instance
     };
   } catch {
     return null;
@@ -4425,36 +4426,35 @@ function getAnonymousBrowserUser(r = "tg_tracking_uid") {
   return {
     user: {
       id: d,
-      firstName: "Guest",
-      lastName: "",
+      first_name: "Guest",
+      last_name: "",
       username: `guest_${f.slice(-6)}`,
-      languageCode: m.toLowerCase(),
-      isPremium: !1,
-      allowsWriteToPm: !1
+      language_code: m.toLowerCase(),
+      allows_write_to_pm: !1
     },
-    authDate: (/* @__PURE__ */ new Date()).toISOString(),
+    auth_date: Math.floor(Date.now() / 1e3),
     hash: "anonymous_cookie_user",
-    startParam: "browser_guest",
-    chatType: "sender",
-    chatInstance: ""
+    start_param: "browser_guest",
+    chat_type: "sender",
+    chat_instance: ""
   };
 }
 function getDefaultMockUser() {
   return {
     user: {
       id: 2077220643,
-      firstName: "Mock",
-      lastName: "User",
+      first_name: "Mock",
+      last_name: "User",
       username: "mock_user_demo",
-      languageCode: "zh-hans",
-      isPremium: !0,
-      allowsWriteToPm: !0
+      language_code: "zh-hans",
+      allows_write_to_pm: !0,
+      is_premium: !0
     },
-    authDate: (/* @__PURE__ */ new Date()).toISOString(),
+    auth_date: Math.floor(Date.now() / 1e3),
     hash: "mock_hash_for_demo_purpose",
-    startParam: "demo_start_param",
-    chatType: "sender",
-    chatInstance: "-245769840322609948"
+    start_param: "demo_start_param",
+    chat_type: "sender",
+    chat_instance: "-245769840322609948"
   };
 }
 var naclUtil$1 = { exports: {} }, naclUtil = naclUtil$1.exports, hasRequiredNaclUtil;
@@ -35925,14 +35925,16 @@ class TonConnectUI {
   }
 }
 const DEFAULT_MANIFEST_URL = "https://miniapp.spinfi.me/tonconnect-manifest.json";
-let tonConnectUIInstance = null;
+let tonConnectUIInstance = null, currentManifestUrl = null;
 class DefaultTonWalletProvider {
-  constructor(f) {
-    if (this.bindWalletCallback = f, !tonConnectUIInstance)
+  constructor(f, d) {
+    this.bindWalletCallback = d;
+    const m = f || DEFAULT_MANIFEST_URL;
+    if (!tonConnectUIInstance || currentManifestUrl !== m)
       try {
         tonConnectUIInstance = new TonConnectUI({
-          manifestUrl: DEFAULT_MANIFEST_URL
-        });
+          manifestUrl: m
+        }), currentManifestUrl = m;
       } catch {
         throw new Error("创建TonConnectUI实例失败");
       }
@@ -36029,7 +36031,10 @@ class HmTrackingSDK {
       onAuthError: () => this.clearAuth(),
       baseURL: m,
       getAppId: () => this.options && this.options.appId || null
-    }), this.api = new APIService(this.http), this.hmAdManager = new HmAdManager({ autoInjectScript: !0 }), this.adMonitor = new AdMonitor((v) => this.api.adMonitor(v)), this.tonWallet = new DefaultTonWalletProvider(this.bindWallet.bind(this));
+    }), this.api = new APIService(this.http), this.hmAdManager = new HmAdManager({ autoInjectScript: !0 }), this.adMonitor = new AdMonitor((v) => this.api.adMonitor(v)), this.tonWallet = new DefaultTonWalletProvider(
+      d.tonConnectManifestUrl,
+      this.bindWallet.bind(this)
+    );
   }
   async init() {
     const f = isTelegramEnv();