用户登录态设置

比如业务有账号体系，并希望SDK同步用户状态。就可以考虑在用户登录后立即对SDK设置user_unique_id，在用户登出后立即对SDK清除user_unique_id。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
});
$$sdk.send();

// 用户登录后立即设置user_unique_id
$$sdk.config({
    user_unique_id: '{{uuid}}', // 值可以考虑为能关联到用户的一些属性
});

// 用户登出后立即清除user_unique_id
$$sdk.config({
    user_unique_id: '',
});

另外SDK的2.6.0+版本提供setUserUniqueID方法来设置user_unique_id。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
});
$$sdk.send();

// 用户登录后立即设置user_unique_id
$$sdk.setUserUniqueID('{{uuid}}'); // 值可以考虑为能关联到用户的一些属性

// 用户登出后立即清除user_unique_id
$$sdk.setUserUniqueID('');

使用openid/unionid设置为登录用户

此场景下，您需要先获取openid/unionid（通常这些id需为业务的服务端携带code向小程序开放平台接口，比如code2Session，发起请求，换取openid、unionid、session_key等信息），然后使用config或setUserUniqueID方法设置给SDK。
下面以微信小程序平台举例：

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
});
$$sdk.send();

App({
    //...
    onLaunch() {
        // ...        
        wx.login({
            success(res) {
                if (res.code) {
                    wx.request({
                        url: 'https://xxxxxx.com/', // 业务自身的服务端接口，去请求小程序开放平台接口换取openid/unionid的
                        data: {
                            code: res.code,
                        },
                        success(res) {
                            // 希望使用openid设置user_unique_id
                            if(res.openid) {
                                $$sdk.config({
                                    user_unique_id: res.openid,
                                });
                            }
                            
                            // 或者希望使用unionid设置user_unique_id
                            if(res.unionid) {
                                $$sdk.config({
                                    user_unique_id: res.unionid,
                                });
                            }
                        }
                    });
                }
            }
        });
    }
});

用户口径相关处理

如果要设置用户口径，需要在设置user_unique_id的同时设置user_unique_id_type。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
});
$$sdk.send();

$$sdk.config({
    user_unique_id: 'tangseng',
    user_unique_id_type: 'huoshan', // user_unique_id_type的值是预制好的
});

多用户口径类型处理

如果要进行多口径绑定，在设置user_unique_id的同时设置user_unique_id_type后，还需要调用bind方法处理。注意：SDK版本要求2.11.0+，并且仅在SAAS云原生、私有化支持。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
});
$$sdk.send();

// 示例中phone和email只是举例，具体传什么口径由业务决定
$$sdk.bind({
    phone: '130xxxxxxxx',
    email: 'xxx@yyy.com'
}).then((status) => {
    // status的值是true或者false, true表示成功、false表示失败
    // 业务根据status进行后续处理，可选处理
});

获取SDK默认生成的web_id、ssid

SDK会为您自动生成web_id、ssid，如果您希望获取SDK默认生成的这些id，可参考以下方式。
获取web_id

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
});
$$sdk.send();

$$sdk.on($$sdk.types.Ready, () => {
    const webid = $$sdk.getConfig('web_id');
    console.log('web_id', webid);
});

获取ssid

注意：获取ssid时，实际需要调用getToken获取到ssid，该方法会发起请求去DataFinder的数据流服务中获取ssid，ssid不在SDK侧进行管理。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
});
$$sdk.send();

$$sdk.getToken().then((ids) => {
    const ssid = ids.ssid;
    console.log('ssid', ssid);
});

自定义web_id

通常情况下您可以直接使用SDK自动生成的Web_id，部分特殊场景下，如果您希望使用自定义的web_id来覆盖SDK自动生成的web_id时，可参考以下方法。

如需希望覆盖SDK默认生成的web_id，首先需要在初始化时开启enable_custom_webid: true，然后再设置web_id。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
    enable_custom_webid: true,
});
$$sdk.send();

开启后，需要业务主动config设置web_id。

web_id的值要求纯数字或全是数字的字符串类型，并且数值最大不能超过2的64次方。不同用户的web_id不应该相同。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
    enable_custom_webid: true,
});
$$sdk.send();

// 在适当时机主动设置web_id
$$sdk.config({
    web_id: '12345678910',
});

另外也可以使用SDK提供的setWebIDviaUnionID和setWebIDviaOpenID两个方法来设置web_id。

• setWebIDviaUnionID：满足业务使用获取到用户的unionid来设置web_id。

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
      enable_custom_webid: true,
  });
  $$sdk.send();
  
  // 在获取到用户的unionid后设置web_id
  $$sdk.setWebIDviaUnionID('{{用户的unionid}}');
  

• setWebIDviaOpenID：满足业务使用获取到用户的openid来设置web_id。

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
      enable_custom_webid: true,
  });
  $$sdk.send();
  
  // 在获取到用户的openid后设置web_id
  $$sdk.setWebIDviaOpenID('{{用户的openid}}');
  

与H5页面关联web_id

小程序自身在与其内部H5页面之间有诸多限制，小程序平台本身提供的能力也有限。目前SDK这边只提供将web_id传递给H5页面。

SDK提供了createWebViewUrl和createWebViewUrlAsync两个方法可以把web_id传递给H5页面。

• createWebViewUrl：在小程序内的webview组件的url上添加web_id传递给h5页面，需要注意的是该方法只能在SDK初始化完成后使用才可能保证有web_id。

  <!-- webview.wxml -->
  <web-view src="{{ webUrl }}"></web-view>
  

  // webview.js
  Page({
     data: {
        webUrl: ''
     },
     onLoad(options) {
        let url = 'https://example/demo.html';
        this.setData({
           webUrl: $$sdk.createWebViewUrl(url),
        });
     }
  });
  

• createWebViewUrlAsync：这个是createWebViewUrl的异步版本，返回promise，不受SDK初始化情况的影响，一定会获取到web_id。

  <!-- webview.wxml -->
  <web-view src="{{ webUrl }}"></web-view>
  

  // webview.js
  Page({
     data: {
        webUrl: ''
     },
     onLoad(options) {
        let url = 'https://example/demo.html';
        $$sdk.createWebViewUrlAsync(url).then((webviewUrl) => {
           this.setData({
              webUrl: webviewUrl,
           });
        });
     }
  });
  

开启预置事件上报

开启预置事件自动上报，需要在初始化时配置auto_report参数为true。

boolean
    appLaunch?: boolean;
    appTerminate?: boolean;
    appError?: boolean;
    pageShow?: boolean;
    pageHide?: boolean;
    pageShare?: boolean;
    pageFavorite?: boolean;
    click?: boolean;
}

示例：

• 不上报点击事件，但上报其他预置事件，设置为true或者空对象{}就可以

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
    auto_report: true,
});
$$sdk.send();

• 上报所有预置事件，包括点击事件，需要将click设为true

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
    auto_report: {
        click: true,
    },
});
$$sdk.send();

• 上报大部分预置事件，但不上报error事件，将appError设为false，其他事件也类似设置

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
    auto_report: {
        click: true,
        appError: false,
    },
});
$$sdk.send();

采集点击事件

当click设为true时，SDK将在那些绑定了一些事件函数的组件被点击时上报bav2b_click事件（目前只支持bindtap类型），该事件会采集组件上的dataset数据集中的内容作为参数上报。 假设如下组件，设置了id="diandian"以及data-hi="hello"

<view id="diandian" data-hi="hello" bindtap="tapMethod">点我</view>

当该组件被点击时，上报bav2b_click事件以及采集的属性大概如下

{
    event: 'bav2b_click',
    params: {
        path: 'pages/index/index',
        query_id: 'diandian',
        query_hi: 'hello'
    }
}

SDK版本2.12.0+开始支持属性过滤能力：初始化参数增加clickIgnoreProperty，类型数组，在click设置为true的情况下有效，作用是过滤被点击元素的dataset值中相应的属性，比如设置了['abc', 'xxx']，那么所有被点击元素的属性上有abc或xxx的都会被过滤掉，不会采集。
全局设置方式，示例：

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
    auto_report: {
        click: true,
        clickIgnoreProperty: ['imgSrc', '...'],
    },
});
$$sdk.send();

单个元素设置方式，示例

<view bindtap="ontest" data-xxx="xxx-value" data-yyy="yyy-value" data-zzz="zzz-value" data-click-ignore-property="xxx,yyy"></view>

给预置事件增加自定义属性

• 针对app_launch、app_terminate事件：在SDK初始化后就可以进行监听“ExtendAppLaunch”、“ExtendAppTerminate”消息。

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  
  // 扩展app_launch事件参数
  $$sdk.on($$sdk.SdkHook.ExtendAppLaunch, (params) => {
      params['xxx'] = '我是额外的xxx参数';
      // 可以扩展多个
  });
  
  // 扩展app_terminate事件参数
  $$sdk.on($$sdk.SdkHook.ExtendAppTerminate, (params) => {
      params['zzz'] = '我是额外的zzz参数';
      // 可以扩展多个
  });
  
  $$sdk.send();
  

• 针对predefine_pageview、predefine_pageview_hide事件：在每个页面（Page）的onLoad方法中监听“ExtendPageShow”、“ExtendPageHide”消息，为了避免页面的onLoad多次执行导致的多次监听，最好在onUnload中移除相应监听（off）。

  // 某个页面
  Page({
      // 其他代码...
      pageShowHook(params) {
          // 首先判断是不是当前页面，假设当前页面为pages/index
          if (params.path.indexOf('pages/index') !== -1) {
              params['abc'] = '我是额外的abc参数';
              // 可以扩展多个
          }
      },
      pageHideHook(params) => {
          // 首先判断是不是当前页面，假设当前页面为pages/index
          if (params.path.indexOf('pages/index') !== -1) {
              params['def'] = '我是额外的def参数';
              // 可以扩展多个
          }
      },
      onLoad() {
          // 其他代码...
          
          // 扩展predefine_pageview事件参数
          $$sdk.on($$sdk.SdkHook.ExtendPageShow, this.pageShowHook);
          
          // 扩展predefine_pageview_hide事件参数
          $$sdk.on($$sdk.SdkHook.ExtendPageHide, this.pageHideHook);
      },
      onUnload() {
          // 其他代码...
          
          // 移除针对predefine_pageview事件的监听
          $$sdk.off($$sdk.SdkHook.ExtendPageShow, this.pageShowHook);
          
          // 移除针对predefine_pageview_hide事件的监听
          $$sdk.off($$sdk.SdkHook.ExtendPageHide, this.pageHideHook);
      },
      
      // 其他代码...
  });
  

设置事件公共属性

使用config方法可以设置公共属性，这些公共属性会在后续所有事件上报都携带上。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
});
$$sdk.send();

// 设置事件公共属性，这些公共属性会在后续所有事件上报时都携带上
$$sdk.config({
    city: '南京',
    nick_name: 'vikings',
});

另外SDK的2.6.0+版本提供setHeaderInfo和removeHeaderInfo两个方法来处理事件公共属性。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
});
$$sdk.send();

// 设置公共属性city，值为南京
$$sdk.setHeaderInfo('city', '南京');

// 移除公共属性city
$$sdk.removeHeaderInfo('city');

SDK内部预设了一些公共属性字段，这些字段预定义好了字段名，如下表所列，其中部分字段，SDK在初始化完成后会自动尝试获取，而其他字段需要业务方设置，比如nick_name、gender、avatar_url这些SDK无法自动获取到的，就需要您主动进行设置。

在小程序分包中使用

使用默认实例时是包含预置事件插件的，在存在该插件时，SDK监听了小程序的App/Page的相关生命周期钩子，SDK也会等待相关生命周期钩子触发，比如App的onLaunch。
而在分包中，等SDK初始化时，App的onLaunch已经触发结束，因此需要“告诉”SDK“跳过”等待触发，在初始化配置时开启enable_skip_launch: true。

// 在分包中初始化SDK
import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
    enable_skip_launch: true,
});
$$sdk.send();

使用多实例

使用多实例，需要导入SDK类，即SDK构造器，位于SDK包中的esm目录下的sdk文件。

import SDK from '@datarangers/sdk-mp/esm/sdk';

提示，如下方式导入的是SDK的默认实例，非SDK构造器。注意观察导入的文件是不一样的。

import $$sdk from '@datarangers/sdk-mp';

示例：

import SDK from '@datarangers/sdk-mp/esm/sdk';

// 对构造器使用new操作产生实例1
$$sdk1 = new SDK();
$$sdk1.init({
    app_id: 1,
    // ...
});
$$sdk1.send();


// 对构造器使用new操作产生实例2
$$sdk2 = new SDK();
$$sdk2.init({
    app_id: 2, // app_id不能与其他实例相同
    // ...
});
$$sdk2.send();

自定义选择内部插件

SDK默认导出的实例包含了尽可能多的插件功能。使用自定义选择插件后，比起默认导出的实例在构建后的体积上会少一些。如果业务希望自定义选择使用哪些插件，可以考虑如下使用方式。

1. 首先导入SDK基础类文件：esm/base.js
2. 再根据需要导入相应的插件文件：esm/plugin/xxx.js
3. 将插件注册到SDK基础类：使用SDK类的usePlugin静态方法
4. 然后实例化SDK，接着再进行初始化设置

// 导入基础类
import BaseSDK from '@datarangers/sdk-mp/esm/base';

// 导入所需插件，比如AB实验插件
import Ab from '@datarangers/sdk-mp/esm/plugin/ab';
BaseSDK.usePlugin(Ab);

// 实例化SDK
const $$sdk = new BaseSDK();
$$sdk.init({
    app_id: 1338, // 替换成申请的app_id
    enable_ab_test: true，//开启ab实验
});
$$sdk.send();

小程序单一平台使用方式

SDK默认导出的实例尽可能的兼容目前主流的小程序平台，比如微信、支付宝、抖音、百度、小红书、QQ、钉钉等。如果业务明确自己的小程序应用只会发布到某一平台，比如微信，可以考虑使用如下方式，明确选择哪个平台的入口文件。需要注意的是，单一的平台入口文件只包含基础的功能，使用更多能力需要主动导入相应插件并注册。

// 导入明确的某个小程序平台入口文件
import WXSDK from '@datarangers/sdk-mp/esm/wx';

// 导入所需插件，比如AB实验插件
import Ab from '@datarangers/sdk-mp/esm/plugin/ab';
WXSDK.usePlugin(Ab);

// 实例化SDK
const $$sdk = new WXSDK();
$$sdk.init({
    app_id: 1338, // 替换成申请的app_id
    enable_ab_test: true，//开启ab实验
});
$$sdk.send();

请求进行加密

目前仅支持国密加密方式。相关参数如下：

示例：

import SDK from '@datarangers/sdk-mp/esm/sdk';

// 使用加密插件
import EncryptPlugin from '@datarangers/sdk-mp/esm/plugin/encrypt';
SDK.usePlugin(Ab);

// 实例化SDK
const $$sdk = new SDK();
$$sdk.init({
    // ...
    
    //这些是国密加密参数
    enable_encrypt: true,
    encrypt_type: 'sm',
    encrypt_public_key: '设置公钥',
    encrypt_header: '', // 国密目前默认为gm_sm2
});
$$sdk.send();

UTM追踪

SDK默认会尝试从小程序启动参数上获取utm相关参数：utm_source、utm_medium、utm_campaign、utm_term、utm_content。如果获取到了，就将这些参数放入事件公共属性中，后续所有事件上报时都会携带上。该能力自动开启，业务不需要做任何处理。

飞书小组件应用实践

注意在飞书小组件场景下，不支持预置事件上报（即auto_report参数设置无效）。SDK版本要求：2.9.0+

// 导入飞书小组件的单独入口类
import BlockSDK from '@datarangers/sdk-mp/esm/block';

// 导入所需插件，比如AB实验插件
import Ab from '@datarangers/sdk-mp/esm/plugin/ab';
BlockSDK.usePlugin(Ab);

// 实例化SDK
const $$sdk = new BlockSDK();
$$sdk.init({
    app_id: 1338, // 替换成申请的app_id
    enable_ab_test: true，//开启ab实验
});
$$sdk.send();

在特殊环境下使用方式

如果业务项目由于一些原因不支持使用npm包、或第三方依赖、甚至没有构建打包处理过程，可以考虑使用SDK提供的umd模块文件。

• 复制SDK包内的index.umd.js文件到项目下

const $$sdk = require('{{相对路径}}/index.umd.js');
$$sdk.init({
    app_id: 1338, // 替换成申请的app_id
    enable_ab_test: true，//开启ab实验
});
$$sdk.send();