🔧 UniApp接入文档

通过UniApp条件编译，一套代码同时支持H5和微信小程序多端统计

UniApp接入

澄泓统计支持UniApp跨平台框架，通过条件编译实现一套代码同时支持H5和微信小程序端。

💡 原理说明：H5端复用网站JS SDK（通过script标签动态加载），微信小程序端复用小程序SDK，通过UniApp的条件编译指令区分平台。
⚠️ 当前支持：
  • ✅ H5端：完整支持
  • ✅ 微信小程序：完整支持
  • ⏳ App端（iOS/Android）：暂不支持，后续版本推出
  • ⏳ 其他小程序（支付宝/百度/字节）：后续版本支持

接入思路

我们将创建一个统一的 utils/analytics.js 工具文件，内部通过条件编译调用不同平台的SDK方法，在业务代码中统一调用即可。

步骤1：准备SDK文件

在项目的 utils 目录下：

  1. 下载微信小程序SDK文件，保存为 utils/analytics-mp.js
  2. 创建统一入口文件 utils/analytics.js

步骤2：创建统一封装工具

创建 utils/analytics.js 文件，内容如下：

js 
// utils/analytics.js
// 澄泓统计 UniApp 统一封装

// #ifdef H5
// H5端：动态加载JS SDK
let h5Inited = false;

function initH5(config) {
  if (h5Inited) return;
  h5Inited = true;
  
  const script = document.createElement('script');
  script.async = true;
  script.defer = true;
  script.setAttribute('data-tid', config.tid);
  script.src = config.scriptUrl || 'https://your-domain/t.js';
  document.head.appendChild(script);
  
  // SPA模式自动开启
  script.setAttribute('data-spa', 'auto');
}
// #endif

// #ifdef MP-WEIXIN
// 微信小程序端：引入小程序SDK
const mpAnalytics = require('./analytics-mp.js');
// #endif

const analytics = {
  init(config) {
    // #ifdef H5
    initH5(config);
    // #endif
    
    // #ifdef MP-WEIXIN
    mpAnalytics.init({
      tid: config.tid,
      serverUrl: config.serverUrl || 'https://your-domain'
    });
    // #endif
  },
  
  // App生命周期
  appLaunch() {
    // #ifdef MP-WEIXIN
    mpAnalytics.appLaunch();
    // #endif
  },
  
  appShow() {
    // #ifdef MP-WEIXIN
    mpAnalytics.appShow();
    // #endif
  },
  
  appHide() {
    // #ifdef MP-WEIXIN
    mpAnalytics.appHide();
    // #endif
  },
  
  // 页面浏览（H5自动处理，小程序需手动调用）
  trackPageview(options) {
    // #ifdef H5
    if (window.lightAnalytics) {
      window.lightAnalytics.trackPageview();
    }
    // #endif
    
    // #ifdef MP-WEIXIN
    mpAnalytics.pageShow(options);
    // #endif
  },
  
  // 自定义事件
  trackEvent(name, props) {
    // #ifdef H5
    if (window.lightAnalytics) {
      window.lightAnalytics.trackEvent(name, props);
    }
    // #endif
    
    // #ifdef MP-WEIXIN
    mpAnalytics.trackEvent(name, props);
    // #endif
  },
  
  // 设置用户ID
  setUserId(userId) {
    // #ifdef MP-WEIXIN
    mpAnalytics.setUserId(userId);
    // #endif
  },
  
  // 设置OpenID
  setOpenid(openid) {
    // #ifdef MP-WEIXIN
    mpAnalytics.setOpenid(openid);
    // #endif
  }
};

export default analytics;

步骤3：在 main.js 中初始化

打开项目根目录的 main.js，在App启动前初始化统计：

js 
// main.js
import Vue from 'vue'
import App from './App'
import analytics from './utils/analytics.js'

Vue.config.productionTip = false

// 初始化统计
analytics.init({
  tid: '你的TrackingID',
  serverUrl: 'https://your-domain',
  scriptUrl: 'https://your-domain/t.js'  // H5端脚本地址
});

App.mpType = 'app'

const app = new Vue({
  ...App
})
app.$mount()

步骤4：在 App.vue 中处理生命周期

打开 App.vue，在应用生命周期中调用对应方法：

js 
<script>
import analytics from './utils/analytics.js'

export default {
  onLaunch: function() {
    console.log('App Launch')
    analytics.appLaunch();
  },
  onShow: function() {
    console.log('App Show')
    analytics.appShow();
  },
  onHide: function() {
    console.log('App Hide')
    analytics.appHide();
  }
}
</script>

<style>
/* 全局样式 */
</style>

H5端单独示例

如果你只需要H5端支持，可以简化接入方式，直接在 index.html 中添加脚本标签：

html 
<!-- index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>UniApp H5</title>
</head>
<body>
  <div id="app"></div>
  <script src="/static/js/index.js"></script>
  
  <!-- 澄泓统计 H5 SDK -->
  <script async defer 
    data-tid="你的TrackingID" 
    data-spa="auto"
    src="https://your-domain/t.js">
  </script>
</body>
</html>

在Vue组件中需要手动上报事件时：

js 
// 在Vue组件方法中
export default {
  methods: {
    handlePurchase() {
      // #ifdef H5
      if (window.lightAnalytics) {
        window.lightAnalytics.trackEvent('purchase', {
          amount: 99,
          product_id: 'P123'
        });
      }
      // #endif
      
      // #ifdef MP-WEIXIN
      const analytics = require('../../utils/analytics-mp.js');
      analytics.trackEvent('purchase', {
        amount: 99,
        product_id: 'P123'
      });
      // #endif
    }
  }
}

微信小程序端单独示例

如果你只需要微信小程序支持，不需要H5，可以直接按微信小程序接入文档操作，不使用条件编译。

在UniApp的页面中使用：

js 
// pages/index/index.vue
<script>
import analytics from '@/utils/analytics.js'

export default {
  data() {
    return {}
  },
  onShow() {
    analytics.trackPageview({
      page_path: '/pages/index/index',
      page_title: '首页'
    });
  },
  methods: {
    onButtonClick() {
      analytics.trackEvent('button_click', {
        button_name: 'cta',
        location: 'home'
      });
    },
    onShareAppMessage() {
      analytics.trackEvent('share', {
        channel: 'wechat'
      });
      return {
        title: '分享标题',
        path: '/pages/index/index'
      };
    }
  }
}
</script>

条件编译说明

UniApp的条件编译是通过特殊注释实现的，以下是常用的编译指令：

编译指令生效平台
#ifdef H5仅H5端
#ifdef MP-WEIXIN仅微信小程序
#ifdef APP-PLUS仅App端
#ifndef H5除了H5之外的平台

Taro框架说明

如果你使用的是Taro框架，接入方式与UniApp类似：

  • H5端：动态加载JS SDK或在html模板中引入
  • 微信小程序端：引入小程序SDK
  • 使用 process.env.TARO_ENV 判断环境
js 
// Taro环境判断示例
if (process.env.TARO_ENV === 'h5') {
  // H5端逻辑
  if (window.lightAnalytics) {
    window.lightAnalytics.trackEvent('event_name');
  }
} else if (process.env.TARO_ENV === 'weapp') {
  // 微信小程序端逻辑
  const analytics = require('./utils/analytics-mp.js');
  analytics.trackEvent('event_name');
}

常见问题

Q: H5端刷新页面后数据会不会重复上报？

A: 不会，SDK会自动处理页面刷新，首次加载自动上报PV，路由切换由SPA模式处理。

Q: 小程序SDK放在utils目录会影响主包大小吗？

A: SDK只有约15KB，且支持分包加载，对包大小影响极小。如果对包大小敏感，可以开启代码压缩。

Q: 如何在uni-app中关闭自动页面追踪？

A: H5端不要设置 data-spa="auto" 即可，小程序端初始化时设置 autoTrack: false。

✅ 验证接入：
  1. H5端：在浏览器中运行，打开开发者工具Network，查看是否有collect请求
  2. 小程序端：在微信开发者工具中查看Network和Console日志
  3. 登录后台查看「实时访客」确认数据上报成功