JS SDK 使用说明

JS SDK 适用于由 HTML 、 Css 及 Javascript 制作成的网站

1. 集成准备

1.1 下载 SDK

最新版本:analysys_JS_v4.1.0

更新时间:2018/09/18

更新内容:

  1. 在初始化配置中新增 encryptType 参数,提供对上传数据可选是否进行加密功能
  2. 增加配置参数 auto 控制启动事件与页面事件是否同时上报
  3. 在 Cookie 中公开 JS 临时 ID
  4. 优化启动事件上报逻辑

1.2 集成 JS SDK

本文之下的 JS SDK 示例地址为:http://sdk.analysys.cn/AnalysysAgent_JS_SDK.min.js,请在接入JS SDK时更改为实际地址。

AnalysysAgent_JS_SDK.min.js:该 JS 文件为 JS SDK 基础统计包。

AnalysysAgent_JS_SDK_VISUAL.min:该 JS 文件为 JS SDK 进行可视化埋点时所需模块。如有可视化埋点需求,请将该文件与 AnalysysAgent_JS_SDK.min.js 存放在同一文件目录中。

1.3 异步载入

将以下JS代码复制到您所需分析页面中的<head></head>标签之间。

<script>
    (function(config) {
        window.AnalysysAgent = window.AnalysysAgent || []
        window.AnalysysAgent.methods = 'identify alias reset track profileSet profileSetOnce profileIncrement profileAppend profileUnset profileDelete registerSuperProperty registerSuperProperties unRegisterSuperProperty clearSuperProperties getSuperProperty getSuperProperties pageView debugMode auto appkey name uploadURL hash visitorConfigURL autoProfile autoWebstay encryptType'.split(' ');

        function factory(b) {
            return function() {
                var a = Array.prototype.slice.call(arguments);
                a.unshift(b);
                window.AnalysysAgent.push(a);
                return window.AnalysysAgent;
            }
        };
        for (var i = 0; i < AnalysysAgent.methods.length; i++) {
            var key = window.AnalysysAgent.methods[i];
            AnalysysAgent[key] = factory(key);
        }
        for (var key in config) {
            AnalysysAgent[key](config[key])
        }
        var date = new Date();
        var time = new String(date.getFullYear()) + new String(date.getMonth() + 1) + new String(date.getDate());

        var d = document,
            c = d.createElement('script'),
            n = d.getElementsByTagName('script')[0];
        c.type = 'text/javascript';
        c.async = true;
        c.id = 'devSDK';
        c.src = window.location.protocol+'//sdk.analysys.cn/AnalysysAgent_JS_SDK.min.js?' + time //JS SDK存放地址
        n.parentNode.insertBefore(c, n);
    })({
        appkey: '' //APPKEY
    })
</script>

请注意将 appkey 的值填入您具体的项目 appkey

1.4 同步载入

将以下 JS 代码复制到您所需分析页面中的<head></head>标签之间。

<script>
    (function(config) {
        window.AnalysysAgent = window.AnalysysAgent || []
        window.AnalysysAgent.methods = 'identify alias reset track profileSet profileSetOnce profileIncrement profileAppend profileUnset profileDelete registerSuperProperty registerSuperProperties unRegisterSuperProperty clearSuperProperties getSuperProperty getSuperProperties pageView debugMode auto appkey name uploadURL hash visitorConfigURL autoProfile autoWebstay encryptType'.split(' ');

        function factory(b) {
            return function() {
                var a = Array.prototype.slice.call(arguments);
                a.unshift(b);
                window.AnalysysAgent.push(a);
                return window.AnalysysAgent;
            }
        };
        for (var i = 0; i < AnalysysAgent.methods.length; i++) {
            var key = window.AnalysysAgent.methods[i];
            AnalysysAgent[key] = factory(key);
        }
        for (var key in config) {
            AnalysysAgent[key](config[key])
        }
    })({
        appkey: '' //APPKEY
    })
</script>

//http协议
<script type="text/javascript" src="http://sdk.analysys.cn/AnalysysAgent_JS_SDK.min.js"></script>

//https协议
<script type="text/javascript" src="https://sdk.analysys.cn/AnalysysAgent_JS_SDK.min.js"></script>

请注意将 appkey 的值填入您具体的项目 appkey

2. SDK 初始化

集成完毕后,需要对集成代码根据您的项目进行配置,配置位置为集成代码中的 appkey 所在位置。

2.1 配置参数

  • appkey(必须) 部署网站中所生成的 appkey
  • debugMode 设置调试模式:0 - 关闭调试模式(默认);1 - 开启调试模式,数据不入库;2 - 开启调试模式,数据入库
  • uploadURL(必须) 设置上传数据接口
  • visitorConfigURL(如使用可视化埋点,则必须) 设置可视化配置获取接口
  • name 设置 JS SDK 全局对象别名
  • auto 设置自动采集页面打开事件:false - 关闭自动采集;true - 开启自动采集(默认)
  • hash 设置检测 url hash 变化:false - 关闭监测url hash变化;true - 开启监测url hash变化(默认)
  • autoProfile 设置是否追踪新用户的首次属性:false - 不追踪新用户的首次属性;true - 追踪新用户的首次属性(默认)
  • autoWebstay 设置是否追踪页面滚动行为:false - 不追踪页面滚动行为(默认);true - 追踪页面滚动行为
  • encryptType 设置是否对上传数据加密:0 - 对上传数据不加密(默认);1 - 对上传数据AES加密

本文之下的所有示例所使用的部署网站中所生成的 appkey 都为 77a52s552c892bn442v721。

2.1.1 appkey

appkey 为在部署网站中所生成的 appkey,为区别数据统计集合的关键字段。请根据您所申请的 appkey 正确填写。

  • value 部署网站中所生成的 appkey。类型:String。长度小于255字符。
//appkey为77a52s552c892bn442v721
{
    appkey:"77a52s552c892bn442v721"
}

2.1.2 debugMode

debugMode 调试模式为接入 JS SDK 后进行数据调试的主要手段。可实时验证 JS SDK 数据监测的正确与否。

  • 0 关闭调试模式(默认)。类型:Number。
  • 1 开启调试模式,数据不入库。类型:Number。
  • 2 开启调试模式,数据入库。类型:Number。
//开启调试模式且数据不入库
{
    appkey:"77a52s552c892bn442v721",
    debugMode:1
}
//开启调试模式且数据入库
{
    appkey:"77a52s552c892bn442v721",
    debugMode:2
}
//关闭调试模式
{
    appkey:"77a52s552c892bn442v721",
    debugMode:0 //或删除debugMode参数
}

或删除 debugMode 参数。

2.1.3 uploadURL

uploadURL 为上传数据接口,参数设置后,所有事件信息将上传到该地址。

  • value 类型:String。必须以http://https:// 开头,长度小于 255字符
//自定义上传地址为`http://......`
{
    appkey:"77a52s552c892bn442v721",
    uploadURL:"http://......"
}

2.1.4 visitorConfigURL

visitorConfigURL 为设置可视化配置获取接口,参数设置后,将从该接口路径获取可视化埋点配置信息。

  • value 类型:String。必须以http://https:// 开头,长度小于 255字符
//自定义上传地址为`http://......`
{
    appkey:"77a52s552c892bn442v721",
    visitorConfigURL:"http://......"
}

2.1.5 name

name 为设置 JS SD K全局对象的别名。可根据自身所需进行更改。

  • value 类型:String。长度小于 255字符。
//设置JS SDK全局对象的别名为analysys,之后可在全局使用analysys来调用JS SDK所有的API方法。
{
    appkey:"77a52s552c892bn442v721",
    name:"analysys"
}

2.1.6 auto

auto 为设置是否开启自动采集页面打开事件的参数。可根据自身需要进行更改。

  • true 开启自动采集页面打开事件(默认)。类型:Boolean。
  • false 关闭自动采集页面打开事件。类型:Boolean。
//关闭自动采集页面打开事件,关闭后可使用JS SDK的API中的手动发送页面打开数据方法,来发送页面打开状态的数据。
{
    appkey:"77a52s552c892bn442v721",
    auto:false
}
//开启自动采集页面打开事件。
{
    appkey:"77a52s552c892bn442v721",
    auto:true//或删除auto参数。
}

2.1.7 hash

hash 为设置是否自动监测 url hash 变化的参数。可根据自身需要进行更改。

  • true 开启自动采集监测 url hash 变化(默认)。类型:Boolean。
  • false 关闭自动采集监测 url hash 变化。类型:Boolean。
//关闭自动采集监测url hash变化,关闭后可使用JS SDK的API中的手动发送页面打开数据方法,来发送url hash变化状态的数据。
{
    appkey:"77a52s552c892bn442v721",
    hash:false
}
//开启自动采集监测url hash变化。
{
    appkey:"77a52s552c892bn442v721",
    hash:true//或删除hash参数。
}

2.1.8 autoProfile

autoProfile 为设置是否追踪新用户的首次属性。可根据自身需要进行更改。

  • true 追踪新用户的首次属性(默认)。类型:Boolean。
  • false 不追踪新用户的首次属性。类型:Boolean。
//不追踪新用户的首次属性,新用户首次打开网站不上传新用户的首次属性。
{
    appkey:"77a52s552c892bn442v721",
    autoProfile:false
}
//追踪新用户的首次属性,新用户首次打开网站上传新用户的首次属性。
{
    appkey:"77a52s552c892bn442v721",
    autoProfile:true//或删除autoProfile参数。
}

2.1.9 autoWebstay

autoWebstay 为设置是否追踪页面滚动行为。可根据自身需要进行更改。

  • true 追踪页面滚动行为。类型:Boolean。
  • false 不追踪页面滚动行为(默认)。类型:Boolean。
//不追踪页面滚动行为。
{
    appkey:"77a52s552c892bn442v721",
    autoWebstay:false//或删除autoWebstay参数。
}
//追踪页面滚动行为。
{
    appkey:"77a52s552c892bn442v721",
    autoWebstay:true
}

2.1.10 encryptType

encryptType 为设置是否对上传数据加密。可根据自身需要进行更改。

  • 0 对上传数据不加密(默认)。类型:Number。
  • 1 对上传数据 AES 加密。类型:Number。
//对上传数据不加密。
{
    appkey:"77a52s552c892bn442v721",
    encryptType:0//或删除encryptType参数。
}
//对上传数据AES加密。
{
    appkey:"77a52s552c892bn442v721",
    encryptType:1
}

3. 基础接口介绍

3.1 统计页面

页面跟踪,SDK 默认设置跟踪所有页面,支持自定义页面信息。接口如下:

AnalysysAgent.pageView(pageName);
AnalysysAgent.pageView(pageName, properties);
  • pageName:页面标识,为字符串,最大长度 255字符
  • properties:页面信息,properties 最多包含 100条,且 key 以字母或 $ 开头,包含字母、数字、下划线和 $,字母不区分大小写,$ 开头为预置事件/属性,不支持乱码和中文,最大长度 255字符,value 支持类型:String/Number/boolean/Json/Array,若为字符串,最大长度 255字符

示例:

// 正在开展某个活动,需要统计活动页面;
AnalysysAgent.pageView("活动页");

......

// 访问手机活动页面,活动页面内容为优惠出售iPhone手机,手机价格为5000元
var properties ={
    "commodityName": "iPhone",
    "commodityPrice": 8000
}

AnalysysAgent.pageView("商品页", properties);

3.2 统计事件

用户行为追踪,可以设置自定义属性。接口如下:

AnalysysAgent.track(eventName, eventInfo)
  • eventName:事件名称,以字母或 $ 开头,包含字母、数字、下划线和 $,字母不区分大小写,$ 开头为预置事件/属性,不支持乱码和中文,最大长度 99字符
  • eventInfo:自定义属性,用于对事件描述。eventInfo 最多包含 100条,且 key 以字母或 $ 开头,包含字母、数字、下划线和 $,字母不区分大小写,$ 开头为预置事件/属性,不支持乱码和中文,最大长度 125字符,value 支持类型:String/Number/boolean/Json/Array,若为字符串,最大长度 255字符

示例:

// 添加事件
AnalysysAgent.track("back");

......

// 用户购买手机
var eventInfo = {
    "type":"Phone",
    "name":"Apple iPhone8",
    "money":4000,
    "count":1
}
AnalysysAgent.track("buy", eventInfo);

3.3 用户关联

用户 id 关联接口。将 aliasIDoriginalId 关联,计算时会认为是一个用户的行为。接口如下:

AnalysysAgent.alias(aliasId, originalId);
  • aliasId:新的唯一用户 id。 长度大于 0,且小于 255字符
  • originalId:待关联的用户 id,可以是现在使用也可以是历史使用的 id,不局限于本地正使用的 Id。 可以为空值,若为空时使用本地的 distinctId。长度大于 0且小于 255字符

示例:

// 登陆账号时调用,只设置当前登陆账号即可和之前行为打通
AnalysysAgent.alias("sanbo", "");

......

//现在登陆账号是zhangsan,和历史上的 lisi是一个人。 此时不会关心登陆 zhangsan前的用户是谁
AnalysysAgent.alias("zhangsan", "lisi");

3.4 用户属性设置

用户属性是一个标准的 K-V 结构,K 和 V 均有相应的约束条件,如不符合则丢弃该次操作。

约束条件如下:

属性名称
以字母或`$`开头,包含字母、数字、下划线和`$`,字母不区分大小写,`$`开头为预置事件/属性,不支持乱码和中文,最大长度125字符
属性值
支持部分类型:String/Number/Boolean/Json/Array;若为字符串,则最大长度 255字符;若为 Array 或 Json,则最多包含 100条,且 key 约束条件与属性名称一致,value 最大长度 255字符

给用户设置单个或多个属性,如果之前不存在,则新建,否则覆盖。接口如下:

//设置单个用户属性
AnalysysAgent.profileSet(propertyName, propertyValue);
//设置多个用户属性
AnalysysAgent.profileSet(property);

示例:

//设置用户的邮箱地址为yonghu@163.com
AnalysysAgent.profileSet("Email", "yonghu@163.com");

......

// 设置用户的邮箱和微信
var property = {
    "Email" : "yonghu@163.com",
    "WeChatID" : "weixinhao"
}
AnalysysAgent.profileSet(property);

4. 更多接口

4.1 用户属性

4.1.1 用户 ID 设置

唯一身份标识设置,接口如下:

AnalysysAgent.identify(distinctId);
  • distinctId:唯一身份标识,长度大于 0且小于 255字符

示例:

// 淘宝店铺,统计到来访用户
AnalysysAgent.identify("fangke009901");

......

// 淘宝店铺,统计到老客用户
AnalysysAgent.identify("laoke008021");

4.1.2 设置用户固有属性

设置用户的固有属性,只在首次设置时有效的属性。 如:应用的激活时间、首次登录时间等。如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据,如果属性不存在则会自动创建。接口如下:

AnalysysAgent.profileSetOnce(propertyName, propertyValue);

AnalysysAgent.profileSetOnce(property);

示例:

// 设置用户激活时间
AnalysysAgent.profileSetOnce("activationTime",1521280551929);

// 设置用户性别和出生时间
var setOnceProfile = {
    "birth": 548798705000,
    "sex": "male"
}
AnalysysAgent.profileSetOnce(setOnceProfile);

4.1.3 设置用户属性相对变化值

设置用户属性的相对变化值(相对增加,减少),只能对数值型属性进行操作,如果这个 Profile之前不存在,则初始值为0。接口如下:

AnalysysAgent.profileIncrement(propertyName, propertyNumber)

AnalysysAgent.profileIncrement(property);

示例:

//用户增加一岁
AnalysysAgent.profileIncrement("age",1);

......

//用户玩某个游戏时间增加一年,游戏等级增加2
var incrementProfile = {
    "gameAge":1,
    "gameRating":2
}
AnalysysAgent.profileIncrement(incrementProfile);

4.1.4 增加列表类型的属性

用户列表属性增加元素。接口如下:

//增加单个属性
AnalysysAgent.profileAppend(propertyName, propertyValue);
//增加多个属性
AnalysysAgent.profileAppend(propertyValue);
//增加多个属性
AnalysysAgent.profileAppend(propertyName, propertyValue);

示例:

// 增加用户爱好 music
AnalysysAgent.profileAppend("hobby", "Music");

// 增加多个用户属性
var map = {
    "hobby": "PlayBasketball",
    "sports": "Run"
};
AnalysysAgent.profileAppend(mContext, map);

//增加多个用户爱好
var list = ["PlayBasketball", "music"];
AnalysysAgent.profileAppend("hobby", list);

4.1.5 删除设置的属性

删除已设置的用户属性。接口如下:

AnalysysAgent.profileUnset(propertyName);
AnalysysAgent.profileDelete();

示例:

// 删除单个用户属性
AnalysysAgent.profileUnset( "age");

// 清除所有属性
AnalysysAgent.profileDelete();

4.2 通用属性

通用属性是每次上传事件信息都会带有的属性,通用属性是一个标准的 K-V 结构,K 和 V 均有相应的约束条件,如不符合则丢弃该次操作。

约束条件如下:

属性名称
以字母或`$`开头,包含字母、数字、下划线和`$`,字母不区分大小写,`$`开头为预置事件/属性,不支持乱码和中文,最大长度125字符
属性值
支持部分类型:String/Number/boolean/Json/Array;若为字符串,则最大长度 255字符;若为 Array 或 Json,则最多包含 100条,且 key 约束条件与属性名称一致,value 最大长度255字符

4.2.1 注册通用属性

某一个体,在固定范围内,持续拥有的属性,每次数据上传都会携带。接口如下:

AnalysysAgent.registerSuperProperty(superPropertyName , superPropertyValue );

AnalysysAgent.registerSuperProperties(superProperty);

示例:

// 在某视频平台,购买一年会员,该年内只需设置一次即可
AnalysysAgent.registerSuperProperty("member","VIP");

......

// 小明在20岁的时候,购买了一年腾讯会员
var property = {
    "platform":"TX",
    "age":"20",
    "member":"VIP",
    "user":"xiaoming"
}
AnalysysAgent.registerSuperProperties(property);

4.2.2 删除通用属性

根据属性名称,删除已设置过的通用属性。接口如下:

//删除单个通用属性
AnalysysAgent.unRegisterSuperProperty(superPropertyName);
//清除所有通用属性
AnalysysAgent.clearSuperProperties();

示例:

// 删除已经设置的用户年龄属性
AnalysysAgent.unRegisterSuperProperty("age");

......

// 清除所有已经设置的通用属性
AnalysysAgent.clearSuperProperties();

4.2.3 获取通用属性

查询获取通用属性。接口如下:

// 获取单个通用属性
AnalysysAgent.getSuperProperty(superPropertyName);
// 获取所有的通用属性
AnalysysAgent.getSuperProperties();

示例:

// 查看已经设置的"member"的通用属性
AnalysysAgent.getSuperProperty("member");

......

// 查看所有已经设置的通用属性
AnalysysAgent.getSuperProperties();

4.3 清除本地设置

清除本地现有的设置(包括 id 和通用属性)重新开始统计。接口如下:

AnalysysAgent.reset();

示例:清除本地现有的设置,包括id和通用属性

// 删除设置的id和通用属性
AnalysysAgent.reset();

4.4 可视化埋点说明

4.4.1 接入 JS SDK 可视化模块

AnalysysAgent_JS_SDK_VISUAL.min.js 放到与 JS SDKAnalysysAgent_JS_SDK.min.js 文件存放在同一文件目录中。

4.4.2 设置可视化配置获取接口

{
    appkey:"77a52s552c892bn442v721",
    visitorConfigURL:"http://......"
}

4.4.3 允许 iframe 加载

使用可视化埋点功能需要使用 iframe 来加载您的网站。如果您的网站禁止了 iframe 加载,就无法使用可视化埋点功能,需要在服务器配置中设置 X-Frame-Options 允许 iframe 加载。

//您的网站为https协议,https://xxx.xxx.xxx为您的本地化产品域名
X-Frame-Options: Allow-From https://xxx.xxx.xxx
//您的网站为http协议,http://xxx.xxx.xxx为您的本地化产品域名
X-Frame-Options: Allow-From http://xxx.xxx.xxx

4.4.4 window对象

以下 window 对象中的属性被复写后将导致可视化埋点功能无法正常使用。

window.top
window.parent
window.name
window.location
Copyright © 2018 易观版权所有 京ICP备15065619号-1 京公网安备110105005360号            updated 2018-10-15 19:34:46

results matching ""

    No results matching ""