本文为您介绍小程序端为您提供的主要API，您可以结合埋点规划调用对应API进行埋点。

• 作用：是对SDK实例进行初始化配置。

• 定义：init(options: InitParams): void

• 参数：

  参数名	类型	必填	说明
  options	options可设置init的多个参数。 interface InitParams { app_id: number; log?: boolean; channel?: 'cn'; //'cn' 或者 'sg' channel_domain?: string; auto_report?: boolean; // boolean 或者 Object enable_ab_test?: boolean; // ... }	是	SDK需要明确知道上报到哪个应用，上报到哪个DataFinder服务地址，开启哪些功能模块，这些就需要在SDK进行初始化时在init接口中进行配置，init涉及的参数及配置说明见下表。

  参数分类	字段	字段值类型	必填	字段说明
  基础参数	app_id	number	是	应用ID，用于标识业务产品，即表明埋点采集的是哪个应用的数据。在DataFinder的控制台创建应用后会自动为您生成对应应用的应用ID，获取应用ID的操作请参见步骤2：获取APPID。
  	log	boolean	否	用于设置是否需要打开日志，设置为true后，控制台会打印调试信息，便于您在集成SDK时通过控制台的日志信息验证SDK集成是否成功。
  	channel	string	否	用于设置采集数据的上报通道，每个应用只能设置唯一一个channel，请根据您当前使用的DataFinder服务的环境类型和所在地域情况，设置合适的channel： cn（默认值）：如果您当前的环境为SaaS-云原生、SaaS-非云原生、私有化环境，可保持默认值，无需修改（即在集成SDK时，init接口中无需配置channel字段）。 sg：如果您当前的环境是SaaS-非云原生 海外BytePlus环境，您需要修改channel取值为sg。 说明 如果您不确定您当前使用的环境是哪种类型，可参考SaaS云原生/非云原生&私有化环境文档进行查看确认。
  	channel_domain	string	否	用于设置数据上报到DataFinder的哪个服务地址： SaaS-云原生（国内：华北2-北京）：https://gator.volces.com SaaS-云原生（国内：华南1-广州）：https://gator.uba.cn-guangzhou.volces.com SaaS-云原生（海外：柔佛）：https://gator.uba.ap-southeast-1.volces.com SaaS-非云原生（国内）：您无需修改，保持默认值（https://mcs.volceapplog.com）即可。 SaaS-非云原生：（海外 BytePlus环境）：https://mcs.tobsnssdk.com 私有化： 私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址，将私有化部署的数据上报域名添加到小程序后台的“request合法域名”中。如您不清楚此地址，请联系您的项目经理或客户成功经理。 说明 配置完成channel_domain后，您还需在小程序中将上述地址配置到小程序的白名单中。 如果您不确定您当前使用的环境是哪种类型，可参考SaaS云原生/非云原生&私有化环境文档进行查看确认。
  自动上报	auto_report	boolean/Object	否	设置是否需要自动采集为您提供的预置事件和预置属性数据（默认为false，不采集）。当前支持设置auto_report的取值结果为true/false或具体的对象取值（二选一）： true/false：设置为true时，等于设置为空对象，会自动采集上报部分预置事件和属性，效果等同于： { appLaunch: true, // 上报app_launch事件，false时不上报 appTerminate: true, // 上报app_terminate事件，false时不上报，或者appLaunch为false时该事件也不会上报 appError: true, // 上报on_error事件，false时不上报 pageShow: true, // 上报predefine_pageview事件，false时不上报 pageHide: true, // 上报predefine_pageview_hide事件，false时不上报，或者pageShow为false时该事件也不会上报 pageShare: true, // 上报on_share事件，false时不上报 pageFavorite: true, // 上报on_addtofavorites事件，false时不上报 pageTabItemTap: true, // 上报on_tabbartap事件，false时不上报 click: false, // 不上报bav2b_click事件，true时才上报 } 设置为对象取值时：您可以在auto_report中对指定预置事件是否采集进行修改配置。 配置空对象时：默认点击事件不采集，app_launch、app_terminate等事件采集； 如果您希望修改配置，仅需在对象取值中配置对应字段的采集开关，其他未配置的字段则保持默认状态。 例如，您希望关闭appError和pageShare，其他事件的采集状态保持默认（采集），则配置示例如下： auto_report: { appError: false, pageFavorite: false, // 其他事件无需修改则无需配置 } 例如，您希望采集点击事件，其他事件的采集状态保持默认（采集），则配置示例如下： auto_report: { click: true, // 其他事件无需修改则无需配置 } 说明 如果您希望采集点击事件，在auto_report中打开click字段开关后，还需在后续集成代码中配置需采集的属性，详情请参见采集点击事件。 小程序端支持的预置事件和属性详情请参见小程序预置事件及属性。
  ab实验	enable_ab_test	boolean	否	设置是否需要开启A/B实验功能。设置为true后，会开启ab实验功能，后续您需要： 在集成SDK初始化时同时配置A/B实验的分流地址（ab_channel_domain）。 使用包括getVar、getAllVars等API来获取实验参数等。A/B实验相关API详情请参见AB实验模块及API。
  	ab_channel_domain	string	否	如果开启了A/B实验，您需要设置A/B实验的分流地址。 SaaS-云原生（国内：华北2-北京）：https://tab.volces.com SaaS-云原生（国内：华南1-广州）：暂不支持 SaaS-云原生（海外：柔佛）：https://tab.ab.ap-southeast-1.volces.com SaaS-非云原生：（国内）：您无需修改，保持默认值即可。 SaaS-非云原生：（海外 BytePlus环境）：您无需修改，保持默认值即可。 私有化： 私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址，将私有化部署的数据上报域名添加到小程序后台的“request合法域名”中。如您不清楚此地址，请联系您的项目经理或客户成功经理。 说明 配置完成ab_channel_domain后，您还需在小程序中将上述地址配置到小程序的白名单中。 如果您不确定您当前使用的环境是哪种类型，可参考SaaS云原生/非云原生&私有化环境文档进行查看确认。
  	clear_ab_cache_on_user_change	boolean	否	如果开启了A/B实验，您可以设置切换用户时是否需要重新获取A/B实验的配置信息，如果要关闭则把clear_ab_cache_on_user_change配置项置为false，默认是true。
  缓冲 （仅2.5.0及以上版本支持）	enable_buffer	boolean	否	设置true后，将开启缓冲。 小程序端的数据采集上报流程请参见参考：SDK核心运行流程。
  	buffer_interval	number	否	缓冲的间隔时间，单位是毫秒，默认值 5000，含义是到达间隔时间后会上报缓冲区的所有事件。
  	buffer_number	number	否	缓冲的最大数量，默认值 5，含义是缓冲数量达到该值后会立即上报缓冲区的所有事件。
  缓存 （仅2.5.0及以上版本支持）	enable_cache	boolean	否	开启后，请求失败的事件会存到storage中，并在用户下一次再进小程序时补充上报。 版本2.5.0~2.1.4.2，该参数默认值为false，使用该功能需要明确设置参数值为true 版本2.14.3开始，该参数默认值为true，无需设置就可以自动使用该功能
  其他	enable_profile	boolean	否	设置true后，可以使用profile相关API，主要用于设置用户属性相关数据采集，详情请参见用户属性模块及API。
  	enable_filter_crawler	boolean	否	设置爬虫场景下是否采集数据： 设置为true：根据小程序平台对事件触发场景的判断结果，如果是爬虫场景下(例如，微信小程序返回的场景值scene: 1129)，则不再采集上报事件；如果不是爬虫场景，则正常采集数据。 设置为false：无论是否是爬虫场景，正常采集数据。
  	enable_custom_webid	boolean	否	是否设置自定义web_id。如果您不希望使用SDK自动生成的web_id，希望上报自定义web_id，您需要在初始化时开启enable_custom_webid，然后再通过config接口设置web_id，只有设置web_id后才会初始化完成，web_id的值要求必须是数字或者全是数字的字符串类型。详情请参见自定义web_id。
  	元素曝光	小程序SDK支持采集元素曝光事件的数据，您可以在初始化时打开元素曝光开关并配置元素曝光的采集数据详情，详情请参见元素曝光模块及API。
  	安全合规	小程序SDK支持使用国密加密方式对请求进行加密，在初始化中通过设置加密相关字段实现加密（enable_encrypt、encrypt_type等），详情请参见请求进行加密。

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  
  $$sdk.init({
      app_id: 1,
      channel: 'cn',
      log: true,
      auto_report: true,
      
      // ...更多配置参数
  });
  

• 作用：当init初始化调用之后，需要调用send方法，SDK才开始上报事件。在调用send方法之前，不会有事件上报。
• 定义：send(): void
• 示例：

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

• 作用：调用config对事件进行一些设置，比如设置公共属性、设置user_unique_id等。可以调用多次，后面设置会覆盖之前相同设置项。

• 定义：config(configs?: ConfigParams): void

• 参数：

  参数名	类型	必填	说明
  configs	interface ConfigParams { user_unique_id?: string 或者 null; user_unique_id_type?: string; [key: string]: any; }	否	您可以在config接口中设置事件公共属性或用户相关。 设置事件公共属性：事件公共属性会在header中作为所有事件的共有属性，更多设置详情请参见设置事件公共属性。 设置user_unique_id：详情请参考user_unique_id相关。

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  // 设置事件公共属性，这些公共属性会在后续所有事件上报时都携带上
  $$sdk.config({
      city: '南京',
      nick_name: 'vikings',
  });
  
  // 设置user_unique_id
  $$sdk.config({
      user_unique_id: 'zhangsan', // 此时user_unique_id为zhangsan
  });
  
  // 再次设置user_unique_id，会覆盖
  $$sdk.config({
      user_unique_id: 'lisi', // 此时user_unique_id为lisi
  });
  

• 作用：使用event方法可以上报自定义事件。该方法支持单个事件方式和批量事件方式上报。

单个事件

• 定义：event(name: string, params: Record<string, string 或 number 或 boolean 或 object 或 Array>): void

• 参数：

  参数名	类型	必填	说明
  name	string	是	事件命名仅支持字母、数字和下划线，不要使用app_launch、app_terminate等SDK内部自动上报事件名。 建议事件名性统一使用小写。
  params	Record<string, string 或 number 或 boolean 或 object 或 Array>	是	建议属性统一使用小写。 事件属性值支持number、string、array、object、boolean类型，数据采集后落库至DataFinder时，数据格式会做一些转化，更多说明请参见支持的数据格式与事件/属性分类。 不要在事件属性中再嵌套object，即属性值不接受object类型，如果业务数据为嵌套object类型，可通过转义的方式转成String后再上报。请参见示例1：嵌套JSON类型属性如何上报并用于过滤、分组。 如果没有属性，可以不传params参数。

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  // 在业务需要的地方进行调用event方法上报自定义事件
  $$sdk.event('some_event', {
      val: '...',
      path: '...',
  });
  

批量事件

• 逻辑说明：接受数组来上报批量事件，数组项数量大于30时，SDK会自动分多次进行上报，即单次批量最多上报30个事件。

• 定义：event(events: Array<{event: string; params: Record<string, string 或 number 或 boolean 或 object 或 Array>; local_time_ms?: number;}>): void

• 参数：

  参数名	类型	必填	说明
  events	Array<{ event: string; params: Record<string, string 或者 number 或者 boolean 或者 object 或者 Array>; local_time_ms?: number; }>	是	event、params的要求与上报单个事件时的要求一致； local_time_ms的值是时间戳，默认SDK会为每个事件补充该字段，如果您主动设置该字段，会以您设置的取值为准。

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      app_id: 1338,
      channel: 'cn',
      log: true,
      auto_report: true,
      
      // ...更多配置参数
  });
  $$sdk.send();
  
  // 在业务需要的地方进行调用event方法上报自定义事件
  $$sdk.event([
      {
          event: 'event1', 
          params: {param: '1'},
      },
      {
          event: 'event2', 
          params: {param2: '2', param2Other: '2-other'},
          local_time_ms: 1580892161098,
      },
      // ... 
      {
          event: 'event30', 
          params: {param30: '30', param30Other: '30-other'},
          local_time_ms: 1580892214276,
      },
  ]);
  

• 作用：设置user_unique_id，可以调用多次，后面设置会覆盖之前相同设置项。版本要求2.6.0+。

  说明

  使用setUserUniqueID接口设置user_unique_id与使用config接口设置user_unique_id效果一样，本质上setUserUniqueID接口内部也是调用的config方法。

• 定义：setUserUniqueID(uuid: string 或 null): void

• 参数：

  参数名	类型	必填	说明
  uuid	string 或 null	是	更多user_unique_id的场景实践请参见user_unique_id相关。

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  // 用户登录后立即设置user_unique_id
  $$sdk.setUserUniqueID('{{uuid}}'); // 值可以考虑为能关联到用户的一些属性
  
  // 用户登出后立即清除user_unique_id
  $$sdk.setUserUniqueID('');
  

• 作用：设置事件公共属性，可以调用多次，后面设置会覆盖之前相同设置项。版本要求2.6.0+。

  说明

  使用setHeaderInfo接口设置公共属性与使用config接口设置公共属性效果一样，本质上setHeaderInfo接口内部也是调用的config方法。

• 定义：setHeaderInfo(key: string, value: any): void

• 参数：

  参数名	类型	必填	说明
  key	string	是	公共属性名。更多事件公共属性的配置实践请参见设置事件公共属性。
  value	any	是	公共属性值。

• 示例：

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

• 作用：移除事件公共属性。版本要求2.6.0+。

• 定义：removeHeaderInfo(key: string): void

• 参数：

  参数名	类型	必填	说明
  key	string	是	公共属性名。

• 示例：

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

• 作用：暂停SDK上报事件。调用该方法后，SDK会处于暂停状态，后续不再会上报事件。版本要求2.11.0+。
• 定义：disableSDK(): void
• 示例：

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

• 作用：取消暂停SDK上报，一般是在调用disableSDK后又打算取消暂停，即重新启动SDK上报，后续会恢复上报事件。版本要求2.11.0+。
• 定义：enableSDK(): void
• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  // 前面有调用过$$sdk.disableSDK();
  $$sdk.enableSDK();
  

此模块提供AB实验能力，并提供了一系列的方法：getVar、getAllVars、getAbSdkVersion、setExternalAbVersion。

开启模块

使用此模块，在SDK初始化时，在init接口中除了通用参数需要配置外，还需打开A/B实验的模块开关：enable_ab_test: true，同时配置A/B实验的分流地址（ab_channel_domain字段）。

import $$sdk from '@datarangers/sdk-mp';
$$sdk.init({
    // ...
    enable_ab_test: true,
    ab_channel_domain: "https://tab.volces.com", 
});
$$sdk.send();

此外还支持设置切换用户时是否需要重新获取A/B实验的配置信息（clear_ab_cache_on_user_change字段），详情请参见init接口中A/B实验部分。

模块方法

getVar

• 作用：获取AB实验配置中的实验对应的配置项值，同时SDK会收集对应的vid（业务一般不用直接关心该vid）。

• 定义：
  getVar(name: string, defaultValue: any, callback: (value: any) => void): void
  getVar(name: string, defaultValue: any): Promise

• 参数：

  参数名	类型	必填	说明
  name	string	是	实验配置中的key。 说明 提示：业务调用getVar方法，SDK发现实验配置中有对应的key时，会上报一个预置事件abtest_exposure。
  defaultValue	any	是	兜底值，当实验配置中没有相应的key的配置项，该方法会返回这个兜底值。
  callback	(value: any) => void	否	当获取到实验配置项值时，如果有设置callback就会执行该callback，并把实验配置项值作为callback的参数。

• 返回值：

  类型	说明
  Promise	当没有设置callback参数时，该方法会返回Promise。

• 示例：

  • 使用回调函数方式。

    import $$sdk from '@datarangers/sdk-mp';
    $$sdk.init({
        // ...
    });
    $$sdk.send();
    
    $$sdk.getVar('color', 'red', (value) => {
        // 当配置中存在color实验，value值为配置中的color对应的值，否则值为red
    });
    

  • 返回Promise方式

    import $$sdk from '@datarangers/sdk-mp';
    $$sdk.init({
        // ...
    });
    $$sdk.send();
    
    $$sdk.getVar('color', 'red').then((value) => { 
        // 当配置中存在color实验，value值为配置中的color对应的值，否则值为red
    });
    

getAllVars

• 作用：获取ab实验所有配置信息。

• 定义：
  getAllVars(callback: (data: any) => void): void
  getAllVars(): Promise

• 参数：

  参数名	类型	必填	说明
  callback	(data: any) => void	否	如果有设置callback就会执行该callback，并把实验配置全部数据作为callback的参数。 实验配置全部数据结构大概如下： { aa: { val: 'aa-value', vid: '11' }, test_before_6d: { val: 'test_before_6d-value', vid: '22' }, bb: { val: 'bb-value', vid: '33' } }

• 返回值：

  类型	说明
  Promise	当没有设置callback参数时，该方法会返回Promise

• 示例：

  • 使用回调函数方式

    import $$sdk from '@datarangers/sdk-mp';
    $$sdk.init({
        // ...
    });
    $$sdk.send();
    
    $$sdk.getAllVars((data) => {
        // data值大概如下：
        /* 
        {
          aa: { val: 'aa-value', vid: '11' },
          test_before_6d: { val: 'test_before_6d-value', vid: '22' },
          bb: { val: 'bb-value', vid: '33' },
        }
        */
    });
    

  • 返回Promise方式

    import $$sdk from '@datarangers/sdk-mp';
    $$sdk.init({
        // ...
    });
    $$sdk.send();
    
    $$sdk.getAllVars().then((data) => { 
        // data值大概如下：
        /* 
        {
          aa: { val: 'aa-value', vid: '11' },
          test_before_6d: { val: 'test_before_6d-value', vid: '22' },
          bb: { val: 'bb-value', vid: '33' },
        }
        */ 
    });
    

getAbSdkVersion

• 作用：​获取已曝光的实验，返回的结果是所有曝光实验的vid，使用逗号连接起来，格式例如：123,234,678

• 定义：​getAbSdkVersion(): string

• 返回值：

  类型	说明
  string	所有曝光实验的vid，使用逗号连接起来，格式例如：123,234,678

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  const vids = $$sdk.getAbSdkVersion();
  // vids值类似 123,234,678
  

setExternalAbVersion

• 作用：手动设置额外的AB实验配置。

• 定义：setExternalAbVersion(vids: string 或 null): void

• 参数：

  参数名	类型	必填	说明
  vids	string 或 null	是	vids的格式要求：使用逗号将vids值连接起来，大概这样'123,234,678'。 通过此方式设置的额外的实验配置vids，会合并到通过getVar处理获得到的vids中。 多次调用时，最后一次设置的额外的实验配置vids会覆盖之前的。 当设置null时，SDK会清空设置的额外的实验配置vids，并且不会影响通过getVar处理获得到的vids。

• 示例：

  • 设置额外的实验配置

    import $$sdk from '@datarangers/sdk-mp';
    $$sdk.init({
        // ...
    });
    $$sdk.send();
    
    // 手动设置额外的
    $$sdk.setExternalAbVersion('25,225,2225');
    

  • 清空额外的实验配置

    import $$sdk from '@datarangers/sdk-mp';
    $$sdk.init({
        // ...
    });
    $$sdk.send();
    
    // 清空额外的
    $$sdk.setExternalAbVersion(null);
    

此模块提供设置用户属性能力，并提供了一系列的方法：profileSet、profileSetOnce、profileUnset、profileIncrement、profileAppend。

开启模块

使用此模块，需要在SDK初始化设置时，在init接口中开启相应参数：enable_profile: true。

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

模块方法

profileSet

• 作用：将属性字段用新的值覆盖，一次可以设置一个或多个属性，支持数组类型属性值。

• 定义：profileSet(params: Record<string, string 或 number 或 Array>): void

• 参数：

  参数名	类型	必填	说明
  params	Record<string, string 或 number 或 Array>	是	设置的用户属性值。将属性字段用新的值覆盖，一次可以设置一个或多个属性，支持数组类型属性值。

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  $$sdk.profileSet({
      trade: '篮球',
      interests: ['篮球', '跑步', '摄影'],
  });
  

profileSetOnce

• 作用：按属性字段，只设置一次，如果已经有值，则不再更新。

• 定义：profileSetOnce(params: Record<string, string 或 number 或 Array>): void

• 参数：

  参数名	类型	必填	说明
  params	Record<string, string 或 number 或 Array>	是	设置的用户属性值。按属性字段，只设置一次，如果已经有值，则不再更新。

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  $$sdk.profileSetOnce({
      trade: '篮球',
  });
  

profileUnset

• 作用：删除某个属性的值。

• 定义：profileUnset(key: string): void

• 参数：

  参数名	类型	必填	说明
  key	string	是	删除的用户属性值。

• 示例：

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

profileIncrement

• 作用：将数值型属性增加指定的值，可以为负数。

• 定义：profileIncrement(params: Record<string, number>): void

• 参数：

  参数名	类型	必填	说明
  params	Record<string, number>	是	增加的用户属性值。将数值型属性增加指定的值，可以为负数。

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  $$sdk. profileIncrement({
      age: 10,
      money: -10000,
  });
  

profileAppend

• 作用：当属性不存在时候，创建属性，并set，如果是数组类型属性的，会把值追加进数组。

• 定义：profileAppend(params: Record<string, string 或 number 或 Array>): void

• 参数：

  参数名	类型	必填	说明
  params	Record<string, string 或 number 或 Array>	是	设置的用户属性值。当属性不存在时候，创建属性，并set，如果是数组类型属性的，会把值追加进数组。

• 示例：

  import $$sdk from '@datarangers/sdk-mp';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  $$sdk.profileAppend({
      trade: '篮球',
      interests: ['钓鱼'],
  });
  

开启模块

要求SDK版本2.13.0+。使用此模块，首先需要导入元素曝光插件并注册，然后在SDK初始化时开启相关参数。

1. 导入exposure插件，并使用SDK实例集成exposure插件；
2. 在SDK初始化时，使用enable_exposure明确开启曝光采集，再配置exposure_config参数明确曝光参数。

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

// 导入元素曝光插件并注册
import Exposure from '@datarangers/sdk-mp/esm/plugin/exposure';
$$sdk.usePlugin(Exposure);

$$sdk.init({
    // ...
    
    // 需要先开启enable_exposure，然后再配置exposure_config
    enable_exposure: true,
    exposure_config: {
        tags: ['logsdk-exposure'],
        rate: 0.5,
        duration: 3,
        bis: false,
    },
    // 如果是使用taro框架开发的需要明确设置framework
    framework: {
        taro: Taro,
    }
});
$$sdk.send();

配置参数说明

1. enable_exposure：是否开启曝光采集，默认值为false，设置为true表示开启曝光采集。

2. exposure_config：曝光采集具体参数配置项，包含class_tags、rate、stay_duration、need_repeat具体参下表。

   说明

   在init中设置exposure_config为全局参数，可以被组件上单独添加的曝光参数和通过API进行曝光的配置参数覆盖。

   $$sdk.init({
       // ...
       
       // 需要先开启enable_exposure，然后再配置exposure_config
       enable_exposure: true,
       exposure_config: {
           tags: ['logsdk-exposure'],
           rate: 0.5,
           duration: 3,
           bis: false,
       },
   });
   

   配置项	类型	默认值	说明
   tags	array	['logsdk-exposure']	曝光标记，是组件的class属性值。
   rate	number	0	曝光的可见比例，值范围为 0~1。0 表示只要露出就满足曝光；1 表示组件需要完全露出才满足曝光。
   duration	number	0	有效停留时长，单位为秒。
   bis	boolean	false	是否允许重复曝光采集。

3. framework：如果是使用taro框架开发的需要明确设置framework。

   $$sdk.init({
       // ...
       
       // 如果是使用taro框架开发的需要明确设置framework
       framework: {
           taro: Taro,
       },
   });
   

   配置项	类型	默认值	说明
   framework	Object	null	使用Taro框架开发的应用在开启曝光采集时需要设置该属性，值固定为。 { taro: Taro }

配置曝光组件

满足这三种场景：全局组件的配置统一场景、页面组件的配置统一场景、组件单独添加曝光参数场景。

全局组件的配置统一场景

在任何页面组件上添加“class”标记，“class”的值为在init时配置exposure_config中的tags中的其中一个值，如果没有配置tags，则是默认值“logsdk-exposure”。然后设置必须的属性data-logsdk-exposure-event-name=“曝光事件名”，事件名本身符合上报事件的名称要求即可。

• 默认值

  $$sdk.init({
      // ...
      
      enable_exposure: true,
      exposure_config: {
          rate: 0.5,
          duration: 3,
          bis: false,
      },
  });
  

  <view class="logsdk-exposure" data-logsdk-exposure-event-name="woshibaoguang"></view>
  

• 自定义值

  $$sdk.init({
      // ...
      
      enable_exposure: true,
      exposure_config: {
          tags: ['my-app-exposure-tag'],
          rate: 0.5,
          duration: 3,
          bis: false,
      },
  });
  

  <view class="my-app-exposure-tag"  data-logsdk-exposure-event-name="woshibaoguang"></view>
  <!--使用logsdk-exposure依旧可以，它是默认值-->
  <view class="logsdk-exposure"  data-logsdk-exposure-event-name="woshibaoguang"></view>
  

页面组件的配置统一场景

在页面中组件上添加“class”标记，设置属性“data-logsdk-exposure-option”配置参数

Page({
  data: {
    option: {
      exposure_config: {
        rate: 0,
        duration: 0,
        bis: false
      },
      event_name: "exposure_name",
      event_properties: {
        haha: "属性haha的值",
        enen: "属性enen的值",
        // ...
      }
    }
  }
});

<view class="logsdk-exposure" data-logsdk-exposure-option="{{option}}"></view>

针对组件单独添加曝光参数

在页面中组件上添加“class”标记，设置具体曝光参数属性

<view 
    class="logsdk-exposure" 
    data-logsdk-exposure-config-rate="0"
    data-logsdk-exposure-config-duration="3"
    data-logsdk-exposure-config-bis="true"
    data-logsdk-exposure-event-name="test"
    data-logsdk-exposure-event-property-haha="haha"
 ></view>

使用API进行元素曝光

addObserver

• 作用：对指定元素进行曝光监听。

• 定义：addObserver(tag: string, config?: OuterRawConfig, listener?: Listener): void

• 参数：

  参数名	类型	必填	说明
  tag	string	是	曝光标记，组件的class
  config	OuterRawConfig type OuterRawConfig = { rate: number; duration: number; bis: boolean; component?: any; };	否	同曝光采集配置
  listener	Listener type Listener = { canExposure?: (tag: string, props: Record<string, any>) => boolean; doneExposure?: (tag: string, props: Record<string, any>) => void; };	否	当前曝光组件触发曝光事件时的回调 canExpose: 是否触发曝光事件回调 doneExpose: 已触发曝光回调

• 示例：

  $$sdk.addObserver(
      '组件class值', 
      {
          rate: 0.5,
          duration: 0,
          bis: false
      },
      {
          canExposure: function(tag, properties){
              // tag 为当前曝光的组件的曝光标记
              // properties 为曝光组件的信息及该组件的曝光自定义属性
              // 触发曝光事件则返回 true
              // 不触发曝光事件则返回 false
              return true
          },
          doneExpose: function(tag, properties){
              // tag 为当前曝光的组件的曝光标记
              // properties 为曝光组件的信息及该组件的曝光自定义属性
          }
      }
  );
  

removebserver

• 作用：移除对指定元素的曝光监听。

• 定义：removebserver(tag: string): void

• 参数：

  参数名	类型	必填	说明
  tag	string	是	曝光标记，组件的class

• 示例：

  $$sdk.removebserver('组件class值');
  

部分场景推荐使用方式

Taro框架中使用

首先创建rangers.js（或.ts）文件，里面封装SDK的初始化代码。

import $$sdk from '@datarangers/sdk-mp';
import Exposure from '@datarangers/sdk-mp/esm/plugin/exposure';
$$sdk.usePlugin(Exposure);

$$sdk.init({
    // ...
    
    // 需要先开启enable_exposure，然后再配置exposure_config
    enable_exposure: true,
    exposure_config: {
        tags: ['logsdk-exposure'],
        rate: 0.5,
        duration: 3,
        bis: false,
    },
    // 如果是使用taro框架开发的需要明确设置framework
    framework: {
        taro: Taro,
    }
});
$$sdk.send();

export default $$sdk;

接着在app.js（或.ts）入口文件中引入rangers.js（或.ts）。

// 尽量在入口的最前面引入
import $$sdk from './rangers';

// ...

接着在page.js（或者.ts）页面中引入rangers.js（或.ts），并使用SDK实例的相关方法。

// page.js
import React, { useEffect } from 'react';
import { View } from '@tarojs/components';
import Taro, { useDidShow, useDidHide } from '@tarojs/taro';
import $$sdk from './rangers';

function Index() {
  // 可以使用所有的 React Hooks
  useEffect(() => {});

  // 对应 onShow
  useDidShow(() => {
      // 需要在nextTick中使用，等Taro渲染完毕后
      Taro.nextTick(() => {
          $$sdk.addObserver('my-exposure-tag', {
            rate: 0.5,
            duration: 0,
            bis: false
          });
      });
  });

  // 对应 onHide
  useDidHide(() => {
      $$sdk.removObserver('my-exposure-tag');
  });

  return <View className="index my-exposure-tag" data-logsdk-exposure-event-name="event-test" />
}

export default Index;

动态渲染场景

<!-- page.wxml -->
<view class="logsdk-exposure" wx:for="{{items}}" wx:key="index" data-logsdk-exposure-event-name="{{item.event}}">
  {{index}}: {{item.event}}
</view>

// page.js
import $$sdk from './rangers';

Page({
    data(){
        return {
            items: [],
        };
    },
    onShow(){
        // 模拟接口请求获取到数据
        fetch().then((datas) => {
            /* 数据大概如下
            datas = [{event: 'test1'}, {event: 'test2'}]
            */
            this.setData({items: datas}, () => {
                $$sdk.addObserver('logsdk-exposure', {
                    rate: 0.5,
                    duration: 0,
                    bis: false
                });
            });
        });
    },
});