💬 微信小程序接入文档

微信小程序原生SDK，支持页面访问统计、自定义事件、错误监控、分享追踪

微信小程序接入

澄泓统计提供微信小程序原生SDK，文件体积小（约15KB），不占用小程序包大小配额，接入简单。

💡 前置条件：请先在后台添加微信小程序站点，获取 Tracking ID 和服务器地址。

步骤1：下载SDK文件

在小程序项目中创建 utils 目录（如果没有的话），下载SDK文件保存为 utils/analytics.js。

你可以通过以下方式获取SDK：

  1. 在后台「站点设置」→「小程序接入」页面直接下载
  2. 或者联系技术支持获取最新版本SDK
⚠️ 重要：请将 analytics.js 放在 utils 目录下，确保路径正确。

步骤2：在 app.js 中初始化

打开项目根目录的 app.js，引入并初始化SDK：

js 
// app.js
const analytics = require('./utils/analytics.js');

App({
  onLaunch: function () {
    // 初始化SDK
    analytics.init({
      tid: '你的TrackingID',
      serverUrl: 'https://your-domain'
    });
    
    // 上报App启动
    analytics.appLaunch();
    
    // ... 你的其他代码
  },
  
  onShow: function () {
    // 上报App显示（从后台切回前台）
    analytics.appShow();
  },
  
  onHide: function () {
    // 上报App隐藏（切到后台）
    analytics.appHide();
  },
  
  onError: function (msg) {
    // SDK会自动捕获错误，这里可以添加你的额外处理
    console.error('App error:', msg);
  },
  
  globalData: {
    userInfo: null
  }
})

初始化参数说明：

  • tid：必填，你在后台获取的 Tracking ID
  • serverUrl：必填，统计服务的域名地址，不要加末尾斜杠
  • debug：可选，设为 true 开启调试日志（默认false）
  • autoTrack：可选，是否自动追踪页面，默认 true

步骤3：页面埋点

如果开启了 autoTrack: true（默认开启），SDK会自动追踪页面访问。如果需要手动控制或更精细的统计，可以在页面中手动调用：

js 
// pages/index/index.js
const analytics = require('../../utils/analytics.js');

Page({
  data: {
    // ...
  },
  
  onShow: function () {
    // 页面显示时上报页面浏览
    analytics.pageShow({
      page_path: '/pages/index/index',
      page_title: '首页'
    });
  },
  
  onHide: function () {
    // 页面隐藏时上报离开
    analytics.pageHide();
  },
  
  onUnload: function () {
    // 页面卸载时上报离开
    analytics.pageHide();
  }
})

自动追踪分享

SDK支持自动追踪分享事件，你只需要在页面的 onShareAppMessage 中添加一行代码：

js 
// pages/product/detail.js
const analytics = require('../../utils/analytics.js');

Page({
  // ...
  
  onShareAppMessage: function () {
    // 上报分享事件
    analytics.trackShare('wechat', {
      page_path: '/pages/product/detail',
      product_id: this.data.productId
    });
    
    return {
      title: '这个商品不错，快来看看！',
      path: '/pages/product/detail?id=' + this.data.productId,
      imageUrl: this.data.coverImage
    };
  },
  
  onShareTimeline: function () {
    // 分享到朋友圈（可选）
    analytics.trackShare('timeline', {
      page_path: '/pages/product/detail',
      product_id: this.data.productId
    });
    
    return {
      title: '这个商品不错，快来看看！',
      query: 'id=' + this.data.productId
    };
  }
})

自定义事件

使用 trackEvent 方法上报任意自定义事件，例如：

js 
// 追踪商品浏览
analytics.trackEvent('product_view', {
  product_id: 'P12345',
  product_name: '示例商品',
  category: '电子产品',
  price: 299
});

// 追踪加入购物车
analytics.trackEvent('add_to_cart', {
  product_id: 'P12345',
  quantity: 1,
  price: 299
});

// 追踪购买
analytics.trackEvent('purchase', {
  order_id: 'O20250101001',
  amount: 99,
  payment_method: 'wechat',
  items_count: 2
});

// 追踪按钮点击
analytics.trackEvent('button_click', {
  button_name: '立即购买',
  location: 'product_detail'
});

// 追踪表单提交
analytics.trackEvent('form_submit', {
  form_name: 'contact_us',
  has_phone: true
});

错误自动捕获

SDK会自动通过 wx.onError 捕获小程序全局错误并上报，无需额外配置。你也可以手动上报捕获到的异常：

js 
try {
  // 可能出错的代码
  riskyOperation();
} catch (e) {
  // 手动上报错误
  analytics.trackError(e, {
    location: 'checkout_page',
    user_action: 'submit_order'
  });
}
📊 错误分析：错误信息会在后台的「错误监控」页面展示，包含错误堆栈、发生次数、影响用户数等信息。

关联用户（可选）

如果你有自己的用户体系，可以通过 setOpenid 或 setUserId 将统计数据与你的用户ID关联：

js 
// 用户登录成功后调用
wx.login({
  success: function(res) {
    if (res.code) {
      // 向你的服务器请求获取 openid
      wx.request({
        url: 'https://your-api.com/getOpenid',
        data: { code: res.code },
        success: function(response) {
          const openid = response.data.openid;
          const userId = response.data.user_id;
          
          // 关联微信openid
          analytics.setOpenid(openid);
          
          // 关联你自己的用户ID（可选）
          analytics.setUserId(userId);
          
          // 还可以设置用户属性
          analytics.setUserProfile({
            level: 'vip',
            register_date: '2025-01-01',
            source: 'wechat_search'
          });
        }
      });
    }
  }
});
⚠️ 合规提醒：请确保在获取和上传用户标识前，已获得用户同意并符合隐私政策要求。详见合规指南。

SDK API 参考

以下是SDK提供的完整方法列表：

方法说明
analytics.init(config)初始化SDK
analytics.appLaunch()上报App启动
analytics.appShow()上报App显示
analytics.appHide()上报App隐藏
analytics.pageShow(options)上报页面显示
analytics.pageHide()上报页面离开
analytics.trackEvent(name, props)上报自定义事件
analytics.trackShare(channel, props)上报分享事件
analytics.trackError(error, props)上报错误
analytics.setOpenid(openid)设置微信OpenID
analytics.setUserId(userId)设置自定义用户ID
analytics.setUserProfile(profile)设置用户属性

服务器域名配置

在微信公众平台登录你的小程序后台，进入「开发」→「开发管理」→「开发设置」→「服务器域名」，添加以下域名到 request合法域名：

text 
https://your-domain
✅ 验证接入：
  1. 在微信开发者工具中编译运行小程序
  2. 打开调试器（Console），开启 debug 模式可看到上报日志
  3. 切换几个页面，点击触发一些自定义事件
  4. 登录统计后台，在「实时访客」中应该能看到你的访问数据