hm-tracking-sdk 0.1.5 → 0.1.8

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",
@@ -55,25 +57,50 @@
     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
+  {"id":"7506466780","first_name":"first","last_name":"name","nickname":"nickname","username":"nickname1992","language_code":"zh","allows_write_to_pm":1,"auth_date":"2025-04-08T02:08:53.000Z","hash":"a9d2d7c1b066bebb73c170006dc474061d7601183b388b037936aa7cb6620acf","chat_instance":"-2254244616056098321","is_premium_user":0,"photo_url":"https://t.me/i/userpic/320/uLzA4KyVzKwd0vi6Uvupe6U2mdnVEQOIbUZbFTQff6B3UhjRpQObL9I8Nq81G0ln.svg"}
+  ```
+
+- 若为加密字符串：请与服务端约定解密方式及签名校验流程。
 
-### 2.1 环境
+### 2.2 环境
 
 - Telegram 环境
   - SDK 自动读取当前Telegram用户的信息。
@@ -84,7 +111,7 @@
     - 便于无登录状态下完成鉴权，拿到 token 后再进行广告或调试。
   - 自定义用户：也可传入 `customUser` 替代匿名用户。
 
-### 2.2 环境判断
+### 2.3 环境判断
 
 - 接口: isTelegramEnv()
 
@@ -181,6 +208,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()
@@ -352,3 +419,7 @@
   - **msg**: 描述信息
   - **timestamp/datetime**: 服务端时间
   - **data**: 业务扩展字段（本例为空对象）
+
+---
+
+

package/dist/browser/index.es.js

@@ -2855,10 +2855,11 @@ class HttpClient {
       const v = this.options.getToken();
       if (v) {
         m.headers = m.headers || {};
-        const g = `Bearer ${v}`;
-        m.headers.Authorization = g;
+        const w = `Bearer ${v}`;
+        m.headers.Authorization = w;
       }
-      return m;
+      const g = this.options.getAppId ? this.options.getAppId() : null;
+      return g && (m.headers = m.headers || {}, m.headers["hm-app-id"] = String(g)), m;
     }), this.instance.interceptors.response.use(
       (m) => m,
       (m) => (m.response && m.response.status === 401 && this.options.onAuthError && this.options.onAuthError(), Promise.reject(m))
@@ -35924,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实例失败");
       }
@@ -36026,8 +36029,12 @@ class HmTrackingSDK {
     this.http = new HttpClient({
       getToken: () => this.token,
       onAuthError: () => this.clearAuth(),
-      baseURL: m
-    }), 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));
+      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(
+      d.tonConnectManifestUrl,
+      this.bindWallet.bind(this)
+    );
   }
   async init() {
     const f = isTelegramEnv();
@@ -36050,15 +36057,19 @@ class HmTrackingSDK {
    * 调用 /user/auth 并持久化 token
    */
   async auth() {
-    var f;
+    var f, d;
     try {
-      const d = await this.api.auth(this.user);
-      if (d.code !== 1) throw new Error(d.msg || "鉴权失败");
-      const m = (f = d.data) == null ? void 0 : f.token;
-      if (!m) throw new Error("鉴权未返回 token");
-      this.token = m, this.storage.set("token", m);
-    } catch (d) {
-      throw d;
+      const m = {
+        ...this.user
+      }, v = (f = this.options) == null ? void 0 : f.notifyUrl;
+      v && (m.notifyUrl = v);
+      const g = await this.api.auth(m);
+      if (g.code !== 1) throw new Error(g.msg || "鉴权失败");
+      const w = (d = g.data) == null ? void 0 : d.token;
+      if (!w) throw new Error("鉴权未返回 token");
+      this.token = w, this.storage.set("token", w);
+    } catch (m) {
+      throw m;
     }
   }
   /**