Web SDK 集成

优质

小牛编辑

143浏览

2023-12-01

1. 安装诸葛SDK

在每个页面的<head>和</head>标签中，嵌入下面代码，完成SDK的安装。

注意：一个页面只可引入一个js文件，且只能有一个App key。

<script type = "text/javascript">
  (function() {
    if (window.zhuge) return;
    window.zhuge = [];
    window.zhuge.methods = "_init identify track trackRevenue getDid getSid getKey setSuperProperty setUserProperties setWxProperties setPlatform".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://zgsdk.zhugeio.com/zhuge.min.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('002714230c264ddda7d94375a4d23e40', { //配置应用的AppKey
      superProperty: { //全局的事件属性(选填)
        '应用名称': '诸葛io'
      },
       adTrack:false,     //广告监测开关，默认为false  
        zgsee:false,      //视屏采集开关，默认为false
        autoTrack: false, //启用全埋点采集（选填，默认false）   
        singlePage: false //是否是单页面应用（SPA），启用autoTrack后生效（选填，默认false）,
        duration: false //页面停留时长采集开关，默认为false
    });
})(); 
</script>

2. 识别用户

为了保持对用户的跟踪，你需要为他们记录一个识别码，你可以使用用户id、email等唯一值来作为用户的识别码。

zhuge.identify('0202033');

你也可以记录用户的更多属性信息，便于你更了解你的用户（推荐）：

zhuge.identify('0202033', {
    name: '张三',         //预定义属性
    avatar: '头像地址',   //预定义属性
    '行业': '互联网'      //自定义属性
});

注意：

name和avatar属性为预定义属性，如果需要上传⽤户名或头像，请确保属性名无误；时间类型的属性建议以「日期的字符串」形式上传；
用户属性如果为空，可以不传。

建议：

通常identify打点是在用户登录或注册操作时进行，当用户登录或注册后，通常我们会跳转到其它页面(例如：首页／个人中心等等)；如果页面跳转，identify请求可能会出现被浏览器中断而无法完成的情况，那么，该用户的后续行为就会被统计为匿名用户行为。

常规打点方式:

zhuge.identify('0202033', {
    name: '张三',     //预定义属性 
    gender: '男',    //预定义属性
    '行业': '互联网'  //自定义属性
});
location.href = 'http://www.xxx.com/index.html';

推荐打点方式：

常规打点方式中identify调用之后会立马进行页面跳转，由于大多数浏览器机制原因，可能会取消请求导致identify请求失败。因此，推荐在identify的回调中执行页面跳转（此方法只针对当前页面跳转的方式），具体打点方式如下：

zhuge.identify('0202033', {
    name: '张三',     //预定义属性
    gender: '男',    //预定义属性
    '行业': '互联网'  //自定义属性
},
function() {
    location.href = 'http://www.xxx.com/index.html'; //执行identify成功后的代码，比如：跳转页面
});

3. 自定义事件

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

zhuge.track('购买手机');   //事件名称不能超过20个字符

你也可以通过属性记录更多的行为信息：

zhuge.track('购买手机', {
    '手机' : '小米4',
    '价格' : 1799,  //数值型属性不要带引号
    '运营商' : '移动'});   //属性名称不能超过255个字符，属性值不能超过200个字符

注意：

在添加事件时，如果事件名称为中文，当用户浏览器编码有问题时，事件会在自动生成时变成乱码；在分析平台中即会显示有乱码事件，又会显示原事件；建议事件名称使用英文；
在添加事件属性时，需注意事件属性类型。如果事件属性类型为「数值型属性」，需要在上传数据时修改数据类型为「数值型」，并且在诸葛io后台埋点管理中修改为「数值型」；
事件属性如果为空，可以不传。

建议：

关于事件的埋点时机有以下建议：

尽量在目标页面进行打点，事件属性可以通过url传参形式传递到目标页面；

无法在目标页面打点的情况下，使用track的回调函数，在回调函数中进行页面跳转。

zhuge.track('eventName', {
 'prop1': '这是自定义属性'//事件自定义属性
}, function(){
 location.href = 'http://www.xxx.com/b.html';//执行打点的后续操作,如页面跳转
});

如果是给页面的某些超链接布点，不同链接需要传递不同的参数，并且需要做到不破坏SEO友好(以jQuery语法为例)。

$(".menu-item").click(function() {
 var link = $(this);
 zhuge.track('菜单导航', {
     'menuName': link.text()
 },
 function() {
     location.href = link.attr('href'); //继续跳转到目标页面
 });
 return false;
});

4. 实时调试

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

window.zhuge.load('Your App Key', {debug:true});

5. 设置事件通用属性

事件通用属性

zhuge.setSuperProperty({
  '属性名': '属性值'
});

若有一些属性，每一个事件都要拥有，可以调用setSuperProperty传入。

6. 设置UTM参数

你可以在window.zhuge.load()方法中添加自定义UTM参数，通过UTM参数来跟踪访问你网站的流量来自于哪些渠道、哪些媒介等。

UTM参数信息具体请参照UTM参数标识流量

具体使用方法如下：

 window.zhuge.load('Your App Key',{
         utm: {"utm_source":"baidu",         //广告来源
               "utm_medium":"cpc",           //广告媒介
               "utm_term":"datadriven",      //广告关键字
               "utm_content":"a",            //广告内容
               "utm_campaign":"doublescore"  //广告名称
               }
            });

说明：每次可以通过此方法设置UTM的5个参数中的1个或多个，自定义设置的UTM参数会覆盖掉SDK默认从URL中解析获取的UTM参数（设置几个覆盖几个，没有设置的不覆盖）。

7. 关联微信公众号用户

你可以上传微信公众号appID和对应用户的openID，关联诸葛io用户。

具体使用方法如下：

zhuge.setWxProperties(appID,  openID)

上传后，可用于智能触达通过微信渠道对微信公众号用户进行触达。

8. Web/H5视屏数据采集

视屏数据默认为不采集，如需采集某个用户的视屏数据，可在需要采集该用户视屏数据时，页面接入SDK的代码window.zhuge.load()中，设置如下参数：

  zgsee: true //默认为false

如需关闭采集该用户的视屏数据时，页面接入SDK的代码window.zhuge.load()中设置如下参数：

  zgsee: false

注：

1.视屏采集数量有限制，建议仅采集需要观察、分析的用户的视屏数据；

2.视屏采集数据的浏览器兼容性：Firefox 3.5+、Google Chrome、Opera 12+、IE10+、Safari 6+。

9. 收入数据采集

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

具体使用方法如下：

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

10. 页面停留时长采集

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

duration: false // 页面停留时长采集，默认false

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

11. 元素曝光采集

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

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

zhuge.load('test-appkey', {
  exposure: true
})

<view 
  class="zhuge-expo-track" 
  data-expo-name="首页banner曝光" // 事件名称 “首页banner曝光”
  data-expo-pos="页头" // 事件属性 pos: "页头"
  data-expo-type="商品" // 事件属性 type: "商品"
>
  xxxx
</view>

12. 其他可选API

你可以通过getDid接口来获取当前设备在诸葛体系下的设备标识。

var did = zhuge.getDid();

你可以通过getSid接口来获得当前的会话ID。

var sid = zhuge.getSid();

你可以通过getKey接口来获得当前的appKey。

var appKey = zhuge.getKey();

你可以通过setUserProperties接口来设置用户属性。

zhuge.setUserProperties({
    '属性名': '属性值'
});