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

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

• 定义：constructor(configuration: InitialConfig)

• 参数：

  参数名	类型	必填	说明
  configuration	interface InitialConfig { app_id: number; logLevel?: string; // 'info' 或 'error' 或 'silent' channel?: string; // 'cn' 或 'sg' channel_domain?: string; enable_ab_test?: boolean; ab_channel_domain?: string; // ... }	是	SDK需要明确知道上报到哪个应用，上报到哪个DataFinder服务地址，开启哪些功能模块，这些就需要在SDK进行初始化时进行配置。

  参数分类	字段	字段值类型	必填	字段说明
  基础参数	app_id	number	是	应用ID，用于标识业务产品，即表明埋点采集的是哪个应用的数据。在DataFinder的控制台创建应用后会自动为您生成对应应用的应用ID，获取应用ID的操作请参见步骤2：获取APPID。
  	logLevel	string	否	设置日志类型。 info：输出所有类型的日志。 error：仅输出错误类型的日志。 silent（默认值）：不输出日志。
  	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 私有化： 私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地。如您不清楚此地址，请联系您的项目经理或客户成功经理。
  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环境）：您无需修改，保持默认值即可。 私有化： 私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。

• 示例：

  import { SDK } from '@datarangers/sdk-electron';
  
  const $$sdk = new SDK({
      app_id: 1,
      channel: 'cn',
          
      // ...更多配置参数
  });
  

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

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

• 参数：

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

• 示例：

  import { SDK } from '@datarangers/sdk-electron';
  const $$sdk = new SDK({
      app_id: 1,
      channel: 'cn',  
      // ...更多配置参数
  });
  
  // 设置事件公共属性，这些公共属性会在后续所有事件上报时都携带上
  $$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类型属性如何上报并用于过滤、分组。 如果想要表达事件属性值空的含义，建议用“be_null”，不建议使用""或" "。

• 示例：

  import { SDK } from '@datarangers/sdk-electron';
  const $$sdk = new SDK({
      app_id: 1,
      channel: 'cn',  
      // ...更多配置参数
  });
  
  // 在业务需要的地方进行调用event方法上报自定义事件
  $$sdk.event('some_event', {
      val: '...',
      path: '...',
  });
  

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

开启模块

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

import { SDK } from '@datarangers/sdk-electron';
const $$sdk = new SDK({
    app_id: 1,
    channel: 'cn',  
    // ...更多配置参数
    enable_ab_test: true,
    ab_channel_domain: "https://tab.volces.com", 
});

模块方法

getVar

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

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

• 参数：

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

• 示例：

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

getAllVars

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

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

• 参数：

  参数名	类型	必填	说明
  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' } }

• 示例：

  import { SDK } from '@datarangers/sdk-electron';
  const $$sdk = new SDK({
      // ...
  });
  
  $$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' },
      }
      */
  });
  

getAbSdkVersion

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

• 定义：​getAbSdkVersion(): string

• 返回值：

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

• 示例：

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

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

模块方法

profileSet

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

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

• 参数：

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

• 示例：

  import { SDK } from '@datarangers/sdk-electron';
  const $$sdk = new SDK({
      // ...
  });
  
  $$sdk.profileSet({
      trade: '篮球',
      interests: ['篮球', '跑步', '摄影'],
  });
  

profileSetOnce

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

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

• 参数：

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

• 示例：

  import { SDK } from '@datarangers/sdk-electron';
  const $$sdk = new SDK({
      // ...
  });
  
  $$sdk.profileSetOnce({
      trade: '篮球',
  });
  

profileUnset

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

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

• 参数：

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

• 示例：

  import { SDK } from '@datarangers/sdk-electron';
  const $$sdk = new SDK({
      // ...
  });
  
  $$sdk.profileUnset('trade');
  

profileIncrement

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

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

• 参数：

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

• 示例：

  import { SDK } from '@datarangers/sdk-electron';
  const $$sdk = new SDK({
      // ...
  });
  
  $$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-electron';
  const $$sdk = new SDK({
      // ...
  });
  
  $$sdk.profileAppend({
      trade: '篮球',
      interests: ['钓鱼'],
  });