1. 初始化相关 API

1.1. setPara( args );

  • 说明:用来配置初始化参数;
  • 参数:args : object , 初始化参数对象,可配置的属性如下
    • name: string , SDK 使用的一个默认的全局变量,会注册在 App 全局函数内,在 Page 中可以通过 app[name].track 来使用,默认值是 sensors 。
    • appid: string , (非必填参数)如果需要使用 initWithOpenid() 方法来完成初始化,需要在神策后端配置 appid 和 appsecret ,同时在这里指定 appid 。
    • server_url: string , 数据接收地址。注意: 请在微信公众平台---开发---开发设置---服务器域名中,把这个地址添加上。
    • autoTrack: object , 是否开启自动采集,六个属性参数( appLaunch、 appShow、 appHide、 pageShow、 pageShare、mpClick),其中 mpClick 默认是 false,其他是 true。即默认采集五个事件 $MPLaunch、$MPShow、$MPHide、$MPViewScreen、$MPShare(0.9以上版本的 SDK 支持),其中 $MPShare 事件 1.9 版本以上支持,$MPClick 事件默认不采集,详细介绍见预置事件。
    • show_log: boolean , 设置 true 后会在模拟器控制台打 logger,会显示发送的数据,设置 false 表示不显示。默认为 true 。
    • send_timeout: number , 请求发送超时时间(如果一个请求发送后,超过规定时间没响应,则继续发送下一条数据),默认为 1000 毫秒。
    • use_client_time: boolean , 因为客户端系统时间的不准确,会导致发生这个事件的时间有误,所以这里默认为 false ,表示不使用客户端时间,使用服务端时间,如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ,注意这里必须是 Date 类型,那么这条数据就会使用你在属性中传入的这个时间。
    • allow_amend_share_path: boolean ,设置 true 后会自动修改 Page.onShareAppMessage 中的 path 属性,新增一些参数包括当前用户的 distinct_id 等,如果要自动采集分享信息,必须设置为 true ,默认为 true 。
    • batch_send: boolean , 小程序中是否使用批量发送数据功能,默认为 false ,配置注意事项详见常见问题 。
    • datasend_timeout: number , 请求发送取消时间(请求发送后,在规定时间内未返回结果,则取消请求),默认为 3000 毫秒(1.12.9 及以上版本支持) 。
    • source_channel: array , 默认情况下,只会解析参数 utm_source、 utm_content、 utm_campaign、 utm_medium、 utm_term 设置到预置事件中,可以通过配置该参数来解析其他自定义参数,例如['from', 'to'] (1.13.8 及以上版本支持) 。
    • is_persistent_save: boolean , 是否需要将最近一次渠道信息保存到 wxStorage 中,默认为 false (1.13.9 及以上版本支持) 。 

1.2. init();

  • 说明:用来标识小程序 SDK 初始化完成,数据可以通过网络发送;此方法不调用,采集的数据会被缓存在内存中,不能通过网络发送;

1.3. setOpenid();

  • 说明:用来将匿名 ID 修改为 openid;

1.4. initWithOpenid();

  • 说明:当客户希望使用 openid 作为匿名 ID,同时不想自己获取 openid 再修改匿名 ID,而是希望神策自动获取 openid,可以使用这个 API.注意事项可以参考常见问题;

2. 采集事件数据 API

2.1. track( eventName,[properties] );

  • 说明:采集自定义事件。
  • 参数:
    • eventName:`string`,必填,事件名称;
    • properties:`object`,选填,为该事件设置的事件属性;

第一次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:电商产品,可以追踪用户注册、浏览商品和下订单等事件。

index.js

// 追踪浏览商品事件。 
var app = getApp();
app.sensors.track('ViewProduct', {
	//String 类型
	ProductName: "MacBook Pro", 
	//Number 类型,-9E15 到 9E15 小数点后最多保留 3 位
	ProductPrice: 123.45, 
	//BOOL 类型,true 或 false
	IsAddedToFav, false
	//List 类型,字符串元素的数组,最大元素个数为 500,其中每个元素使用 UTF-8 编码后最大长度 255 字节
	ProductList:["apple","orange"], 
	//DATETIME 类型,可以直接传 new Date() 或者 传 yyyy-MM-dd HH:mm:ss.SSS / yyyy-MM-dd HH:mm:ss 格式的字符串。
	ViewTime:new Date()
});
JS

2.2. login( userID );

  • 说明:用来做用户关联,当传入的参数与当前 distinct_id 不一致时,会触发 $SignUp 预置事件;
  • 参数:
    • userID: string, 必填,用户 ID 或登录 ID 

2.3. registerApp( properties );

  • 说明:用来给所有事件设置公共属性,可以在 app.js 文件引入 sensorsdata.min.js 文件之后, init() 方法调用之前使用 registerApp() 方法设置公共属性。
  • 参数:
    • properties:object,必填,为该方法调用后的所有事件设置的公共事件属性;

app.js

// 注册事件公共属性。 
var sa = require('sensorsdata.min.js');
sa.setPara({
	name: 'sensors',
	server_url: '数据接收地址'
});
sa.registerApp({
	userLever: 'VIP3',
	userSex: '男'
}); 
sa.init();
JS

2.4. quick( ['appLaunch'|'appShow'|'appHide'|'getAnonymousID'], [options], [properties]);

  • 说明:通过给定的第一个参数,来分别实现不同的功能;
  • 参数:
    • appLaunch:string, 用来发送一条预置事件 $MPLaunch 数据,一般在小程序 App 实例的 onLaunch 生命周期中调用;
      • 第二个参数 options,必须, 需要传入返回的生命周期函数参数对象;
      • 第三个参数 properties,非必须,可以传入要设置给预置事件 $MPLaunch 事件的自定义属性;
    • appShow:string, 用来发送一条预置事件 $MPShow 数据,一般在小程序 App 实例的 onShow 生命周期中调用;
      • 第二个参数 options,必须, 需要传入返回的生命周期函数参数对象;
      • 第三个参数 properties,非必须,要设置给预置事件 $MPShow 事件的自定义属性
    • appHide:string, 用来发送一条预置事件 $MPHide 数据,一般在小程序 App 实例的 onHide 生命周期中调用;
      • 第二个参数 options,非必须, 要设置给预置事件 $MPHide 事件的自定义属性;
    • getAnonymousID:string, 用来获取匿名 ID;

3. 采集用户数据 API

3.1. setProfile( properties );

  • 说明:设置用户的属性,如果存在则覆盖。
  • 参数:
    • properties:object,必填,要给该用户设置的用户属性;

app.js

sa.setProfile({
	email:'xxx@xx',
	favoriteFruits: ['苹果', '油桃'],
	subscribers: 7277
});
JS

3.2. setOnceProfile( properties );

  • 说明:如果不存在同名属性则设置,存在同名属性,同名属性不会重新设置。
  • 参数:
    • properties:object,必填,要给该用户设置的用户属性;

app.js

sa.setOnceProfile({
	email:'xxx@xx',
	favoriteFruits: ['苹果', '油桃'],
	subscribers: 7277
});
JS

3.3. incrementProfile( properties );

  • 说明:增加或减少一个用户的某个 Numeric 类型的 Profile,如果该用户属性不存在则自动创建。
  • 参数:
    • properties:object,必选。

app.js

sa.incrementProfile({
	subscribers: 5
});
JS

3.4. appendProfile( properties );

  • 说明:向某个用户的某个数组类型的 Profile 添加一个或者多个值。
  • 参数:
    • properties:object,必选。

app.js

sa.appendProfile({ 
	favoriteFruits: ['葡萄', '香蕉'] 
});
JS

4. 其他 API

4.1. identify( 'anonymousID', [boolean]);

  • 说明:用来修改当前小程序访问用户的匿名 ID;
  • 参数:
    • anonymousID: String ,要使用的匿名 ID;
    • boolean: Boolean, 设置为 true, 表示将该匿名 ID 保存到微信 storage 中;不填或者设置为 false,表示该匿名 ID 只在小游戏本次生命周期中有效,下次冷启动后使用的仍然时修改之前的匿名 ID;

4.2. getPresetProperties();

  • 说明:用来获取部分预置属性;

4.3. clearAllRegister();

  • 说明:用来清除存储在 storage 中的公共属性;

4.4. logout( [boolean])

  • 说明:用来将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID;
  • 参数:
    • boolean: Boolean, 不填, 表示将当前的 Distinct ID 切换回调用 login() 接口之前的匿名 ID;设置为 true,表示将当前的 Distinct ID 切换为一个重新生成的 UUID;