1、简介

热力引擎 ( SolarEngine ) 是面向移动开发者提供的帮助产品持续增长的一站式智能营销服务平台，在报表方面提供固定分析报表服务和高度自定义的数据分析服务，系统在数据埋点、属性设置、报表创建、看板配置等多方面都支持开发者按需求进行个性化配置。

本文档将针对 快应用  SDK 端的数据上报进行说明，帮助您进行数据接入。

隐私权政策：https://www.solar-engine.com/privacyPolicy.html

2、集成前的准备工作

在正式开始数据接入之前，需要提前准备一些接入过程中需要的参数、准备 SDK 包，下面说明如何获取这些信息。

2.1、获取 userCode

报送数据需要 userCode 及 Appkey，负责人账号管登录热力引擎系统系统后可自行查询。

userCode 查询路径：账户管理-账号信息-密钥-16 位 userId（即 user Code）。

2.2、获取 Appkey

Appkey 查询路径：资产管理-应用管理-16位 Appkey（即应用 ID）。

2.3、获取 SDK

SDK下载地址（提供umd和es两种格式包）

https://sdk.solar-engine.com/QuickApp/SolarEngine-QuickApp-CN-SDK-1.3.0.zip    

3、SDK 集成

注意: 需要在项目的manifest.json中的features中声明system.fetch和system.storage。否则可能会导致sdk功能不可用。

// manifest.json
{
   "features": [
        {"name": "system.storage"},
        {"name": "system.fetch"}
   ]
}

3.1、SDK初始化

建议在快应用项目中的app.ux中引入SDK并在onCreate中初始化，以保证数据初始化的准确性。SDK初始化之前，需要先进行预初始化, 调用prevInit方法，传入应用的 appKey。

注意：一个快应用中只能引入1次SDK，app.ux中引入SDK后建议挂载到全局(比如global)上供其他地方使用。

如果是ES Modules的开发环境，请引入es格式文件，否则请引入umd格式文件。

// app.ux
import SESDK from './quickapp-cn-sesdk-umd.js';

// 如果打包环境强制使用ES Modules方式，请引入es格式文件。  
// import SESDK from './quickapp-cn-sesdk-es.js'  

// 某些平台可能仅支持commonjs方式引入，则需要使用require方式引入  
// const SESDK = require('./quickapp-cn-sesdk-umd.js')

export default {
  onCreate() {
    // 预初始化
    SESDK.prevInit('appKey'); 
    // 初始化
    SESDK.init(initParams);
    // 挂载到全局(比如global)上供其他地方使用
    global.SESDK = SESDK;
  },
};

initParams参数说明：

初始化配置Config参数说明：

调用示例：

SESDK.prevInit('6666666'); 
SESDK.init({
  appKey: '666666',
  userId: '888888',
  config: {
    logEnabled: true,
  },
});

由于SDK的初始化逻辑是异步进行的，如果业务场景中需要依赖SDK初始化完成之后的执行逻辑，可调用ready方法

SESDK.ready(callback);

SDK初始化过程中，如需加载SDK插件，可调用use方法

SESDK.use(sdkPlugin);

3.2、访客 ID

访客 ID 即 _visitor_id，是用户在设备上安装了应用之后，登录状态之前该用户的唯一标识。

我们提供访客 ID 自定义设置的接口，如果您有自己的访客管理体系需要替换访客 ID，应在 SDK 初始化之前进行设置。

数据上报时仅以最后一次传入的访客 ID 为准，应避免多次调用造成多个非正常访客 ID 先后上报数据的情况。

3.2.1、设置访客 ID

调用 setVisitorId: 来设置访客 ID：

SESDK.setVisitorId('vid8709901241')

注：

该调用仅为向 SDK 传入访客 ID，不会上报用户设置事件。

开发者设置的访客ID长度不能超过128个字符，否则会设置失败。

开发者设置后会存储在本地存储中。

3.2.2、获取访客 ID

如果您需要获取当前访客 ID，可以调用 getVisitorId 获取：

SESDK.getVisitorId()

3.3、账号 ID

指用户在应用中登录之后，登录账号在应用中的唯一标识。登录之前将以访客 ID 作为用户标识。

在账户 ID 设置完成后，在调用 logout 清除账号 ID之前，设置的账号 ID 将一直保留，并作为用户身份识别 ID。清除账号 ID 的操作请在有真实退出登录状态行为时进行，关闭 App、退至后台运行时无需调用。

数据上报时仅以最后一次传入的账号 ID 为准，应避免多次调用造成多个非正常账号 ID 先后上报数据的情况。

3.3.1、设置账号 ID

调用 login 来设置用户的账号 ID：

SESDK.login('aid25491084');

注：

该调用仅为向 SDK 传入账号 ID，不会上报用户登录事件。

开发者设置的账号 ID 长度不能超过 128 个字符，否则会设置失败。

开发者设置后会存储在本地存储中。

3.3.2、获取账号 ID

调用 getAccountId 来获取用户的账号 ID：

SESDK.getAccountId();

3.3.3、清除账号 ID

调用 logout 来清除账号 ID：

SESDK.logout();

注：该调用仅为通知 SDK 清除账号 ID，不会上报用户登出事件。

3.4、设置公共事件属性

公共事件属性指的是每个事件都会带有的属性，对于一些重要的属性，如用户的来源渠道、转化的广告 ID 等，这些属性需要设置在每个事件中，这些属性可以被设置为公共事件属性。

公共事件属性设置的方法最好放在SDK的初始化方法之前，这样可以保证所有的上报事件中都能存在我们已经设置好的公共事件属性。

您可以调用 setSuperProperties 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

公共事件属性的格式要求与事件属性一致，见“事件上报-自定义属性要求”

SESDK.setSuperProperties({
   key:  value
});

如果您需要删除某个公共事件属性，可以调用 unsetSuperProperty 清除其中一个公共事件属性；

SESDK.unsetSuperProperty(key);

如果您想要清空所有公共事件属性，则可以调用 clearSuperProperties。

SESDK.clearSuperProperties();

注：

如果调用 setSuperProperties 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。

如果公共事件属性和事件上报上传的某个属性的 key 重复，则该事件的属性会覆盖公共事件属性。

开发者设置后会存储在本地存储中。

3.5、设置预置事件属性

热力引擎 SDK 支持开发者对启动、安装、退出三个预置事件设置自定义属性，通过这些自定义属性，开发者可以更方便地统计和分析数据。

SESDK.setPresetEvent(eventType, properties);

注：

1. 设置预置事件自定义属性的方法必须在热力引擎SDK初始化之前设置，这样设置的属性会适用于所有后续SDK产生的预置事件，如果在SDK初始化之后再设置，在此之前产生的预置事件不会包含这些设置的自定义属性。
2. 预置事件设置的自定义属性不会被缓存，每次设置都会覆盖前一次的设置，多次设置同一个预置事件只有最后一次生效。
3. 如果设置了 eventType 的枚举为 all，会覆盖通过mpInstall、mpStart、mpEnd 这三种枚举设置的自定义属性，如果多次设置，只有最后一次生效。
4. 给预置事件设置的自定义属性支持清空，可以调用对应的枚举清空，如下：SESDK.setPresetEvent('mpInstall', null); 上述方法可以用来清空启动事件的自定义属性，安装与退出事件只需更改对应的枚举值即可。
5. 另外，热力引擎 SDK 也支持全局清除预置事件的自定义属性，如下：SESDK.setPresetEvent('all', null); 上述方法可以清空所有预置事件的自定义属性，通过 mpInstall、mpStart、mpEnd 这三种枚举设置的自定义属性会被一并清空。

调用示例：

SESDK.setPresetEvent('mpInstall', {
  k1: 'v1',
  k2: 'v2'
});

3.6、设置其他上报属性

3.6.1、设置渠道名称

调用 setChannel 方法设置渠道名称_channel

SESDK.setChannel('channel');      

3.6.2、设置快应用来源页面title信息

调用 setReferrerTitle 方法设置来源页面title信息_referrer_title

SESDK.setReferrerTitle('title');       

3.6.3、设置快应用当前页面query信息

开发者调用 setQuery 方法设置当前页面query信息

// 在页面的onInit中，获取到query信息后
onInit(query) {
   SESDK.setQuery(query); 
} 

3.7、获取distinct_id和distinct_id_type

开发者调用getDistinctId方法可获取到distinct_id和distinct_id_type，该方法返回一个Promise对象。

SESDK.getDistinctId().then(data => {
   // data.result.distinct_id
   // data.result.distinct_id_type
})

3.8、获取归因结果

3.8.1、设置监听归因结果回调

开发者设置监听归因结果回调。仅可调用一次。该方法返回一个Promise对象。

SESDK.setOnAttributionListener().then(res => {
   // res.result   归因结果信息
})

3.8.2、主动获取归因结果

开发和主动获取归因结果信息。可多次调用。该方法返回一个Promise对象。

SESDK.getAttribution().then(res => { 
     // res.result 归因结果信息
})

4、事件上报

在 SDK 初始化完成之后，就可以通过调用方法来进行数据的上报。

上报的数据主要分为以下 4 类：

• 预置事件：该类事件由 SDK 按规则自行触发上报，无需开发者调用。有确定的 _event_name ，如安装、启动、退出等事件。
• 预定义事件：该类事件已经在系统中明确定义了事件意义，有确定的 _event_name 。需要在对应的事件发生时，由开发者触发上报，如变现广告展示、应用内付费等。
• 自定义事件：即系统未明确定义意义的事件，开发者可按分析需要自行定义并埋点进行上报。
• 时长事件：需要记录某个事件的持续时长，用来进行相关的分析。

注：事件名支持大小写中英文、数字、下划线，长度不超过 40。

下面将对每种事件的上报规则进行一一说明。

4.1、预置事件

4.1.1、安装

每次安装后首次打开自动报送该事件。（删除快应用后，再次打开快应用时算一次安装）

安装事件的 _event_name 为 _mpInstall。

4.1.2、启动

每次打开快应用、或快应用从后台进入前台时，如果需要报送该事件，需要在每一个页面的onShow中调用trackAppStart方法。

启动事件的 _event_name 为 _mpStart。

// page页面
export default {
   onShow() {
      global.SESDK.trackAppStart();
   }
}

4.1.3、退出

快应用从前台进入后台时，如果需要报送该事件，需要在每一个页面的onShow中调用trackAppEnd方法。

退出事件的 _event_name 为 _mpEnd。

// page页面
export default { 
    onHide() { 
        global.SESDK.trackAppEnd(); 
     } 
 }

4.2、预定义事件

4.2.1、变现广告展示事件

变现广告展示时，报送该事件，用于进行广告展示及变现收入分析。

SESDK.trackAdImpression(data)

data 为object类型，参数说明：

调用示例：

SESDK.trackAdImpression({
  adNetworkPlatform: 'oppo',
  adType: 1,
  adNetworkAppID: '123',
  adId: '123',
  mediationPlatform: 'custom',
  ecpm: 13.140001,
  currency: 'USD',
  rendered: true,
  customProperties: {
    one: '1',
  }
})

4.2.2、变现广告点击事件

变现广告点击时，报送该事件，用于进行广告点击数据分析。

SESDK.trackAdClick(data)

data 为object类型，参数说明：

调用示例：

SESDK.trackAdClick({
  adNetworkPlatform: 'oppo',
  adType: 1,
  adId: '123',
  mediationPlatform: 'custom',
  customProperties: {
    one: '1',
  }
})

4.2.3、应用内购买事件

付费购买时，报送该事件，用于进行购买及内购收入分析。

SESDK.trackIAP(data)

data 为object类型，参数说明：

注：支付失败原因 failReason 参数仅在 payStatus 参数为 fail 支付失败时才会传入，其他状态传""即可。

调用示例：

SESDK.trackIAP({
  orderId: '12345678',
  payAmount: 1234.5678,
  currencyType: 'USD',
  payType: 'alipay',
  productID: '12345678',
  productName: 'this is product name',
  productCount: 10,
  payStatus: 1,
  failReason: 'this is fail reason',
  customProperties: {
    one: '1',
  }
})
自归因安装事件

4.2.4、增加归因安装事件

支持统计归因数据，满足客户使用三方归因或者自归因之后的结果数据回传到自定义分析，上报时机支持开发者自定义触发。

自归因事件的 _event_name 为 _mpAttr。

SESDK.trackAppAttr(data)

data 为object类型，参数说明：

示例代码：

SESDK.trackMpAttr({
  adNetwork: '123456',
  subChannel: '123456',
  adAccountID: '123456',
  adAccountName: '123456',
  adCampaignID: '123456',
  adCampaignName: '123456',
  adOfferID: '123456',
  adOfferName: '123456',
  adCreativeID: '123456',
  adCreativeName: '123456',
  attributionPlatform: '123456',
  customProperties: {
  	one: '1',
  }
})

4.2.5、订单事件

用于进行订单数据分析。

SESDK.trackOrder(data)

data 为object类型，参数说明：

调用示例：

SESDK.trackOrder({
  orderId: '12345678',
  payAmount: 1234.5678,
  currencyType: 'USD',
  payType: 'alipay',
  status: 'this is fail status',
  customProperties: {
    one: '1',
  }
})

4.2.6、注册事件

用户注册时，报送该事件，用于进行用户注册数据分析。

SESDK.trackRegister(data)

data 为object类型，参数说明：

调用示例：

SESDK.trackRegister({
  regType: 'WeChat',
  registerStatus: 'success',
  customProperties: {
    one: '1',
  }
})

4.2.7登录事件

用户登录时，报送该事件，用于进行用户登录数据分析。

SESDK.trackLogin(data)

data 为object类型，参数说明：

调用示例：

SESDK.trackLogin({
  loginType: 'WeChat',
  loginStatus: 'success',
  customProperties: {
    one: '1',
  }
})

4.3、自定义事件

除了以上已经列出的有明确定义的事件外，开发者可以根据自己的分析需求，进行自定义事件的上报

自定义事件，即事件的 _event_name 由开发者自定义。

您可以调用 track(eventName, data) 来上报事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件。

事件名称要求：

• string 类型
• 只能以字母开头，其余字符可包含数字、小写字母和下划线"_"
• 长度最大为 40 个字符
• 仅支持小写字母

调用示例：

SESDK.track('test', {
  one: '1',
});

4.4、自定义属性要求

事件的属性是一个 object 对象，其中每个元素代表一个属性。

4.4.1、key 为该属性的名称

• string 类型
• 只能以字母开头，其余字符可包含数字、小写字母和下划线"_"
• 长度最大为 40 个字符
• 仅支持小写字母

4.4.2、value 为该属性的值

• 支持 string、number 、boolean和 array
• 对于 array 的元素，只支持字符串类型
• 对于其他类型都将强制转为字符串存储

4.4.3、自定义属性的属性类型

一个自定义属性的存储数据类型，会以第一次上报数据的格式自动由系统进行识别，一旦确定无法修改。相同产品的属性类型在第一次上报时进行确定。后续不同SDK、不同事件上报的同名属性只有类型与第一次一致才会入库。

注：属性的存储数据类型，决定了在分析模型中可以选择的分析逻辑，比如数值型可以进行最大值、最小值、求和等计算，布尔型可以进行为真数、为假数的计算，所以报送数据的格式，需要考虑分析场景和业务需求，制定完整的埋点方案，并按埋点方案进行格式确定。

4.5、时长事件

如果您需要记录某个事件的持续时长，可以调用 eventStart(eventName) 来开始计时，配置您想要计时的事件名称，当您结束该事件时，需要调用 eventFinish(eventName, data)，它将会自动在您的事件属性中加入 _duration 这一属性来表示记录的时长，单位为毫秒。需要注意的是，同一个事件名只能有一个在计时的任务。

SESDK.eventFinish('testEvent', {
  one: '1',
});

注：在上报预置事件 _appEnd 时，会默认上报由上一次 _appStart 开始计时的时长，即退出事件的时长无需配置开始计时，会默认赋值。

5、用户属性设置

在热力引擎中，专门提供了针对用户属性设置数据的上报方法，针对用户的属性的添加或变更，您可以通过该方法进行上报。

建议您将与用户相关的不变的、或变化频率比较低、或保存价值比较高的属性，比如年龄、创建角色时间、等级、所在地、首次付费时间、总付费金额等属性设置为用户属性，其它变化频率比较高的属性通过事件进行上报和记录。

用户属性设置分为以下几种方式：userUpdate、userInit、userAdd、userUnset、userAppend、userDelete，由开发者调用，对用户属性进行设置。

注：用户属性格式要求与事件属性保持一致。

5.1、userInit

如果您要上传一批用户属性，其中已经存在的用户属性不去更新属性值、对不存在的属性进行创建并保存属性值，则可以调用 userInit 来进行设置。

调用示例：

SESDK.userInit({
  regtime: "2021-03-01 12:34:56.789", // 自定义属性
  rolename: "engineer", // 自定义属性
  age: 29, // 自定义属性
});

5.2、userUpdate

对于一般的用户属性，您可以调用 userUpdate 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致。

调用示例：

SESDK.userUpdate({
  rolename: "leader", // 自定义属性
});

5.3、userAdd

当您要上传数值型的属性时，您可以调用 userAdd 来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。

调用示例：

SESDK.userAdd({
  age: 1, // 自定义属性
});

userAdd 设置的属性类型以及 Key 值的限制与 userUpdate 一致，但 Value 只允许 number 类型。

5.4、userUnset

当您要清空用户的属性值时，您可以调用 userUnset 来对指定属性（字符串数组）进行清空操作，如果该属性还未在集群中被创建，则 不会 创建该属性。

调用示例：

SESDK.userUnset(["age"]);

userUnset 传入的参数是用户属性的属性名，类型是字符串数组。

5.5、userAppend

您可以调用 userAppend 对数组类型的用户属性进行追加操作。如果该属性不存在，则会新建该属性。

调用示例：

SESDK.userAppend({
  location: ["BeiJing"], // 自定义属性
});

5.6、userDelete

如果您要删除某个用户，可以调用 userDelete 将这名用户删除。用户删除后，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

调用示例：

SESDK.userDelete(deleteType);

// 通过AccountId删除用户 
SESDK.userDelete('userDeleteByAccountId'); 

// 通过VisitorId删除用户 
SESDK.userDelete('userDeleteByVisitorId');

————————————

SDK 更新记录

2025-03-14 1.3.0

• 事件上报逻辑优化

2025-03-13 1.2.9

• 事件上报逻辑优化

2025-02-13 1.2.8

• 付费事件上报优化

2025-01-03 1.2.7

• 付费事件上报优化

2024-12-10 1.2.4

• 上报逻辑优化

2024-11-29 1.2.3

• 初始化逻辑优化

2024-11-11 1.2.2

• 新增获取归因结果方法
• 新增设置当前页面的query方法
• 初始化方法新增getQuickQueryWaitTime

2024-10-31 1.2.1

•增加sdk内部日志上报

2024-08-14 1.1.9

• SDK对外API校验逻辑优化

2024-05-22 1.1.8

• install事件上报优化

2024-04-22 1.1.7

• 优化事件上报逻辑

2024-04-16 1.1.6

• SolarEngine 快应用 SDK 初版
• 支持预定义属性、自定义属性设置
• 支持预定义事件、自定义事件上报
• 支持用户属性设置
• 支持参数下发插件