钉钉小程序 SDK 使用说明

最后更新于：2019-09-23 11:18:53

在使用前，请先阅读数据模型的介绍。

更新日志

1. 获取和引入神策分析 SDK

1.1. 安装方法

1.1.1. 下载 SDK

从 github 上下载钉钉小程序 sdk，sensorsdata.min.js 和 sensorsdata_conf.js;

1.1.2. 配置参数

配置 sensorsdata.conf.js 文件中的数据接收地址 server_url 参数; 注意: 请在“设置／开发设置 / 服务器域名”中添加 httpRequest 接口请求域名白名单，把这个地址加上。

1.1.3. 引入 SDK

把这两个文件放在小程序项目中，然后在 app.js 中通过 require 引入; 

------app.js
    var sensors = require('./sdk/sensorsdata.min.js')

在 App 函数中设置一个值为 sensors 的全局变量; 

------app.js
    var sensors = require('./sdk/sensorsdata.min.js')
    App({ 
        onLaunch : function(){ 
            this.sensors = sensors 
        }
    })

其他 Page 中通过 getApp 来使用神策追踪;

------index.js
    var app = getApp();
    Page({
        onShow: function(){
            app.sensors.track('pageView',{
                 pagename: 'index'
            })
        }
    });

2. 事件采集

2.1. 预置事件采集

小程序支持采集 $MPLaunch、$MPShow、$MPHide 这三个预置事件。需要在小程序的 onLaunch、 onShow、 onHide 生命周期函数中分别调用 sensors.quick('appLaunch', options，[properties])、sensors.quick('appShow', options，[properties])、sensors.quick('appHide'，[properties])

  • options：必填，onLaunch、onShow 生命周期回调函数使用的参数；

  • properties：object，选填,为预置事件增加的自定义属性

------app.js
    var sensors = require('./sdk/sensorsdata.min.js')
    App({
        onLaunch : function( options ){
            this.sensors = sensors;
            sensors.quick('appLaunch', options,{
                ProductId: '123456'
            });
        },
        onShow : function( options ){
            sensors.quick('appShow', options,{
                ProductCatalog: "Laptop Computer"
            });
        },
        onHide : function(){
            sensors.quick('appHide',{
                ProductName: "MacBook Pro"
            });
        }
    });

2.2. 自定义事件采集

sdk 提供了 track(eventName,[properties]) 方法来采集自定义事件。

  • eventName：string，必填，事件名称；

  • properties：object，选填,为该事件设置的事件属性；

第一次接入神策分析时，建议先追踪 3~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：

电商产品，可以追踪用户注册、浏览商品和下订单等事件。

------index.js
    // 追踪浏览商品事件。  
    var app = getApp();
    app.sensors.track('ViewProduct', {
        ProductId: '123456',
        ProductCatalog: "Laptop Computer",
        ProductName: "MacBook Pro",
        ProductPrice: 12345
    });

3. 标识用户

在进行任何埋点之前，都应当先确定如何标识用户。distinct_id 是神策用来标识用户的一段唯一的字符串。

在小程序中，会有下面 2 种 id

  1. 默认情况下，我们会生成一个随机数 uuid ，保存在本地缓存中，我们暂时称这个为 uuid
  2. 数据库中保存的，用户真实 id 。我们暂时称为 "你们服务端分配给用户具体的登录 ID"

如果不做任何操作，小程序会使用 uuid 作为 distinct_id ，注意： uuid 在换了设备，或者删除小程序后，会重新生成。

3.1. 修改匿名 ID

默认情况下，是把 uuid 作为 distinct_id 的。如果想使用其他匿名 id（比如你们自己生成的 uuid），可以用 identify(id,true) 方法来改变当前的distinct_id。 

------app.js
    var sensors = require('./sdk/sensorsdata.min.js')
    sensors.identify('匿名ID', true);
    App({
       onLaunch: function( options ){
           this.sensors = sensors;
           sensors.quick('appLaunch', options)
       }
    });

3.2. 用户关联

可以通过调用 login("userID") 方法来标识真实用户；会把 SDK 自动生成的 uuid 与现在传入的 userID关联。且以后会一直使用这个 userID。

------app.js
    var sensors = require('./sdk/sensorsdata.min.js')
    sensors.login("userID");
    App({
       onLaunch: function( options ){
           this.sensors = sensors;
           sensors.quick('appLaunch', options)
       }
    });

4. 属性设置

4.1. 设置公共属性

4.1.1. registerApp(properties)

事件公共属性：可以在 app.js 文件引入 sensorsdata.min.js 文件之后， 使用 registerApp() 方法设置公共属性。

  • properties：object，必填，调用该方法之后的所有事件将具有的公共属性 
------app.js
    // 注册事件公共属性。  
    var sensors = require('./sdk/sensorsdata.min.js')
    sensors.registerApp({
        userLever: 'VIP3',
        userSex: '男'
    });

4.2. 设置用户属性

4.2.1. setProfile(properties)

直接设置用户的属性，如果存在则覆盖。

  • properties：object，必选。
    sensors.setProfile({
        email:'xxx@xx',
        favoriteFruits: ['苹果', '油桃'],
        subscribers： 7277
    });

4.2.2. setOnceProfile(properties)

如果不存在则设置，存在就不设置。

  • properties：object，必选。
    sensors.setOnceProfile({
        email:'xxx@xx',
        favoriteFruits: ['苹果', '油桃'],
        subscribers： 7277
    });