js-sdk集成指南

适用范围

最终以html、js代码形式运行在浏览器中的页面（包括APP内嵌webView页面），均可以使用该sdk进行埋点采集上报。

引入js-sdk

传统网页引入

<script>
  (function () {
    if (window.zhuge) return;
    // 文档中的sdk集成代码
    window.zhuge = window.zhuge || [];
    window.zhuge.methods =
      '_init identify track getDid getSid getKey setSuperProperty setUserProperties setPlatform setWxProperties setUTM'.split(
        ' ',
      );
    window.zhuge.factory = function (b) {
      return function () {
        var a = Array.prototype.slice.call(arguments);
        a.unshift(b);
        window.zhuge.push(a);
        return window.zhuge;
      };
    };
    for (var i = 0; i < window.zhuge.methods.length; i++) {
      var key = window.zhuge.methods[i];
      window.zhuge[key] = window.zhuge.factory(key);
    }
    window.zhuge.load = function (b, x) {
      if (!document.getElementById('zhuge-js')) {
        var a = document.createElement('script');
        var verDate = new Date();
        var verStr =
          verDate.getFullYear().toString() +
          verDate.getMonth().toString() +
          verDate.getDate().toString();

        a.type = 'text/javascript';
        a.id = 'zhuge-js';
        a.async = !0;
        a.src = 'https://sdk.domain.com/zhuge.js?v=' + verStr;
        a.onerror = function () {
          window.zhuge.identify = window.zhuge.track = function (ename, props, callback) {
            if (callback && Object.prototype.toString.call(callback) === '[object Function]') {
              callback();
            } else if (Object.prototype.toString.call(props) === '[object Function]') {
              props();
            }
          };
        };
        var c = document.getElementsByTagName('script')[0];
        c.parentNode.insertBefore(a, c);
        window.zhuge._init(b, x);
      }
    };
    window.zhuge.load('APPKEY', {
      // sdk集成配置
    });
  })();
</script>

注意:

1. APPKEY为诸葛分配的应用标识，https://sdk.domain.com/zhuge.js为诸葛提供的js-sdk地址。
2. 同一个页面请勿重复引入上述集成代码，否则会导致集成失败。
3. 不要在线上 file 协议地址的页面中集成使用SDK，否则会因为无法写入cookie，产生大量匿名用户数据。且无法维护用户会话状态。

npm引入

安装

npm install @zgfe/js-sdk

SDK集成

import Tracker from '@zgfe/js-sdk';

const zhuge = new Tracker();
zhuge.load('APPKEY', {
  // sdk集成配置
});

export default zhuge;

npm下载的sdk文件中，默认数据上报地址为saas环境，因此私有部署的客户，请使用本地集成引入方式集成SDK，或在初始化时传入apiHost、apiHostBac和socketUrl，如：

import Tracker from '@zgfe/js-sdk';
const zhuge1 = new Tracker();
zhuge1.load('APPKEY', {
  // 埋点数据上报地址
  apiHost: 'https://u.zhugeapi.net',
  // 埋点数据上报备用地址（没有时可与apiHost保持一致）
  apiHostBac: 'https://ubak.zhugeio.com',
  /**
   * socket通信连接地址，在通过分析平台打开页面分析、可视化埋点、落地页热力图分析时，
   * 需要通过该地址与分析平台进行通信，通常与分析平台域名保持一致
   */
  socketUrl: 'wss://saas.zhugeio.com',
});

本地集成

SDK文件可通过技术支持人员获取后在项目中引入。将获取的SDK文件放置在项目中，然后在项目中引入SDK文件，如：

import Tracker from './zhuge';

const zhuge = new Tracker();
zhuge.load('APPKEY', {
  // sdk集成配置
});

export default zhuge;

注意:

1. APPKEY为诸葛分配的应用标识
2. 不要在线上 file 协议地址的页面中集成使用SDK，否则会因为无法写入cookie，产生大量匿名用户数据。且无法维护用户会话状态。
3. 数据上报地址等信息，请和技术支持人员确认。

多实例

sdk支持多实例化，可以在不同的业务场景下使用不同的实例。例如：

import Tracker from '@zgfe/js-sdk';

const tracker1 = new Tracker();
tracker1.load('APPKEY1', {
  // sdk集成配置
});
tracker1.track('custom_event1', {
  property1: 'value1',
});

const tracker2 = new Tracker();
tracker2.load('APPKEY2', {
  // sdk集成配置
});
tracker2.track('custom_event2', {
  property2: 'value2',
});

初始化配置项介绍

所有配置项均为非必填项，可根据实际需求进行配置。

| 配置项 | 介绍 | 备注 | | --- | --- | --- | | cookieExpires | cookie过期时间，单位为天，默认为365天 | 无 | | ~~cookie_expire_days~~ | cookie过期时间，单位为天，默认为365天（此为过时属性，建议使用cookieExpires） | 已过时 | | cookieCrossSubDomain | 是否跨子域设置cookie，默认为true，即可以在所有子域下共享cookie | 无 | | ~~cookie_cross_subdomain~~ | 是否跨子域设置cookie，默认为true，即可以在所有子域下共享cookie（此为过时属性，建议使用cookieCrossSubDomain） | 已过时 | | cookieSecure | 是否只在https下设置cookie，默认为false | 无 | | ~~cookie_secure~~ | 是否只在https下设置cookie，默认为false（此为过时属性，建议使用cookieSecure） | 已过时 | | ~~did_cookie_expire_days~~ | did和cookie过期时间，单位为天，默认为365天（此为过时属性，建议使用didExpires） | 已过时 | | didExpires | did过期时间，单位为天，默认为365天 | 无 | | platformExpire | 环境平台信息过期时间，单位为天，默认为7天。SDK活跃时间超过该期限时，重新获取环境平台信息并进行上报 | 无 | | ~~info_upload_interval_days~~ | 环境平台信息过期时间，单位为天，默认为7天。SDK活跃时间超过该期限时，重新获取环境平台信息并进行上报（此为过时属性，建议使用platformExpire） | 已过时 | | sessionExpire | 会话过期时间，单位为分钟，默认为30分钟。超过该时间间隔，认为新的会话开始 | 无 | | ~~session_interval_mins~~ | 会话过期时间，单位为分钟，默认为30分钟。超过该时间间隔，认为新的会话开始（此为过时属性，建议使用sessionExpire） | 已过时 | | storeMode | 存储模式，默认为cookie | 取值为cookie或者storage | | apiHost | 数据上报地址 | 无 | | ~~api_host~~ | 数据上报地址（此为过时属性，建议使用apiHost） | 已过时 | | apiHostBac | 数据上报备用地址 | 无 | | ~~api_host_bac~~ | 数据上报备用地址（此为过时属性，建议使用apiHostBac） | 已过时 | | debug | 是否开启调试模式 | 无 | | appChannel | 应用渠道 | 无 | | ~~app_channel~~ | 应用渠道（此为过时属性，建议使用appChannel） | 已过时 | | appVersion | 应用版本 | 无 | | ~~app_version~~ | 应用版本（此为过时属性，建议使用appVersion） | 已过时 | | superProperty | 全局事件公共属性，当传值为字符串时，需要符合JSON格式 | 可以为object或者json | | platform | 环境平台属性，用于拓展SDK采集到的环境信息能力，当传值为字符串时，需要符合JSON格式 | 可以为object或者json | | autoTrack | 是否开启全埋点自动采集，默认为false，影响范围：click、pv、scroll的自动采集 | 无 | | pv | 是否开启页面浏览事件自动采集，默认为false | 无 | | click | 是否开启点击事件自动采集，默认为false，当开启时，会自动采集所有元素的点击事件，若元素上带有zgclickdisable属性，则不采集 | 无 | | openLanding | 是否开启落地页滚动事件自动采集，默认为false | 无 | | alwaysLanding | 是否开启落地页滚动事件自动采集，默认为false。当开启时，无论是否为落地页，都会采集滚动事件 | 无 | | isClickAble | 用于自定义点击事件的采集规则，返回true则采集，返回false则不采集，当传入isClickAble时，SDK内置的点击事件采集规则将失效 | 无 | | visualizer | 是否开启埋点可视化，默认为false | 无 | | utm | UTM参数，当传值为字符串时，需要符合JSON格式 | 包含多个过时属性 | | adTrack | 是否开启广告监测，默认为false | 无 | | adCollect | 是否开启广告监测深度归隐数据采集，默认为false | 无 | | autoUploadByApp | 是否开启APP自动上报，默认为false。当开启并且在APP环境下监测到APP集成了诸葛原生SDK，js端产生的所有数据将通过APP上报 | 无 | | did | 设备ID，用于标识设备唯一性，此参数仅在SDK首次初始化时生效 | 无 | | updateUtm | 是否更新UTM参数，默认为false，即每个会话只取一次utm信息 | 无 | | openPrivacy | 是否开启全埋点采集隐私数据脱敏，默认为false；脱敏规则包括：邮箱地址、网址及数字脱敏 | 无 | | exposure | 是否开启曝光事件自动采集，默认为false | 无 | | duration | 是否开启页面停留时长事件自动采集，默认为false | 无 | | adLanding | 广告落地页地址，用于标识广告落地页 | 无 | | useAjax | 是否使用ajax上报，默认为false | 无 | | encrypt | 是否开启数据加密（sm2+sm4），默认为false | 无 | | publicKey | sm2公钥，用于数据加密 | 无 | | skipAppkeyCheck | 是否跳过appkey校验（纯客户端逻辑），默认为false | 无 | | clickBlackList | 用于判断点击元素是否在黑名单中，返回true则不采集，返回false则采集（API已过时，建议使用isClickAble） | 已过时 | | showLog | 是否显示日志，默认为false | 无 |

加密传输

SDK支持数据国密加密传输，以保障数据安全性。加密方式为sm2+sm4，加密传输需要在初始化时传入encrypt，如：

import Tracker from '@zgfe/js-sdk';
const tracker = new Tracker();
tracker.load('APPKEY', {
  encrypt: true,
  // publicKey: '公钥',
});

注意: publicKey为系统默认公钥，一般不需要自定义指定；如需使用自定义公钥，请联系技术支持人员获取。

使用hook

用于在特定声明周期进行监听或者使用插件。

参数

• lifecycle：LifecycleEvent类型，生命周期事件类型。
• plugin：Function类型，要使用的插件函数。

例如:

function myPlugin() {
  // 插件逻辑...
}
tracker.hook(LifecycleEvent.READY, myPlugin);

初始化完成(READY)

SDK初始化完成后触发。

tracker.hook(LifecycleEvent.READY, () => {
  // 初始化完成后的逻辑...
});

注意：

1. 需要在调用zhuge.load初始化SDK之前注册该事件。否则容易造成监听不到初始化完成事件。
2. 该事件只会触发一次。
3. 请勿在该事件中绑定强业务逻辑，以免主线业务逻辑受影响。

会话开始(SESSION_START)

监测到会话开始时触发，可以通过该事件获取会话信息。但数据为只读状态，无法对数据进行修改。

tracker.hook(LifecycleEvent.SESSION_START, (data: ZGTypes.UploadData['data'][0]) => {
  console.log('会话开始', data);
});

回传数据样例:

{
  "dt": "ss",
  "pr": {
    // 会话id
    "$sid": 1729129353863,
    // 用户唯一标识（实名用户时有）
    "$cuid": "cuid",
    // 触发时间
    "$ct": 1729129353863,
    // 时区
    "$tz": 28800000,
    // 当前url
    "$url": "http://172.16.11.211:8585/#%E5%88%9D%E5%A7%8B%E5%8C%96%E5%AE%8C%E6%88%90(READY)",
    // 来源url
    "$ref": "http://172.16.11.211:8585/#%E5%88%9D%E5%A7%8B%E5%8C%96%E5%AE%8C%E6%88%90(READY)",
    // 来源域名
    "$referrer_domain": "172.16.11.211"
  }
}

注意： 建议在调用zhuge.load初始化SDK之前注册该事件。否则容易造成监听不到会话开始事件。

会话结束(SESSION_END)

监测到会话结束时触发，可以通过该事件获取会话信息。但数据为只读状态，无法对数据进行修改。

tracker.hook(LifecycleEvent.SESSION_END, (data: ZGTypes.UploadData['data'][0]) => {
  console.log('会话结束', data);
});

回传数据样例:

{
  "dt": "se",
  "pr": {
    // 会话id
    "$sid": 1729129353863,
    // 用户唯一标识（实名用户时有）
    "$cuid": "cuid",
    // 触发时间
    "$ct": 1729129353863,
    // 时区
    "$tz": 28800000,
    // 会话时长
    "$dru": 0,
  }
}

注意： 建议在调用zhuge.load初始化SDK之前注册该事件。否则容易造成监听不到会话结束事件。

用户标识(USER_IDENTIFY)

在调用identify时触发，此状态下可以在数据上报前修改数据。

tracker.hook(LifecycleEvent.USER_IDENTIFY, (data: ZGTypes.UploadData['data'][0]) => {
  return {
    // 拓展属性
    '拓展属性名': '拓展属性值'
    '修改属性名': '修改属性值'
  }
});

注意: 返回的数据会覆盖原有数据

数据样例：

{
  "dt": "usr",
  "pr": {
    "$cuid": "张三",
    "_年龄": "39",
    "$sid": 1729148811446,
    "$ct": 1729148895474,
    "$tz": 28800000,
    "$url": "http://172.16.11.211:8585/base",
    "$cn": "js",
    "$ref": "http://172.16.11.211:8585/#%E5%88%9D%E5%A7%8B%E5%8C%96%E5%AE%8C%E6%88%90(READY)",
    "$referrer_domain": "172.16.11.211"
  }
}

点击监听(CLICK)

在全埋点点击事件上报前触发，此状态下可以在事件上报前修改事件数据，如果返回false则取消事件上报。

tracker.hook(LifecycleEvent.CLICK, (data: ZGTypes.UploadData['data'][0], targetElement: HTMLElement) => {
  // 如果返回false，则阻止当次上报
  return {
    // 拓展属性
    '拓展属性名': '拓展属性值'
    '修改属性名': '修改属性值'
  }
})

事件上报前(BEFORE_EVENT_UPLOAD)

在事件上报前触发，此状态下可以在事件上报前修改事件数据，如果返回false则取消事件上报。

tracker.hook(LifecycleEvent.BEFORE_EVENT_UPLOAD, (data: ZGTypes.UploadData['data'][0]) => {
  return {
    // 拓展属性
    '拓展属性名': '拓展属性值'
    '修改属性名': '修改属性值'
  }
});
tracker.hook(LifecycleEvent.BEFORE_EVENT_UPLOAD, (data: ZGTypes.UploadData['data'][0]) => {
  // 阻止数据上报
  return false
});

注意: 返回的数据会覆盖原有数据，如果返回false则取消事件上报

数据样例：

{
  "dt": "abp",
  "pr": {
    "$eid": "click", // 点击事件
    "$page_url": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$page_title": "Document",
    "$element_id": null,
    "$element_type": "BUTTON",
    "$element_style": "ant-btn css-dev-only-do-not-override-vryruh ant-btn-primary ant-btn-color-primary ant-btn-variant-solid",
    "$element_content": "已复制",
    "$element_selector": "37bd5f3754717ac87218266f1664280b",
    "$sid": 1729148811446,
    "$cuid": "张三",
    "$ct": 1729149219326,
    "$tz": 28800000,
    "$url": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$cn": "js",
    "$ref": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$referrer_domain": "172.16.11.211"
  }
}

{
  "dt": "abp",
  "pr": {
    "$eid": "pv", // 页面浏览事件
    "$page_url": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$page_title": "Document",
    "$sid": 1729148811446,
    "$cuid": "张三",
    "$ct": 1729149217264,
    "$tz": 28800000,
    "$url": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$cn": "js",
    "$ref": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$referrer_domain": "172.16.11.211"
  }
}

{
  "dt": "evt",
  "pr": {
    "$eid": "测试事件", // 自定义事件
    "_自定义属性": "abc",
    "$sid": 1729148811446,
    "$cuid": "张三",
    "$ct": 1729149288955,
    "$tz": 28800000,
    "$url": "http://172.16.11.211:8585/base",
    "$cn": "js",
    "$ref": "http://172.16.11.211:8585/settings",
    "$referrer_domain": "172.16.11.211"
  }
}

全埋点介绍

全埋点包括三种事件：页面点击(click)、页面访问(pv)、页面滚动(scroll)。启用全埋点数据采集，需要在初始化时配置autoTrack为true，如下：

tracker.load('APPKEY', {
  autoTrack: true,
});

注意: 开启全埋点后，默认页面点击与页面访问事件会自动采集

页面浏览(pv)

当页面发生跳转或单页应用(SPA)路由切换时，sdk会自动采集页面浏览事件。

上报数据样例：

{
  "dt": "abp",
  "pr": {
    "$eid": "pv", // 页面浏览事件
    "$page_url": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$page_title": "Document",
    "$sid": 1729148811446,
    "$cuid": "张三",
    "$ct": 1729149217264,
    "$tz": 28800000,
    "$url": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$cn": "js",
    "$ref": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$referrer_domain": "172.16.11.211"
  }
}

sdk支持在开启全埋点的情况下，单独关闭页面浏览事件采集，如下：

tracker.load('APPKEY', {
  autoTrack: true,
  pv: false,
});

通过hook监听LifecycleEvent.BEFORE_EVENT_UPLOAD，可以实现在页面浏览事件上报前修改数据或在指定页面停止采集页面浏览数据，如：

tracker.hook(LifecycleEvent.BEFORE_EVENT_UPLOAD, (data: ZGTypes.UploadData['data'][0]) => {
  // 指定条件页面下阻止页面浏览事件上报
  if (data.pr.$page_url === 'http://domain.com/login') {
    return false; // 返回false阻止事件上报
  }
  if (data.pr.$eid === 'pv') { // 对页面浏览事件数据进行处理
    return {
      // 拓展属性
      '拓展属性名': '拓展属性值'
      '修改属性名': '修改属性值'
    }
  }
});

点击事件(click)

SDK会自动采集当前页面所有的有效元素点击事件，有效元素点击判断规则：

1. 通过addEventListener绑定点击事件的元素
2. 通过onclick属性绑定点击事件的元素
3. 通过a标签的href属性跳转的元素，且href属性不为空及不为javascript:开头
4. 可点击的button元素

点击行为在普通事件采集(track)基础上，增加了一些内置属性：

• $page_title：页面标题
• $element_id：元素id
• $element_content：元素的文本内容
• $element_type：元素的标签类型
• $element_style：元素的样式名称
• $element_selector：元素的选择器

上报数据样例:

{
  "dt": "abp",
  "pr": {
    "$eid": "click", // 点击事件
    "$page_url": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$page_title": "Document",
    "$element_id": null,
    "$element_type": "BUTTON",
    "$element_style": "ant-btn css-dev-only-do-not-override-vryruh ant-btn-primary ant-btn-color-primary ant-btn-variant-solid",
    "$element_content": "已复制",
    "$element_selector": "37bd5f3754717ac87218266f1664280b",
    "$sid": 1729148811446,
    "$cuid": "张三",
    "$ct": 1729149219326,
    "$tz": 28800000,
    "$url": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$cn": "js",
    "$ref": "http://172.16.11.211:8585/#%E4%BA%8B%E4%BB%B6%E4%B8%8A%E6%8A%A5%E5%89%8D(BEFORE_EVENT_UPLOAD)",
    "$referrer_domain": "172.16.11.211"
  }
}

sdk支持在开启全埋点的情况下，单独关闭点击事件采集，如下：

tracker.load('APPKEY', {
  autoTrack: true,
  click: false,
});

如果元素标记了zgclickdisable属性或class中带有zgclickdisable，则不采集该元素的点击事件，如：

<button zgclickdisable="true">不采集点击事件</button>

<button class="zgclickdisable">不采集点击事件</button>

通过hook监听LifecycleEvent.BEFORE_EVENT_UPLOAD，可以实现在点击事件上报前修改数据或在指定元素停止采集点击数据，如：

tracker.hook(LifecycleEvent.BEFORE_EVENT_UPLOAD, (data: ZGTypes.UploadData['data'][0]) => {
  // 指定条件元素下阻止点击事件上报
  if (data.pr.$element_selector === '37bd5f3754717ac87218266f1664280b') {
    return false; // 返回false阻止事件上报
  }
  if (data.pr.$eid === 'click') { // 对点击事件数据进行处理
    return {
      // 拓展属性
      '拓展属性名': '拓展属性值'
      '修改属性名': '修改属性值'
    }
  }
});

自定义点击规则

除了内置点击规则外，还可以通过isClickAble配置项自定义点击事件的采集规则，如：

tracker.load('APPKEY', {
  autoTrack: true,
  isClickAble: (element: HTMLElement) => {
    // 自定义点击规则
    return {
      clickable: true, // 是否可点击
      target: element, // 点击目标元素
    };
  },
});

注意:

1. isClickAble返回值为object，包含clickable和target两个属性，clickable为true时，表示该元素可点击，target为点击目标元素。
2. 启用isClickAble后，SDK内置的点击事件采集规则将失效。

页面滚动(scroll)

当开启了落地页数据采集时，sdk会自动采集页面滚动事件。开启方式：

tracker.load('APPKEY', {
  autoTrack: true,
  openLanding: true,
});

落地页滚动事件采集，只会在落地页时采集，非落地页不会采集。

落地页概念定义：用户会话中的第一个页面，且网页来源网址为空或来源网址与当前网址不同。即视该页面为落地页。

如果想所有页面都能够使用分析平台中「广告监测-落地页」分析模型分析业务数据时，可以开启alwaysLanding配置项，如下：

tracker.load('APPKEY', {
  autoTrack: true,
  openLanding: true,
  alwaysLanding: true,
});

注意:

1. 开启落地页采集，需要先开启全埋点自动采集。
2. 落地页滚动数据采集，只能采集到页面整体滚动的数据，无法采集到局部滚动的数据。
3. 慎重开启alwaysLanding配置项，因为会导致所有页面都会被识别为落地页，滚动数据频繁上报会造成一定数据量压力。

可视化埋点

通过JS可视化埋点功能，产品、运营等非技术人员可以通过可视化的方式，自定义埋点事件，无需开发人员介入，提高数据采集效率。

开启可视化埋点方式：

tracker.load('APPKEY', {
  visualizer: true,
});

全埋点支持的可采集元素规则，与全埋点可点击元素规则一致，详情请参考点击事件(click)。

注意:

1. 通过可视化功能添加的埋点事件，会高度依赖页面结构，建议在页面结构稳定的情况下使用，或为元素添加唯一ID标识（元素id属性）。
2. 可视化埋点功能，在页面结构比较稳定且业务场景比较简单的情况下使用效果更佳。复杂业务场景下，建议使用JS代码埋点方式进行埋点，可以实现更加灵活的控制埋点逻辑，得到更加精准的数据。

页面停留时长统计

停留时长默认不采集，如需采集，需要在load方法时，打开duration开关，代码示例如下：

tracker.load('APPKEY', {
  duration: true,
});

采集的页面停留时长单位为毫秒，打开页面到离开页面，即视为一次页面停留，时间差即为「页面停留时长」。

sdk内部实现逻辑，会在浏览器支持的情况下，优先使用requestAnimationFrame机制来实现时长统计，当页面隐藏或后台运行时（如浏览器最小化或tab页发生了切换）会自动停止计时，使停留时长的统计更加精确。

当旧版本浏览器不支持requestAnimationFrame时，会采用定时器方式循环计时，间隔为500毫秒。

数据上报样例:

{
  "dt": "abp",
  "pr": {
    "$eid": "dr",
    "$url": "http://172.16.11.211:8585/settings",
    "$page_url": "http://172.16.11.211:8585/settings",
    "$dr": 6848,
    "$sid": 1729154850388,
    "$ct": 1729160412612,
    "$tz": 28800000,
    "$cn": "js",
    "$ref": "http://172.16.11.211:8585/settings",
    "$page_title": "Document",
    "$referrer_domain": "172.16.11.211"
  }
}

曝光采集

用户使用约定的规则标记元素，元素由不可见变为可见时,sdk会自动采集配置在元素上的自定义事件名称和事件属性，会以自定义事件的方式采上传数据。

使用曝光采集，需要在初始化时配置exposure为true，如下：

tracker.load('APPKEY', {
  exposure: true,
});

在DOM元素中增加zhuge-expo-track类名，使用data-expo-xxx="yyy"的形式设置自定义事件名称和事件属性，其中data-expo-name="evt"会被识别为事件名其他标记会识别为事件属性。

页面元素赋值规则：

<div
  class="zhuge-expo-track"
  data-expo-name="曝光元素1"
  data-expo-id="1"
  data-expo-pos="滚动展示"
></div>

上报数据为：

{
  "dt": "evt",
  "pr": {
    "$eid": "曝光元素1",
    "_id": "1",
    "_pos": "滚动展示",
    "$sid": 1729154850388,
    "$ct": 1729155073691,
    "$tz": 28800000,
    "$url": "http://172.16.11.211:8585/exposure",
    "$cn": "js",
    "$ref": "http://172.16.11.211:8585/",
    "$referrer_domain": "172.16.11.211"
  }
}

注意:

1. 元素曝光采集，只是sdk内置的一种快捷埋点方式，只覆盖基础曝光场景；内部实现逻辑同样是通过触发track来进行埋点上报；因此如果内置的曝光采集触发时机、业务场景、属性支撑能力等方面不满足业务需求时，请自行通过track埋点方式进行上报。
2. 曝光采集需使用Observer API，不支持IE11及以下浏览器，具体浏览器兼容情况参考：IntersectionObserver

SDK API

SDK初始化(load)

• 功能描述：sdk初始化主入口方法。
• 参数
  • appKey：字符串类型，应用标识。
  • config：可选，ZGTypes.Config类型，配置对象。
• 调用示例

import Tracker from '@zgfe/js-sdk';

const tracker = new Tracker();
const appKey = 'your_app_key';
const config = {
  // 其他配置项...
};
tracker.load(appKey, config);

注意： 每个Tracker的示例对象只能调用一次load方法，多次调用会导致数据上报异常。

设置配置信息(setConfig)

• 功能描述：设置配置信息。
• 参数
  • config：ZGTypes.Config类型，配置对象。

调用示例

const config = {
  // 其他配置项...
};
tracker.setConfig(config);

注意： 该方法会覆盖之前的配置信息。

获取配置信息(getConfig)

• 功能描述：获取当前配置信息。
• 返回值：ZGTypes.Config类型，当前配置信息。
• 调用示例

const config = tracker.getConfig();

阻止数据上报(setBlockUpload)

• 功能描述：阻止数据上报。

• 参数

  • flag：布尔类型，是否阻止数据上报。

• 调用示例

  tracker.setBlockUpload(true);

  注意： 该方法会阻止数据上报，直到调用setBlockUpload(false)解除阻止。且期间数据会彻底丢失，请慎重调用。

自定义事件(track)

• 功能描述：自定义事件埋点。
• 参数
  • eventName：字符串类型，事件名称。
  • data：可选，Record<string, any>类型，sdk自定义事件属性。
  • callback：可选，Function类型，回调函数。
• 调用示例

在你希望记录用户行为的位置，自定义事件，调用如下代码：

const eventName = 'custom_event';
const data = {
  property1: 'value1',
  property2: 'value2',
};
tracker.track(eventName, data);

在传统网页中，如果在track后，页面需要进行跳转，浏览器页面跳转时，会将未完成的网络请求取消发送，此时若track请求未及时发出，会造成数据丢失，此时可以通过将页面跳转放到回调函数中执行进行规避，也可以在跳转后补充上报track，避免数据丢失，回调函数应用示例代码如：

const eventName = 'custom_event';
const data = {
  property1: 'value1',
  property2: 'value2',
};
tracker.track(eventName, data, () => {
  // 页面跳转逻辑
});

注意：

1. 事件名称不能超过20个字符。
2. 属性名称不能超过255个字符
3. 属性值不能超过200个字符
4. 页面编码请使用UTF-8编码，否则会导致中文数据内容上报时乱码。
5. 在添加事件属性时，需注意事件属性类型。如果事件属性类型为「数值型属性」，需要在上传数据时修改数据类型为「数值型」，并且在诸葛io后台埋点管理中修改为「数值型」；

用户标识(identify)

为了保持对用户的跟踪，你需要为他们记录一个识别码，可以使用手机号、email 等唯一值来作为用户的识别码。另外，也可以在跟踪用户的时候， 记录用户更多的属性信息，便于你更了解你的用户

• 功能描述：用户实名认证绑定。
• 参数
  • cuid：字符串类型，用户唯一标识。
  • data：可选，Record<string, any>类型，用户属性。
  • callback：可选，Function类型，回调函数。
• 调用示例

const cuid = 'user_unique_id';
const userData = {
  name: 'John Doe',
  age: 30,
};
tracker.identify(cuid, userData);

在非SPA产品中，如果在identify后，页面需要进行跳转，浏览器页面跳转时，会将未完成的网络请求取消发送，此时若identify请求未及时发出，会造成数据丢失，此时可以通过将页面跳转放到回调函数中执行进行规避，也可以在跳转后补充上报identify，避免数据丢失，回调函数应用示例代码如：

const cuid = 'user_unique_id';
const userData = {
  name: 'John Doe',
  age: 30,
};
tracker.identify(cuid, userData, () => {
  // 页面跳转逻辑
});

退出用户标识(logout)

• 功能描述：退出登录，清空当前用户的cuid并强制结束当前会话。
• 调用示例

tracker.logout();

注意： 退出登录后，用户的cuid将被清空，下次访问时将被视为新用户。并且该方法调用，并不影响客户自己业务逻辑中的用户登录状态。

日志打印(showLog)

开启log打印时，SDK会在控制台打印比较详细的日志信息。以便于开发者调试。请在生产环境关闭日志打印，避免数据泄露。

• 功能描述：日志打印开关控制。
• 参数
  • flag：布尔类型，是否显示日志。
• 调用示例

const flag = true;
tracker.showLog(flag);

开启事件时长统计(startTrack)

若你希望统计一个事件发生的时长，比如视频的播放，页面的停留，可以使用startTrack和endTrack方法来实现事件时长统计。调用startTrack方法时，会记录事件开始时间，调用endTrack方法时，会记录事件结束时间，并上报事件时长。调用startTrack和endTrack方法时，需要传入相同的事件名称。

• 功能描述：开启事件时长统计，标记事件开始（本身不触发数据上报）。
• 参数
  • eventName：字符串类型，事件名称。
• 调用示例

const eventName = 'event_to_track_duration';
tracker.startTrack(eventName);

上报事件时长(endTrack)

请确保调用endTrack方法时，传入的事件名称与调用startTrack方法时传入的事件名称一致。并且endTrack方法的调用时机应该在startTrack方法之后。

• 功能描述：结束事件时长统计并上报相关数据。
• 参数
  • eventName：字符串类型，事件名称。
  • props：可选，Record<string, any>类型，事件属性。
• 调用示例

const eventName = 'event_to_track_duration';
const props = {
  additionalProperty: 'value',
};
tracker.endTrack(eventName, props);

页面浏览(pv)

• 功能描述：上报页面浏览(pv)事件。
• 参数
  • extraProps：可选，Record<string, any>类型，页面浏览事件属性。

调用该方法，会自动上报当前页面浏览事件。通常在关闭全局pv自动采集时，可以使用该方法手动上报页面浏览事件。

• 功能描述：上报页面浏览(pv)事件。
• 调用示例

tracker.pv();

// 上报页面浏览事件，并携带额外属性
const extraProps = {
  additionalProperty: 'value',
};
tracker.pv(extraProps);

点击事件(click)

• 功能描述：上报点击事件。
• 参数
  • extraProps：可选，Record<string, any>类型，点击事件属性。
• 调用示例

tracker.click();

注意： 该方法上报的点击事件，会无法和元素信息进行关联绑定，请慎重使用。

更新UTM(setUTM)

utm信息包括：utm_source, utm_medium, utm_campaign, utm_content, utm_term。调用该方法，会更新当前会话的UTM信息。

• 功能描述：更新UTM信息。
• 参数
  • utm：Record<string, any>类型，要更新的UTM信息。
• 调用示例

const utm = {
  utm_source: 'new_source',
  utm_medium: 'new_medium',
};
tracker.setUTM(utm);

设置全局事件属性(setSuperProperty)

设置全局事件属性后，所有事件上报都会携带全局事件属性，当属性名与具体埋点的自定义属性冲突，则以具体埋点的属性为准进行上报。

• 功能描述：设置全局事件属性，覆盖之前的所有全局事件属性。
• 参数
  • data：Record<string, any>类型，要设置的全局事件属性。
• 调用示例

const globalData = {
  globalProperty1: 'value1',
  globalProperty2: 'value2',
};
tracker.setSuperProperty(globalData);

该方法会将已设置的全局属性全部覆盖，比如当前已有全局属性a、b、c，调用该方法传入属性d后，sdk后续全局属性只会生效属性d

拓展全局事件属性(extendSuperProperty)

拓展全局事件属性，会将传入的事件属性合并到已有的全局事件属性中。

• 功能描述：拓展全局事件属性，在之前的全局事件属性上进行拓展，同名属性会被覆盖。
• 参数
  • data：Record<string, any>类型，要拓展的全局事件属性。
• 调用示例

const additionalData = {
  newGlobalProperty: 'value',
};
tracker.extendSuperProperty(additionalData);

比如当前已有全局属性a、b、c，调用该方法传入属性d后，sdk后续全局属性会同时生效a、b、c、d，若传入的属性已存在，会以最新传入的属性为准进行覆盖

获取全局事件属性(getSuperProperty)

• 功能描述：获取全局事件属性。
• 返回值：Record<string, any>类型，全局事件属性。
• 调用示例

const superProperties = tracker.getSuperProperty();

移除全局事件属性(removeSuperProperty)

• 功能描述：移除全局事件属性。
• 参数
  • key：字符串类型，要移除的全局事件属性名称，支持字符串及字符串数组格式。
• 调用示例

// 删除单个全局属性
const keyToRemove = 'globalProperty1';
tracker.removeSuperProperty(keyToRemove);
// 删除多个全局属性
const keysToRemove = ['globalProperty1', 'globalProperty2'];
tracker.removeSuperProperty(keysToRemove);

调试模式切换(debug)

你可以使用实时调试功能实时看到所有的操作信息，以辅助开发者确认打点是否正确（实时调试过程中的数据仅用于调试，不影响正式数据，调试完成后请关闭debug）；调用zhuge.load()时，通过设置debug参数，开启实时调试

• 功能描述：调试模式开关。
• 参数
  • flag：布尔类型，是否开启调试模式。
• 调用示例

const debugFlag = true;
tracker.debug(debugFlag);

注意: 实时调试功能仅支持在开发阶段做开发调试支持，请勿在生产环境中开启调试模式，否则会影响正常数据上报甚至数据丢失。

获取设备ID(getDid)

• 功能描述：获取设备ID。
• 返回值：设备ID（字符串类型）。
• 调用示例

const did = tracker.getDid();

获取会话ID(getSid)

• 功能描述：获取当前会话ID。
• 返回值：当前会话ID（可能为数字或其他类型，取决于内部实现）。
• 调用示例

const sid = tracker.getSid();

获取APPKEY(getKey)

• 功能描述：获取当前应用标识。
• 返回值：当前应用标识（字符串类型）。
• 调用示例

const appKey = tracker.getKey();

收入事件上报trackRevenue

收入数据采集，需调用trackRevenue函数，自动记录收入事件以及事件属性；price(商品价格)、productID(商品ID)、productQuantity(商品数量)、revenueType(收入类型)为收入事件内置属性，必传项。

• 功能描述：上报收入事件。
• 参数
  • _props：ZGTypes.RevenueProps类型，收入属性。
• 调用示例

const revenueProps = {
  price: 229,
  productID: '小米NFC手环',
  productQuantity: 2,
  revenueType: '手环',
};
tracker.trackRevenue(revenueProps);

其它

EventDataType(事件上报类型参照)

1. platform
   • 对应的值为pl。
   • 描述：代表设备环境信息。
2. event
   • 对应的值为evt。
   • 描述：表示自定义埋点事件。
3. user
   • 对应的值为usr。
   • 描述：用于表示用户实名认证事件。
4. sessionStart
   • 对应的值为ss。
   • 描述：表示会话开始事件。
5. sessionEnd
   • 对应的值为se。
   • 描述：表示会话结束事件。
6. fixed
   • 对应的值为abp。
   • 描述：代表内置埋点事件。
7. adtf
   • 对应的值为adtf。
   • 描述：为广告深度归因专用事件类型。

完整上报数据字典

{
    "sln": "itn", //行业方案，itn：互联网
    "pl": "js", //平台，必填
    "sdk": "js", //SDK平台，必填
    "sdkv": "2.0", //SDK版本，必填
    "owner": "admin", //创建者，必填
    "ut": "2014-02-28 07:25:25", //上传时间，必填
    "tz": 28800000, //时区偏移量，必填
    "debug": 1, //实时调试，1：打开，0：关闭
    "ak": "80df322ceac8497199bf19801d6db7a3", //appKey，必填
    "usr": {
        "did": "5b095e4c076ac7e319fe79c048e13cd3" //设备ID，必填
    },
    "data": [ //数据
        {
            "dt": "usr", //数据类型，usr，用户信息，必填
            "pr": { //数据属性，$为默认属性标识
                "$ct": 1471941345321, //时间戳，毫秒，必填
                "$tz": 28800000, //相对UTC偏移量，必填
                "$cuid": "1234523", //UserID，必填
                "$sid": 1471941345321,
                "$url": "", //当前url
                "$ref": "", //来源网址
                "_name": "张三", //姓名
                "_avatar": "", //头像url
                "_性别": "male" //用户定义属性
            },
        }, {
            "dt": "evt", //数据类型，evt，自定义事件，必填
            "pr": { //数据属性，$为默认属性标识
                "$ct": 1471941345321, //时间戳，毫秒，必填
                "$tz": 28800000, //相对UTC偏移量，必填
                "$cuid": "1234523", //用户ID
                "$sid": 1471941345321 "$url": "", //当前页面url（JS）
                "$ref": "", //来源网址
                "$eid": "购买", //事件名称
                "$referrer_domain": "google.com", //来源网站(JS),由后台根据来源网址进行解析
                "$utm_source": "", //js
                "$utm_medium": "", //js
                "$utm_campaign": "", //js
                "$utm_content": "", //js
                "$utm_term": "", //js
                "_平台": "天猫", //自定义事件属性
                "_数量": 2,
                "_价格": 3999
            }
        }, {
            "dt": "pl", //数据类型，pl，平台信息
            "pr": {
                "$rs": "1280x720", //设备分辨率
                "$tz": 28800000, // 时区，必填
                "$ct": 1452570066831, // 事件发生时间戳，必填
                "$cuid": "1234523" //用户ID
            }
        }, {
            "dt": "ss", //数据类型，ss，会话开始
            "pr": {
                "$ct": 1471941345321, //会话开始时间，必填
                "$sid": 1471941345321, //会话ID，毫秒，必填
                "$cuid": "1234523",
                "$tz": 28800000, // 时区，必填
                "$cn": "js",
                "$vn": "2.0",
                "$url": "https://docs.google.com/documen", //当前url(JS)
                "$ref": "https://google.com/documen", //来源网址(JS)
                "$referrer_domain": "google.com", //来源网站(JS),由后台根据来源网址进行解析
                "$utm_source": "", //js
                "$utm_medium": "", //js
                "$utm_campaign": "", //js
                "$utm_content": "", //js
                "$utm_term": "" //js
            }
        }, {
            "dt": "se", //数据类型，se会话结束
            "pr": {
                "$ct": 1471941395321, //会话结束时间，必填
                "$tz": 28800000, // 时区，必填
                "$dru": 50000, //会话时长，毫秒
                "$sid": 1471941345321, //会话ID，毫秒，必填
                "$cuid": "1234523"
            }
        }, {
            "dt": "abp", //数据类型，abp（All buried point）全埋点（目前记录所有内置事件）
            "pr": {
                "$ct": 1471941395321, //会话结束时间，必填
                "$tz": 28800000, // 时区，必填
                "$sid": 1471941345321, //会话ID，毫秒，必填
                "$cuid": "1234523", //用户ID
                "$url": "", //当前页面url（JS）
                "$ref": "", //来源网址
                "$referrer_domain": "", //来源网域名
                "$eid": "pv", //事件名称（包含：pv、click、scroll...）
            }
        }
    ]
}