HM Tracking SDK 使用文档

本文档详细介绍如何使用 HM Tracking SDK，包括初始化、广告业务和支付业务的完整流程。

1. 安装

建议通过 npm/yarn 安装正式发布的包：

# 使用 yarn
yarn add hm-tracking-sdk axios crypto-js

# 或使用 npm
npm i hm-tracking-sdk axios crypto-js

2. SDK 初始化

• 接口: init()

  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时的可选参数，数据结构及内部结构说明为：

    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 示例：

  {
    "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()

  import { isTelegramEnv } from "hm-tracking-sdk";
  
  if (isTelegramEnv()) {
    // Telegram WebApp 环境
  } else {
    // 浏览器/其他环境
  }

  • 函数说明：判断是否是Telegram环境。
  • 返回值：boolean。

3. 获取Telegram用户信息

• 接口: getTelegramUserUnsafe()

  import { getTelegramUserUnsafe, type TelegramUserInfo } from "hm-tracking-sdk";
  
  const user: TelegramUserInfo | null = getTelegramUserUnsafe();

  • 函数说明：在 Telegram 环境下返回 TelegramUserInfo；获取失败返回 null。

  • 返回值：TelegramUserInfo | null，数据结构为：

    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()

  await sdk.showHmAdByPosition(adPositionName, {
    onSuccess: (result) => {
      console.log("广告观看完成", result);
    },
    onError: (error) => {
      console.error("广告展示失败:", error);
    },
  });

• 函数说明：根据广告位名称展示广告。

• 参数说明

  • adPositionName（必填）
    • 说明：广告位名称，需要根据业务进行申请，具体请联系SDK开发者，使用示例值进行测试。
    • 类型：string
    • 示例值：
      • game_rewarded_ad_position
  • callbacks

    • 说明：广告展示成功/失败的回调。

    • 类型：

      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/。

• 最小示例

  {
    "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。

  • 生产环境建议通过初始化参数传入：

    const sdk = new HmTrackingSDK({
      tonConnectManifestUrl: "https://your-domain.com/tonconnect-manifest.json",
      // 其他可选项...
    });

• 自检

  • 在浏览器访问你的 manifest URL，确认返回 200 且 JSON 内容正确。
  • 打开连接钱包弹窗，应显示你在 manifest 中配置的名称与图标。

5.1.1 钱包是否链接

• 接口: isWalletConnected()

  sdk.isWalletConnected(): boolean

• 函数说明：同步检查是否已连接 TON 钱包；

• 返回值：boolean。

5.1.2 链接钱包

• 接口: connectWallet()

  sdk.connectWallet(): Promise<boolean>

• 函数说明：发起连接 TON 钱包；

• 返回值：Promise<boolean> 表示是否连接成功。

5.1.3 断开钱包链接

• 接口: disconnectWallet()

  sdk.disconnectWallet(): Promise<boolean>

• 函数说明：断开已连接的钱包；

• 返回值：Promise<boolean>，true 表示已断开或原本未连接；false 表示断开失败。

5.2 支付

5.2.1 获取支持的支付方式

• 接口: getSupportedPayModes()

  sdk.getSupportedPayModes(): Promise<MerchantPayModeListData>

• 函数说明：获取当前支持的币种及汇率配置；

• 返回值说明：Promise<MerchantPayModeListData>，见下方类型定义。

  interface MerchantPayModeListData {
    payModeList: MerchantPayModeItem[];
  }
  
  interface MerchantPayModeItem {
    id: number;
    title: string;
    name: string;   // 币种: 'USDT' | 'TON' | 'STARS'
    rate: number;   // 汇率
    nameDesc: string;
  }

5.2.2 创建并支付订单

• 接口: payByMerchant()

  
  // 创建并支付订单
  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 链上交易）；

• 参数说明：

  interface MerchantPayCreateRequest {
    currencyName: string; // "USDT" | "TON" | "STARS"
    amount: number;      // 支付金额
    outTradeNo: string;  // 商户订单号
    notifyUrl: string;   // 服务端支付回调地址
    attach: string;      // 附加信息，通常使用 JSON.stringify
  }

• 返回值数据结构：

  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;
  }

  // 支付完成回调返回的订单结果
  type MerchantPayFinishResponseData = MerchantPayOrderBase;

5.2.3 查询支付结果

• 接口: merchantPayQueryResult()

  sdk.merchantPayQueryResult(data: MerchantPayQueryResultRequest): Promise<MerchantPayQueryResultResponseData>

• 函数说明：通过系统订单号 orderSn 或商户订单号 outTradeNo 查询订单最新结果；

• 参数说明：MerchantPayQueryResultRequest，见下方类型:

  interface MerchantPayQueryResultRequest {
   orderSn?: string;
   outTradeNo?: string;
  }

• 返回值说明：Promise<MerchantPayQueryResultResponseData>，同 MerchantPayOrderBase。

  type MerchantPayQueryResultResponseData = MerchantPayOrderBase;

5.2.4 支付结果通知（服务端回调）

• 说明：当你的服务接收 notifyUrl 的支付结果通知时，应返回统一响应结构，以便平台确认处理状态。
• 返回值示例：

{
  "code": 1,
  "msg": "通知支付结果成功",
  "timestamp": 1756442387,
  "datetime": "2025-08-29T04:39:47.518Z",
  "data": {}
}

• 约定说明：
  • code: 1 表示成功；非 1 表示失败
  • msg: 描述信息
  • timestamp/datetime: 服务端时间
  • data: 业务扩展字段（本例为空对象）