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

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

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

• 参数：

  参数名	类型	必填	说明
  options	interface InitParams { app_id: number; log?: boolean; channel?: 'cn' 或 'sg'; channel_domain?: string; auto_report?: boolean; 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 私有化： 私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地。如您不清楚此地址，请联系您的项目经理或客户成功经理。
  自动上报	auto_report	boolean	否	设置是否需要自动采集为您提供的预置事件和预置属性数据（默认为false，不采集）。
  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环境）：您无需修改，保持默认值即可。 私有化： 私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。
  	clear_ab_cache_on_user_change	boolean	否	如果开启了A/B实验，您可以设置切换用户时是否需要重新获取A/B实验的配置信息，如果要关闭则把clear_ab_cache_on_user_change配置项置为false，默认是true。
  缓冲 （仅2.2.0及以上版本支持）	enable_buffer	boolean	否	设置true后，将开启缓冲。
  	buffer_interval	number	否	缓冲的间隔时间，单位是毫秒，默认值 5000，含义是到达间隔时间后会上报缓冲区的所有事件。
  	buffer_number	number	否	缓冲的最大数量，默认值 5，含义是缓冲数量达到该值后会立即上报缓冲区的所有事件。
  缓存 （仅2.2.0及以上版本支持）	enable_cache	boolean	否	开启后，请求失败的事件会存到storage中，并在用户下一次再进小游戏时补充上报。
  其他	enable_profile	boolean	否	设置true后，可以使用profile相关API，主要用于设置用户属性相关数据采集，详情请参见用户属性模块及API。

• 示例：

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

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

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

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

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

• 参数：

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

• 示例：

  import $$sdk from '@datarangers/sdk-quick';
  $$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 事件属性值支持number、string、array、object、boolean类型，数据采集后落库至DataFinder时，数据格式会做一些转化，更多说明请参见支持的数据格式与事件/属性分类。 不要在事件属性中再嵌套object，即属性值不接受object类型，如果业务数据为嵌套object类型，可通过转义的方式转成String后再上报。请参见示例1：嵌套JSON类型属性如何上报并用于过滤、分组。 如果想要表达事件属性值空的含义，建议用“be_null”，不建议使用""或" "。

• 示例：

  import $$sdk from '@datarangers/sdk-quick';
  $$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-quick';
  $$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,
      },
  ]);
  

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

开启模块

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

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

  • 返回Promise方式

    import $$sdk from '@datarangers/sdk-quick';
    $$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-quick';
    $$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-quick';
    $$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-quick';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  const vids = $$sdk.getAbSdkVersion();
  // vids值类似 123,234,678
  

setExternalAbVersion

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

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

• 参数：

  参数名	类型	必填	说明
  vids	string	null	是 通过此方式设置的额外的实验配置vids，会合并到通过getVar处理获得到的vids中。 多次调用时，最后一次设置的额外的实验配置vids会覆盖之前的。 当设置null时，SDK会清空设置的额外的实验配置vids，并且不会影响通过getVar处理获得到的vids。

• 示例：

  • 设置额外的实验配置

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

  • 清空额外的实验配置

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

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

开启模块

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

import $$sdk from '@datarangers/sdk-quick';
$$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-quick';
  $$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-quick';
  $$sdk.init({
      // ...
  });
  $$sdk.send();
  
  $$sdk.profileSetOnce({
      trade: '篮球',
  });
  

profileUnset

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

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

• 参数：

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

• 示例：

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

profileIncrement

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

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

• 参数：

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

• 示例：

  import $$sdk from '@datarangers/sdk-quick';
  $$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>

• 示例：

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