1、简介

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

本文档为热力引擎 ( SolarEngine ) App 内行为事件通过接口上报的 API 接口说明，帮助您进行数据接入。

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

2、接入前的准备工作

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

2.1、获取 userCode

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

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

2.2、获取 Appkey

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

2.3、理解与标识用户

用户作为分析过程中的主体，正确进行用户标识是得出准确的分析结果的关键。为了便于在接入过程中理解热力引擎的用户体系，以便您进行正确的设置和标识，以下针对用户标识进行说明。

2.3.1、设备 ID

设备 ID 即 _distinct_id，指设备的唯一标识参数，在上报埋点时必须报送该属性。

Android ：建议报送设备的 AndroidId 作为 _distinct_id，如果 AndroidId 获取不到则获取随机的 UUID + 当前时间 13 位时间戳作为 _distinct_id。

iOS：建议报送设备的 IDFV 作为 _distinct_id，如果 IDFV 获取不到则获取随机的 UUID + 当前时间 13 位时间戳作为 _distinct_id。

2.3.2、访客 ID

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

但大多数休闲游戏或一些工具类应用没有用户注册和登录体系，访客 ID 将是标识用户最重要的 ID。

• 热力引擎 SDK 默认会用 _distinct_id 作为访客 ID，用 API 报送数据时，如果您没有报送 _visitor_id 的值，我们会在接收服务中以 _distinct_id 补充到 _visitor_id。
• 如果您有自己的访客 ID 体系，也可以根据您的实际情况为访客 ID 赋值。

2.3.3、账号 ID

账号 ID 即 _account_id，指用户在应用中注册之后，应用为该用户分配的用户 ID。

中重度游戏及大部分应用都有用户注册和登录体系。通过账号 ID，应用可以跨设备、跨平台识别同一用户，从而建立起用户的全平台行为轨迹，因此账号 ID 是多平台识别用户的 ID。

• 当您上报的事件是用户登录状态发生时，需要在数据中上报当前登录用户的 _account_id。
• 当事件是在未登录或退出登录状态下发生时，即不能关联到账号时，_account_id 请置空。

注：热力引擎中标识用户，会以账号 ID 优先进行识别；账号 ID 为空时会以访客 ID 进行识别。

3、数据报送

3.1、报送方式

数据报送地址：

海外版本报送地址请参考: https://vg-api-receiver.detailroi.com/datareceiver/receive/v3/sapi
国内版本报送地址请参考  https://api-receiver.detailroi.com/datareceiver/receive/v3/sapi

测试地址（测试地址提供上报数据错误明细信息，调试完成后请切换为上方正式地址）

• 将.com后的路径替换为 datareceiver/receive/sapiDebug

• 私有化部署项目需要与运维人员联系获取报送地址
• 所有请求格式统一使用 UTF-8 编码，请求方式使用 post
• iOS 必传参数，Android 不需上报；Android 必传参数，iOS 不需上报。预置属性名需与说明文档保持一致
• 报送的头信息中一定要有Content-Type=application/json参数

3.2、报送数据签名

3.2.1、token有效性

请求参数：

timestamp(时间戳)、sign

验签规则：

1、timestamp 30分钟内有效，

2、验签

sign =   Md5(appkey+timestamp)

说明：

• appkey： 热力引擎 portal 中的应用 ID 即 Appkey

Demo：

https://api-receiver.detailroi.com/datareceiver/receive/v3/sapi?timestamp={}&sign={}

appKey:"f499a4bdc9097b12"
timestamp:1648702202000
加密前字符串："f499a4bdc9097b121648702202000"
md5后 sign：18c55727422f35e66a8765c1f4e5e546

3.2.2、API demo

若您需要开启谷歌投放与配置数据回调，请务必上报 _app_version 和 _os_version 属性，否则谷歌会拒收数据

https://localhost:8008/datareceiver/receive/v3/sapi?timestamp=1648702202000&sign=8010b5be154a31cefe6762c78ba09312


[
    {
        "_oaid": "",
        "_one_id": "92692c8213c1ecc3770ad174c58430e5",
        "_event_id": "43e0f9ac-9c63-4aff-8340-64ccef8fed5f",
        "_type": "event",
        "_visitor_id": "",
        "_distinct_id": "3e4416a9d42f4566",
        "_package_type":2,//中国大陆产品传1，非中国大陆产品传2
        "_event_name": "_appEnd1",
        "_appkey": "1ef820c432fde099",
        "_ua": "Dalvik/2.1.0 (Linux; U; Android 9; MIX 3 MIUI/V10.0.12.0.PEECNFH)",
        "_uuid": "11e37840-2a9b-4acc-97fb-ef2de369e0d4",
        "_imei": "8698100361257575",
        "_session_id": "22119e2858154084b15301dd8351fde1",
        "_account_id": "",
        "_imei2": "869810036127576",
        "_android_id": "6dd78f842f095ab4",
        "_source_type": "api",
        "_ip":"102.249.1.212",
        "properties": {
            "_language": "zh",
            "_referrer_title": "",
            "_screen_height": 2210,
            "_manufacturer": "Xiaomi",
            "_referrer_name": "",
            "_app_version": "2.0.0",
            "_page_name": "com.xxx.xxx",
            "ad_network": "topon",
            "_is_first_time": false,
            "_duration": "",
            "_channel": "common",
            "_app_version_code": "2",
            "_lib_version": "1.0.2",
            "_screen_width": 1080,
            "_os_version": "9",
            "_browser": "",
            "_lib": 1,
            "_time_zone": "GMT+08:00",
            "_platform": 1,
            "_log_count": 922,
            "_device_type": 1,
            "_density": 2.75,
            "_app_name": "xxx",
            "_browser_version": "",
            "_device_model": "XiaomiMIX 2",
            "_is_first_day": true,
            "_network_type": 9,
            "_package_name": "com.xxx.xxx.xxx"
        },
        "_ts": 1646295420763,
        "_gaid": ""
    }
]

4、事件上报

上报的事件主要分为以下 3 类：

• 预置事件：该类事件一般由 SDK 按规则自行触发，有确定的 _event_name，如安装、启动、退出等事件。当您通过 API 进行数据接入时，这 3 个预置事件需要您自行配置触发时机，通过 API 接口报送到热力引擎。热力引擎对 SDK 或 API 上报的事件的分析方法是相同的，如果不报送预置事件，也将无法进行分析。
• 预定义事件：该类事件已经在系统中明确定义了事件意义，有确定的 _event_name，需要在对应的事件发生时，由开发者触发上报，如变现广告展示、应用内付费等。
• 自定义事件：即系统未明确定义意义的事件，开发者可按分析需要自行定义并埋点进行上报。

4.1、事件属性及报文格式

4.1.1、事件通用属性

以下为每个事件都有的字段参数，其中设备标识类字段用于固定报表的数据串联，用来进行收入、成本、ROI 等指标的计算，为了保证计算处理的准确性，请您尽量完整的报送。

部分预定义事件还会包含一些该事件所特有的字段，会在对应的事件说明列出。

在oppo vivo 华为 小米投放应用时，_oaid 为媒体要求的必传属性，如果 _oaid 无法获取请填写 _distinct_id

4.1.2、事件自定义属性

事件的属性是一个 JSON 对象，其中每个 key-value 代表一个属性。

自定义属性需全部位于 properties 内层报送。

key 为该属性的名称

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

value 为该属性的值

• 支持基本数据类型 String、int、long、float、double、boolean 等以及 Date 类型与数组
• 对于数组的元素，只支持字符串类型
• 对于其他类型都将强制转为字符串存储

自定义属性的属性类型

一个自定义属性的存储数据类型，会以第一次上报数据的格式自动由系统进行识别，一旦确定无法修改。

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

4.1.3、事件报文格式

以自定义事件为例，以下为请求示例

若您需要开启谷歌投放与配置数据回调，请务必上报 _app_version 和 _os_version 属性，否则谷歌会拒收数据

[{
  "_appkey": "c7d6914e9f4b423c",
  "_source_type": "api",
  "_type": "event", //事件类数据上报
  "_event_name": "addCart", //自定义事件标识
  "_account_id": "aid25491084",
  "_package_type":2, //中国大陆产品传1，非中国大陆产品传2
  "_visitor_id": "vid8709901241",
  "_distinct_id": "3e4416a9d42f4566",
  "_session_id": "100092419802",
  "_event_id": "56e3704cf535e5e6dccdc421e37b201e",
  "_ts": "1631790831000",
  "_idfa": "1e2dfa89-496a-47fd-9941-df1fc4e6484a",
  "_idfv": "599f9c00-92dc-4b5c-9464-7971f01f8370",
  "_ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_3_1 like Mac OS X)",
  "_ip": "1.119.175.47",
  "properties": {
    "_manufacturer": "Apple",
    "_app_version": "1.0.10.404",
    "regtime": "2021-03-01 12:34:56.789", //自定义属性
    "roleName": "dashen", //自定义属性
    "_log_count": 25,
    "_platform": 1,
    "_package_name": "com.xxx.xxx.xxx"
  }
}]

注：在报文中，字段表中 _ipv6 及之前的参数请置于 properties 外层报送，其它的全部字段置于内层报送。

返回示例：

成功 {"status":0}

4.2、预置事件

4.2.1、安装

安装事件为预置事件。每次安装后首次打开时报送该事件。

安装事件的 _event_name 为

APP 端： _appInstall

小程序/小游戏：_mpInstall

Web 端：_webInstall

4.2.2、启动

启动事件为预置事件。建议 iOS 端每次打开、或从后台进入前台时，Android 每次打开、或退出后台 30s 再进入前台时报送。

启动事件的 _event_name 为

APP 端： _appStart

小程序/小游戏：_mpStart

Web 端：_webStart

4.2.3、退出

退出事件为预置事件。建议 iOS 端应用退到后台时，Android 应用退出、或退到后台超过 30s 时报送。

退出事件的 _event_name 为

APP 端： _appEnd

小程序/小游戏：_mpEnd

Web 端：_webEnd

4.3、预定义事件

4.3.1、变现广告展示事件

变现广告展示事件为预定义事件。App 内变现广告展示时报送，用于进行广告展示及变现收入分析。使用发行中心功能、自定义分析变现指标时，必须报送该事件。

广告展示事件的 _event_name 请传

APP 端： _appImp

小程序/小游戏：_mpImp

Web 端：_webImp

变现广告展示事件需要上报的属性：

（各聚合平台对应传值字段参见： ROI-三方账户管理-聚合平台-其他聚合平台 ）

4.3.2、变现广告点击事件

变现广告点击事件为预定义事件。App 内变现广告被点击时报送，用于进行广告点击的分析。

广告展示事件的 _event_name 请传

APP 端： _appClick

小程序/小游戏：_mpClick

Web 端：_webClick

变现广告点击事件需要上报的属性：

4.3.3、应用内购买事件

App 内付费事件为预定义事件。App 内付费购买时报送，用于进行购买及内购收入分析。需要完整统计 App 收入，或后期使用系统提供的预测服务时，必须报送该事件。

应用内购买事件的 _event_name 请传

APP 端： _appPur

小程序/小游戏：_mpPur

Web 端：_webPur

应用内购买事件需要上报的属性：

上报示例

[
    {
        "_appkey": "1405a",
        "_source_type": "api",
        "_type": "event",
        "_package_type": 2,
        "_event_name": "_appPur",
        "_event_id": "bf269822",
        "_ts": 1719993598637,
        "_distinct_id": "bxbbcb22534b4",
        "_account_id": "123456",
        "_ip": "13.1.1.1",
        "_ua": "131",
        "properties": {
            "_order_id": "20230606180554",
            "_pay_amount": 9.99,
            "_currency_type": "BRL",
            "_platform": 1,
            "_pay_status": 1,
            "_package_name": "com.ove",
            "_pay_type": "GooglePay"
        }
    }
]

4.3.4、订单事件

App 内付费订单事件为预定义事件。App 产生付费订单时上报。

应用内购买事件的 _event_name 请传

APP 端： _appOrder

小程序/小游戏：_mpOrder

Web 端：_webOrder

付费订单事件需要上报的属性：

4.3.5、注册事件

用户注册事件为预定义事件。用户产生注册行为时上报。

注册事件的 _event_name 请传

APP 端： _appReg

小程序/小游戏：_mpReg

Web 端：_webReg

4.3.6、登录事件

用户登录事件为预定义事件。用户产生登录行为时上报。

注册事件的 _event_name 请传

APP 端： _appLogin

小程序/小游戏：_mpLogin

Web 端：_webLogin

4.3.7、自归因事件

自归因事件为预定义事件，开发者自定义触发时机。

自归因事件的 _event_name 为

APP 端： _appAttr

小程序/小游戏：_mpAttr

Web 端：_webAttr

4.4、自定义事件

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

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

事件名称要求：

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

5、用户属性设置

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

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

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

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

5.1、用户设置属性与报文格式

5.1.1、用户设置通用属性

以下为用户设置类数据的通用字段参数，其中 _account_id 及 _visitor_id 为查找用户的标识 ID，为了保证计算处理的准确性，请您尽量完整的报送。

5.1.2、用户设置自定义属性

事件的属性是一个 JSON 对象，其中每个 key-value 代表一个属性。

自定义属性需全部位于 properties 内层报送。

key 为该属性的名称

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

value 为该属性的值

• 支持基本数据类型 string、int、long、float、double、boolean 等以及 date 类型与数组
• 对于数组的元素，只支持字符串类型
• 对于其他类型都将强制转为字符串存储

自定义属性的属性类型

自定义用户属性数据类型的识别规则，与事件的自定义属性相同，处理方法也相同，即会以第一次上报数据的格式自动由系统进行识别，一旦确定无法修改。相同产品的属性类型在第一次上报时进行确定。后续不同SDK、不同事件上报的同名属性只有类型与第一次一致才会入库。而属性的存储数据类型，决定了在分析模型中可以选择的分析逻辑，所以报送数据的格式，需要考虑分析场景和业务需求，制定完整的埋点方案，并按埋点方案进行格式确定。

5.1.3、用户设置报文格式

用户设置操作的数据格式与事件上报的格式相似，不同之外在于：

• _type：事件上报需传 event ，而用户属性设置需传 userset
• _userset_type ：用户设置类的数据，_userset_type 为必传属性，没有 event_name 这个属性

[{
  "_appkey": "c7d6914e9f4b423c",
  "_type": "userset", //用户属性设置类数据上报
  "_userset_type": "userInit", //用户属性设置方式
  "_account_id": "aid25491084",
  "_visitor_id": "vid8709901241",
  "_ts": "1631790831000",
  "_idfa": "1e2dfa89-496a-47fd-9941-df1fc4e6484a",
  "_ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_3_1 like Mac OS X)",
  "properties": {
     "_platform":8,
    "regtime": "2021-03-01 12:34:56.789", //自定义属性
    "roleName": "dashen" //自定义属性
  }
}]

5.2、userInit

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

5.3、userUpdate

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

5.4、userAdd

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

5.5、userUnset

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

5.6、userAppend

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

5.7、userDelete

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

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

API 更新记录

2022-01-20

• API 对接文档初版