@eclicktech/mp-sdk

v3.3.1-beta.2

Published

5 months ago

The Eclicktech Funsdata of MiniProgram SDK, suport echat, Alipay, TikTok

Downloads

0High
0Medium
0Low

lk06

kayn.li

sdk MiniProgram wechat fundsdata analytics eclicktech yeahmobi

FunsData Analytics 小程序 SDK

上报参数

app_id 您的项目的 app_id，可通过在项目产品页面获取
上报地址：your_serviceurl

一、集成 SDK

安装命令：

pnpm add @eclicktech/mp-sdk

将 analytics.wx.js 文件导入

const analytics = require("miniprogram_npm/@eclicktech/mp-sdk/analytics.wx");

在 project.config.json 中需要确认：

"miniprogramRoot": "./",
"setting": {
  "nodeModules": true,
  "packNpmRelationList": [
      {
          "packageJsonPath": "./package.json",
          "miniprogramNpmDistDir": "./miniprogram_npm"
      }
  ],
}

二、配置 SDK

引入 SDK 之后，您就可以创建 SDK 实例，开始上报数据了：

import analytics from "../../mp_sdk/build/analytics.wx";
// 初始化配置
var config = {
  appId: "your-app-id", // 项目的 App ID（必填）
  serverUrl: "https://your.serverurl.com", // 数据上报地址（必填）
  autoTrack: {
    // 自动追踪配置（可选）
    appShow: true, // 自动追踪应用显示事件
    appHide: true, // 自动追踪应用隐藏事件
    appLaunch: true, // 自动追踪应用启动事件
    pageShow: true, // 自动追踪页面显示事件
    pageLeave: true, // 自动追踪页面离开事件
    mpClick: true, // 自动追踪小程序点击事件
    pageShare: true, // 自动追踪页面分享事件
    mpFavorite: true, // 自动追踪小程序收藏事件
    properties: {}, // 自动追踪事件的公共属性
    callback: function (eventType) {
      // 自动追踪事件回调
      return {}; // 返回额外属性
    }
  },
  enableLog: true, // 启用日志打印（可选）
  debugMode: "none", // 调试模式：'none', 'debug', 'debugOnly'
  strict: true, // 严格模式，验证参数格式
  disablePresetProperties: [], // 禁用的预置属性列表
  zoneOffset: 8 // 时区偏移量
};

analytics.init(config);

Page({
  data: {},
  onReady: function () {
    // 初始化
  },
  // 设置访客 ID, 对应上报数据中的 #distinct_id
  identify: function () {
    analytics.setDistinctId("your_own_anonymous_id");
  },
  // 设置账号 ID，对应上报数据里的 #account_id
  login: function () {
    analytics.login("ABC_123456");
  },
  // 去除上报数据里的 #account_id 字段
  logout: function () {
    analytics.logout();
  },
  // 设置公共事件属性
  setSuperProperties: function () {
    analytics.setSuperProperties({ channel: "渠道" });
  },
  // 上报事件
  track: function () {
    analytics.track(
      "Purchase", //追踪事件的名称
      {
        Item: "商品A",
        ItemNum: 1,
        Cost: 100
      } //需要上传的事件属性
    );
  }
});

三、发送事件

3.1 普通事件追踪 - track

// 基础调用方式
Analytics.track(
  {
    eventName: "product_buy", // 事件名称，必填
    properties: {
      // 事件属性，可选
      product_name: "钻石",
      price: 100
    },
    time: new Date(), // 事件时间，可选
    onComplete: function (result) {
      // 回调函数，可选
      console.log("事件上报结果:", result);
    }
  },
  "appId"
); // appId 可选

3.2 首次事件追踪 - trackFirst

Analytics.trackFirst({
  eventName: "first_login",
  firstCheckId: "device_id", // 首次检查ID，默认为设备ID
  properties: { channel: "wechat" },
  time: new Date(),
  onComplete: callback
});

3.3 可更新事件追踪 - trackUpdate

Analytics.trackUpdate({
  eventName: "game_level",
  eventId: "unique_event_id", // 事件ID，必填
  properties: { level: 5 },
  time: new Date(),
  onComplete: callback
});

3.4 可覆写事件追踪 - trackOverwrite

Analytics.trackOverwrite({
  eventName: "user_profile",
  eventId: "profile_update_id", // 事件ID，必填
  properties: { age: 25 },
  time: new Date(),
  onComplete: callback
});

四、用户属性

4.1 设置用户属性 - userSet

Analytics.userSet({
  properties: {
    // 用户属性，必填
    username: "tiki",
    age: 25,
    vip_level: "gold"
  },
  time: new Date(), // 时间，可选
  onComplete: callback // 回调，可选
});

4.2 设置用户属性（仅首次） - userSetOnce

// 如果属性已存在，则忽略新值
Analytics.userSetOnce({
  properties: {
    first_login_time: new Date(),
    register_channel: "wechat"
  }
});

4.3 数值类型用户属性累加 - userAdd

Analytics.userAdd({
  properties: {
    total_purchase: 100, // 累加购买金额
    login_count: 1 // 累加登录次数
  },
  time: new Date(),
  onComplete: callback
});

4.4 重置用户属性 - userUnset

Analytics.userUnset({
  property: "temp_data", // 要重置的属性名
  time: new Date(),
  onComplete: callback
});

4.5 删除用户 - userDel

// 删除用户数据，不可逆操作，请谨慎使用
Analytics.userDel({
  time: new Date(),
  onComplete: callback
});

4.6 追加列表类型用户属性 - userAppend

Analytics.userAppend({
  properties: {
    favorite_games: ["game1", "game2"] // 追加到列表
  }
});

4.7 去重追加列表属性 - userUniqAppend

Analytics.userUniqAppend({
  properties: {
    visited_pages: ["home", "profile"] // 去重后追加
  }
});

4.8 用户身份管理

// 设置访客ID
Analytics.setDistinctId("unique_visitor_id");

// 用户登录
Analytics.login("user_account_id");

// 用户登出
Analytics.logout();

五、公共属性设置

5.1 设置公共事件属性

设置后，所有事件都会包含这些属性：

Analytics.setSuperProperties({
  channel: "wechat",
  app_version: "1.0.0"
});

5.2 设置动态公共属性

每次上报事件时，动态获取最新值：

Analytics.setDynamicSuperProperties(function () {
  return {
    current_time: new Date().getTime(),
    network_type: getCurrentNetworkType()
  };
});

六、其他重要方法

6.1 设置事件上报状态

控制事件上报行为：

| 状态值 | 说明 | | ----------- | ------------------ | | NORMAL | 正常上报 | | PAUSE | 暂停上报 | | STOP | 停止上报并清除缓存 | | SAVE_ONLY | 仅保存不上报 |

Analytics.setTrackStatus("NORMAL");

6.2 立即上报缓存数据

立即尝试上报缓存队列中的数据：

Analytics.flush();

6.3 用户登录 / 登出

// 用户登录
Analytics.login("user_account_id");

// 用户登出
Analytics.logout();

七、自动采集事件

7.1 自动采集配置

autoTrack: {
  appLaunch: true,      // 自动采集应用启动事件 ta_mp_launch
  appShow: true,        // 自动采集应用显示事件 ta_mp_show
  appHide: true,        // 自动采集应用隐藏事件 ta_mp_hide
  pageShow: true,       // 自动采集页面浏览事件 ta_mp_view
  pageLeave: true,      // 自动采集页面离开事件 ta_page_leave
  pageShare: true,      // 自动采集页面分享事件 ta_mp_share
  mpClick: true,        // 自动采集小程序点击事件 ta_mp_click
  mpFavorite: true,     // 自动采集小程序收藏事件 ta_add_favorite
  properties: {},       // 自动采集事件的公共属性
  callback: function(eventType) {
    // 自动采集事件回调，返回额外属性
    return {};
  }
}

import analytics from "../../mp_sdk/build/analytics.wx";
var config = {
  appId: "your_app_id", // 项目的 APP ID
  serverUrl: "https://deapi.adsgreat.cn/v1/wechat/report/json", // 数据上报地址
  autoTrack: {
    appLaunch: true, // 自动采集 ta_mp_launch
    appShow: true, // 自动采集 ta_mp_show
    appHide: true, // 自动采集 ta_mp_hide
    pageShow: true, // 自动采集 ta_mp_view
    pageShare: true // 自动采集 ta_mp_share
  }
};
analytics.init(config);

Page({
  data: {},
  onReady: function () {
    // 初始化
  },
  // 设置访客 ID, 对应上报数据中的 #distinct_id
  identify: function () {
    analytics.setDistinctId("your_own_anonymous_id");
  },
  // 设置账号 ID，对应上报数据里的 #account_id
  login: function () {
    analytics.login("ABC_123456");
  },
  // 去除上报数据里的 #account_id 字段
  logout: function () {
    analytics.logout();
  },
  // 设置公共事件属性
  setSuperProperties: function () {
    analytics.setSuperProperties({ channel: "渠道" });
  },
  // 上报事件
  track: function () {
    analytics.track(
      "Purchase", //追踪事件的名称
      {
        Item: "商品A",
        ItemNum: 1,
        Cost: 100
      } //需要上传的事件属性
    );
  }
});

7.2 属性说明

7.2.1 通用属性

#url_path
通过 getCurrentPages() 获取当前页面路径。
#scene
从小程序启动参数中获取场景值（微信提供的场景值）。
#utm
从 URL query 参数中解析 UTM 营销参数。
#start_reason
小程序启动参数的 JSON 字符串。

7.2.2 时长相关属性

#duration
通过 timeEvent() 方法计算的事件持续时间（秒）。
- 应用隐藏事件会计算应用使用时长。
- 页面离开事件会计算页面停留时长。

7.2.3 元素相关属性（点击事件）

| 属性名 | 数据来源 | | -------------------- | ------------------------------- | | #element_id | currentTarget.id | | #element_type | currentTarget.dataset.type | | #element_content | currentTarget.dataset.content | | #element_name | currentTarget.dataset.name |

7.3 采集事件

7.3.1 小程序初始化

| 项目 | 说明 | | ---------------- | ---------------------------------------------------------------------- | | 事件名 | ta_mp_launch | | 触发时机 | 首次打开小程序，或用户杀死进程后重新启动；整个进程生命周期仅触发一次。 | | 自动采集属性 | #scene：场景值，取自微信提供的场景值。 | | 典型分析场景 | 计算每日使用次数、人均使用次数；按场景值分组查看不同场景的使用情况。 |

7.3.2 小程序启动

| 项目 | 说明 | | ---------------- | ----------------------------------------------------------- | | 事件名 | ta_mp_show | | 触发时机 | 小程序启动，或从后台调回前台。 | | 自动采集属性 | - #scene：场景值- #url_path：启动后展示页面的路径。 | | 典型分析场景 | 在行为路径中标记一次使用起点，作为用户行为路径的初始行为。 |

7.3.3 小程序隐藏

| 项目 | 说明 | | ---------------- | ------------------------------------------------------------------------- | | 事件名 | ta_mp_hide | | 触发时机 | 小程序被调入后台。 | | 自动采集属性 | - #scene：场景值- #duration：本次启动到隐藏的持续时长（秒）。 | | 典型分析场景 | 计算总使用时长、人均时长；除以初始化次数可得单次使用时长。 |

7.3.4 小程序页面浏览

| 项目 | 说明 | | ---------------- | ------------------------------------------------------------------------------------------------------------ | | 事件名 | ta_mp_view | | 触发时机 | 页面打开，或从后台调回前台时页面重新展示。 | | 自动采集属性 | - #scene：场景值- #url_path：被展示页面的路径- #referrer：前向路径，若首页打开则为“直接打开”。 | | 典型分析场景 | 计算各页面 PV/UV；分析用户访问路径。 |

7.3.5 小程序页面转发分享

| 项目 | 说明 | | ---------------- | ----------------------------------------------------------- | | 事件名 | ta_mp_share | | 触发时机 | 点击转发按钮（右上角导航栏按钮或页面内按钮）。 | | 自动采集属性 | - #scene：场景值- #url_path：转发时所在的页面路径。 | | 典型分析场景 | 分析页面分享率，优化转发功能。 |

7.3.6 小程序页面卸载

| 项目 | 说明 | | ---------------- | ---------------------------------------------------------------------- | | 事件名 | ta_page_leave | | 触发时机 | 页面卸载（例如跳转到其他页面）。 | | 自动采集属性 | - #duration：页面停留时长（秒）- #url_path：卸载时的页面路径。 |

7.3.7 小程序页面收藏

| 项目 | 说明 | | ---------------- | ------------------------------- | | 事件名 | ta_add_favorite | | 触发时机 | 页面被收藏。 | | 自动采集属性 | #url_path：被收藏页面的路径。 |

以下是将表格内容转换为 Markdown 格式后的结果：

系统预置字段

核心标识字段

| 字段名 | 简介 | 示例值 | | ------------ | ------------------------------------- | ----------------------------- | | #distinct_id | 访客唯一标识，UUID 自动生成或手动设置 | 1234-5678-9012-3456-789012345 | | #account_id | 用户账户 ID，登录时设置 | user_123456 | | #device_id | 设备唯一标识 | device_abc123 |

设备信息字段

| 字段名 | 简介 | 示例值 | | -------------- | ---------------- | ----------------------- | | #os | 操作系统类型 | iOS, Android | | #os_version | 操作系统版本 | 14.5, 11.0 | | #device_model | 设备型号 | iPhone 12, Xiaomi Mi 11 | | #manufacturer | 设备制造商 | Apple, Xiaomi | | #screen_width | 屏幕宽度（像素） | 375, 414 | | #screen_height | 屏幕高度（像素） | 812, 896 | | #network_type | 网络连接类型 | wifi, 4g, 3g |

自动收集的数据

| 字段名 | 简介 | 示例值 | | ---------------- | ------------------------------- | ------------------ | | #device_id | 设备唯一标识符（UUID 生成） | abc123-def456-789 | | #device_model | 设备型号 | iPhone 8 | | #manufacturer | 设备制造商 | Apple | | #screen_width | 屏幕宽度（像素） | 375 | | #screen_height | 屏幕高度（像素） | 667 | | #os | 操作系统名称 | iOS、Android | | #os_version | 操作系统版本号 | 14.5、11.0 | | #system_language | 系统语言 | zh-CN、en-US | | #network_type | 当前网络类型（wifi、4g、3g 等） | wifi、4g、3g | | #lib | SDK 名称 | FunsData Analytics | | #lib_version | SDK 版本号 | 1.0.0 | | #mp_platform | 小程序平台名称 | wechat_mp | | #app_version | 小程序版本号 | 2.3.1 | | #zone_offset | 时区偏移量 | +8 |

微信SDK文件位置: @eclicktech/mp-sdk/build/analytics.wx.js 详细使用指南: https://janzlz0n1f.feishu.cn/wiki/PGKqwsWGWikAXokH5rvcOqtKnGd