1. SDK Basic Information

SolarEngine (SE) is an all-in-one mobile app growth analytics and publishing intelligent decision-making platform. It supports data management across global channels, assisting developers to monitor every stage of business development. With our attribution tracking and user-granular ROI analysis, you'll be able to measure the true value every channel creates and optimize future growth strategies. SE also offers various analysis models and A/B testing feature to help fully visualize the user journey, identify potential pain points, implement targeted product enhancements and ultimately drive large-scale app growth.

This documentation provides instructions for data reporting through API.

Privacy Policy: https://www.solar-engine.com/privacyPolicyEN.html

2. Before you start

Before you start, there are some parameters required. Follow the directions below to get prepared.

Step 1: Get User Code

Log in to your admin account, and find the User Code under Account Management --> Account Profile.

 

Step 2: Get AppKey

Access Path:  Asset Management - App Management - AppKey

 

Step 3: Identify Users

As the central focus of the analysis process, users play a critical role, and accurately identifying users is key to obtaining precise analytical results. To help you better understand the user system of SolarEngine and ensure correct setup and identification, the following provides an explanation.

Device ID

A unique device identifier generated by SDK, with the attribute name "_distinct_id". It must be reported when event tracking.

Android: It is recommended to report the Android ID as _distinct_id. If the Android ID cannot be obtained, obtain a random UUID + a 13-digit timestamp of the current time as _distinct_id.

iOS: It is recommended to report the IDFV as _distinct_id. If the IDFV cannot be obtained, obtain a random UUID + a 13-digit timestamp of the current time as _distinct_id.

Visitor ID

The visitor ID refers to the user's unique identification generated before login or registration, with the attribute name "_visitor_id".

Most hyper casual games or utility tool apps do not have a user registration and login system. In this case, the visitor ID will be the most important ID to identify users.

Account ID

The account ID is usually generated after users login or register within the app, with the attribute name "_account_id". Account IDs can be used to identify users across devices and platforms.

Note:

When identifying users in SolarEngine, the account ID will be used for priority. When the account ID is empty, the visitor ID will be used for identification.

3. Data Reporting

3.1 Reporting Method

Data reporting address:

Non-China-Mainland: https://vg-api-receiver.detailroi.com/datareceiver/receive/v3/sapi

China Mainland: https://api-receiver.detailroi.com/datareceiver/receive/v3/sapi

Debug address:

• Replace the official address path after ".com" with "datareceiver/receive/sapiDebug".

The debug address provides detailed error information. Please switch to the official address after debugging.

• For private deployment, please contact our operations team for data reporting address.
• Please use the UTF-8 encoded format, and request through POST.
• Parameters required for Android devices do not need to be reported by iOS devices, and vice versa. Preset property names should be consistent with that in the documentation.
• Content-Type=application/json must be included in the headers.

3.2 Report Data Signature

3.2.1. Token Validity

Request parameters:

timestamp, sign

Verification rules:

1. Timestamp is valid within 30 minutes.

2. Signature verification

sign = Md5(appkey+timestamp)

Note:

appkey: The app ID in the SolarEngine portal, also known as the Appkey.

Demo:

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

appKey:"f499a4bdc9097b12"
timestamp:1648702202000
String before md5："f499a4bdc9097b121648702202000"
Sign after md5：18c55727422f35e66a8765c1f4e5e546

3.2.2. API Demo

 If you need to enable Google Ads attribution and data postback, please ensure to report the _app_version and _os_version properties, otherwise Google will reject the data.

https://localhost:8008/datareceiver/receive/v2/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,//Send 1 for China Mainland product, otherwise send 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. Event Reporting

 SolarEngine events are mainly divided into three categories:

4.1. Event Properties & Reporting Format

4.1.1. General Event Properties

The following are the parameters owned by all events, among which the device IDs are used for data integration and calculation of revenue, cost, ROI and other metrics. Therefore, please pass device related parameters as complete as possible.

Some predefined events will also contain parameters unique to the event, which will be listed in the corresponding event description.

If you launch apps on OPPO, VIVO, Huawei, and Xiaomi, _oaid is a mandatory attribute required by the UA networks. If _oaid cannot be obtained, please provide _distinct_id instead.

Property Name	Description	Example	Data Type	Required

_appkey	16-digit AppKey in SolarEngine	546279e4b8514d56	String	YES
_event_name	Event Identification	_appInstall	String	YES (Limit 40 characters, contain only letters, numbers, underscores, but no blanks)
_source_type	Data Source (send api if reported through API)	api	String	YES
_type	Data Type (send event for events)	event	String	YES
_distinct_id	Device ID iOS: IDFV Android: Android ID Web: cookie_id (generated by combining the current timestamp+screen height/width+uuid+UA after MD5) MiniProgram/MiniGame: openid>uuid (defined by WeChat); openid>anonymouopenid>uuid Last Choice: uuid + 13-digit timestamp of current time	3e4416a9d42f4566	String	YES
_distinct_id_type	Mini Program/Mini Game: When _distinct_id is openid, pass 1101. When _distinct_id is anonymousopenid, pass 1102. When _distinct_id is other ID, pass 1103. Web: When _distinct_id is default, pass 1101. When _distinct_id takes the last choice ID, pass 1102. When _distinct_id is other ID, pass 1103.		number	Required if Mini Program/Mini Game/Web
_account_id	Account ID	aid25491084	String	Yes if no visitor ID. Limit 128 characters.
_visitor_id	Visitor ID	vid8709901241	String	Yes if no account ID. Limit 128 characters.
_session_id	Session ID, used to identify from app open to exit.	3e4a4f9d2258cc41ee86dd09132bc61c	String	No
_event_id	To identify data uniqueness, used for data deduplication.	56e3704cf535e5e6dccdc421e37b201e	String	No
_ts	13-digit timestamp when the data was generated.	1631790831000	String	Yes
_idfa	IDFA for iOS devices	1e2dfa89-496a-47fd-9941-df1fc4e6484a	String	No, but recommended for iOS devices.
_idfv	IDFV for iOS devices	599f9c00-92dc-4b5c-9464-7971f01f8370	String	No, but recommended for iOS devices. 【Required by China Mainland Self-Attributing Networks】
_uuid	UUID generated by Android through system API	99ae3a5b-750c-4f5f-aeb9-f128ab8a0ea0	String	No, but recommended for Android devices.
_package_type	Data storage region in China Mainland: 1   Data storage region outside China Mainland: 2	1 or 2	Number	Yes
_imei	IMEI for Android devices	861886043826831	String	No, but recommended for Android devices.
_imei2	IMEI for Android devices	861886043826849	String	No, but recommended for Android devices.
_gaid	GAID for Android devices	bd4b382b-2eeb-4aea-90c4-02b7f28a04b3	String	No, but recommended for Android devices.
_oaid	OAID for Android devices	fdebebfd-c64f-e6c5-7eea-b7f73da79380	String	No, but recommended for Android devices.
_android_id	Android ID for Android devices	55ae62239e982d88	String	No, but recommended for Android devices. 【Required by China Mainland Self-Attributing Networks】
_unionid	Unique user ID across multiple mini programs by the same developer		String	No
_ua	Device UA	Mozilla/5.0 (iPhone; CPU iPhone OS 13_3_1 like Mac OS X)	String	Yes
_ip	Device IP	1.119.175.47	String	Yes
_ipv6	Device IPv6	2001:0db8:3c4d:0012:0000:0000:0a8b:2a2b	String	No
properties	The following properties must be reported nested under "properties".
_caid	CAID for the iOS system	[{"version":"20220111","caid":"912ec803b2ce498d495ab570"},{"version":"20211207","caid":"e332a76c2b31ced090c7"}]	String	No
_openid	The unique user ID within the current mini program		String	No
_anonymous_openid	Exclusive to Douyin: The unique anonymous user ID within the current mini program		String	No
_country	Country where the user is located. Generated based on IP address if not sent.	China		No
_province	Province where the user is located. Generated based on IP address if not sent.	Hebei	String	No
_city	City where the user is located. Generated based on IP address if not sent.	Shijiazhuang	String	No
_language	Device Language	zh-han	String	No
_time_zone	Device Timezone	GMT+08:00	String	No
_manufacturer	Device Manufacturer	Apple	String	No
_platform	Operating Platform, e.g. 0：Other 1：Android 2：iOS 3：Windows 4：Mac 8：devtools 11：HarmonyOS 12：Linux	2	number	Yes
_mp_type	Mini Program type: wechat douyin kwai bilibili	wechat	string	Yes for minigame and miniprogram.
_app_platform	App Platform: web\android\ios\miniprogram\minigame	miniprogram	string	Yes for minigame and miniprogram.
_os_version	For the most granular system version number, such as iOS 14.3.1 or Android 10.0.0, it is important to report this attribute if you need to enable Google delivery and configure data callbacks. Otherwise, Google may reject the data.	14.3.1	string	Yes for iOS attribution
_resolution	Device Resolution	1080*1920	string	No
_screen_height	Device Screen Height	1920	number	No
_screen_width	Device Screen Width	1080	number	No
_density	Pixel Density	480	number	No
_device_model	Device Model	iPhone 9,1	string	Yes for iOS attribution
_device_name	Device Name after MD5	867E57BD062C7169995DC03CC0541C19	string	No
_device_type	Device Type, e.g. 0：Other 1：Android Phone 2：Android Pad 3：iPhone 4：iPad 5：Mac 6：PC 8：tv 9：Harmony Phone 10：Harmony Pad	3	number	No
_network_type	Network Type, e.g. 0：No Internet connection 1：unknown 2：2G 3：3G 4：4G 5：5G 6：6G or above 9：WIFI 10：bluetooth（Quick app） 11：others（Quick app）	4	number	No
_carrier	Network Carrier	cmcc	string	No
_app_version	App Version If you're advertising on Google Ads and have enabled data postbacks to it, this property must be reported, otherwise Google will reject the data.	1.0.10.404	string	No
_app_version_code	Build Number	819	string	No
_package_name	Package Name	com.aike.dashenguilai.ad	string	Yes
_app_name	App Name	wechat	string	No
_channel	App Distribution Platform	头条	string	No
_lib	Integrated SDK type: 0:  Other 1:  Android 2：iOS 3：Js 4：Mini program 5：Mini game 6：Quick app 9：Harmony 10：Quick game 11：Mac 12：Windows 13：Linux	2	number	No
_lib_version	Integrated SDK version	1.6.6	string	No
_duration	Event Duration (Unit: millisecond) The timeEvent functions needs to be called to record the duration.	71	number	No
_is_first_day	Whether triggered on the first day of installation. True: yes False: no	true	boolean	Yes for _appInstall event.
_is_first_time	Whether triggered for the first time. True: yes False: no	true	boolean	Yes for _appInstall event.
_browser	The type of browser being used, such as Chrome, Firefox, etc.	Chrome	String	No
_browser_version	The version of the browser being used, such as Chrome 61.0, Firefox 57.0, etc.	Chrome 61.0	String	No
_page_title	Title of the current page Android: The value of android:label in Activity. iOS: The text of the title or titleView in ViewController.	Adding cart	String	No
_page_name	Name of the current page Android: The name corresponding to Activity or Fragment. iOS: The name of ViewController.	com.aike.dashenguilai.android.cart	String	No
_referrer_title	Title of the previous page	Homepage	String	No
_referrer_name	Name of the previous page	com.aike.dashenguilai.android.index	String	No
_ad_personalization_enabled	Whether the user allows Google to use their data for personalized ads	true/false	boolean	No
_ad_user_data_enabled	Whether the user consents to send their data to Google	true/false	boolean	No
_adservices_token	Request the ASA token from Apple		String	No

4.1.2. Custom Event Properties

Event property is a JSON object, and each key-value represents a property.

All custom properties must be reported nested under "properties".

key is the name of the property

value is the value of the property

Property type for custom properties

The data type of a custom property is determined by the system when it is first reported and cannot be modified later.

Data Type	Description	Example

number	Range from -9E15 to 9E15, without quotation marks.	1234, 12.34
string	Limit 2KB. Numbers with quotation marks will also be identified as strings.	"dashen", "北京", "1234", "true"
date	"yyyy-MM-dd HH:mm:ss.SSS", "yyyy-MM-dd HH:mm:ss", or "yyyy-MM-dd 00:00:00"	"2023-03-01 12:34:56","2023-03-01 12:34:56.789","2023-03-01 00:00:00"
boolean	True or false without quotation marks.	true, false
array	All elements in an array will be converted into strings.	["a","1","true"]

Note: 

The data type of the property determines its calculation logic available in the analysis model. For example, the numerical type can perform calculations such as maximum value, minimum value, and summation, while the Boolean type can perform calculations of true numbers and false numbers. Therefore, before submitting the data, please consider the analysis scenarios and your business needs, formulate a complete event tracking plan, and determine the format according to the plan.

4.1.3. Event Reporting Format

Taking custom events as an example, the following is a request example.

 If you need to enable Google advertising and data postback, please be sure to report the _app_version and _os_version properties, otherwise Google will reject the data.

[{
  "_appkey": "c7d6914e9f4b423c",
  "_source_type": "api",
  "_type": "event", //event data reporting
  "_event_name": "addCart", //custom event identification
  "_account_id": "aid25491084",
  "_package_type":2, //Send 1 for China Mainland products, 2 for Non-China-Mainland products
  "_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", //Custom properties
    "roleName": "dashen", //Custom properties
    "_log_count": 25,
    "_platform": 1,
    "_package_name": "com.xxx.xxx.xxx"
  }
}]

Note:

As shown in the example, _ipv6 and parameters above it in the field table should be placed in the outer layer of properties for reporting, and all other fields should be nested in the inner layer for reporting.

Return example:

Success {"status":0}

4.2. Preset events

4.2.1. App Install

 This event is sent every time the app is opened for the first time after install.

The _event_name of the install event is:

4.2.2. App Start

It is recommended to report this event when an iOS device is opened or switches back to the foreground from the background, and when an Android device is opened or enters the foreground after 30 seconds in the background.

The _event_name of the event is:

4.2.3. App End

It is recommended to report this event when an iOS application exits to the background, and when the Android application exits or exits to the background for more than 30 seconds.

The _event_name of the exit event is:

4.3. Predefined Events

4.3.1. Ad Impression

Automatically reported when displaying ads within the app, which is essential for ROI analysis and monetization-related metrics in user analysis.

Please pass the "_event_name" of ad impression as follows:

Properties that need to be reported for ad impression event:

(For the corresponding fields of each mediation platform, please refer to: 

https://help.solar-engine.com/en/docs/Impression-level-revenue-integration

Parameter Name	Parameter Meaning	Example	Parameter Type	Mandatory

4.3.2. Ad Click

The ad click event is reported when in-app ads are clicked.

Please pass the "_event_name" of the ad click event as follows:

Properties that need to be reported for ad click event:

4.3.3. In-App Purchase

Automatically reported when in-app purchase is made. Please make sure to report this event if you need to analyze IAP revenue or use the prediction service in SolarEngine later.

Please pass the "_event_name" of the in-app purchase event as follows:

• APP: _appPur

• MiniProgram/MiniGame: _mpPur

• Web: _webPur

Properties that need to be reported for in-app purchase event:

Parameter Name	Parameter Meaning	Example	Parameter Type	Mandatory

_order_id	The order ID generated by the system for this purchase	2021111918032157001921	String	no
_pay_amount	The amount paid for this purchase (Unit: yuan)	128.00	number	yes
_currency_type	The currency type of payment (following ISO 4217)	CNY	String	yes
_pay_type	Payment methods, such as alipay, weixin, applepay, paypal, etc.	alipay	String	no
_product_id	Purchased item ID	1700923511	String	no
_product_name	Purchased item name	Package 1	String	no
_product_num	Quantity of items purchased	1	number	no
_pay_status	Payment status 1: successful 2: failed	1	number	yes
_fail_reason	Reason for payment failure	BANK_ERROR	String	no

Code Example

[
    {
        "_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. In-App Order

Automatically reported when in-app order is placed.

Please pass the "_event_name" of the in-app order event as follows:

• APP: _appOrder

• MiniProgram/MiniGame: _mpOrder

• Web: _webOrder

Properties that need to be reported for in-app order event:

Parameter Name	Parameter Meaning	Example	Parameter Type	Mandatory

4.3.5. Registration

Automatically reported when a user registers.

Please pass the "_event_name" of the registration event as follows:

• APP: _appReg

• MiniProgram/MiniGame: _mpReg

• Web: _webReg

Properties that need to be reported for registration event:

Parameter Name	Parameter Meaning	Example	Parameter Type	Mandatory

4.3.6. Login

Automatically reported when a user logs in.

Please pass the "_event_name" of the login event as follows:

• APP: _appLogin

• MiniProgram/MiniGame: _mpLogin

• Web: _webLogin

Properties that need to be reported for login event:

4.3.7. Self-Reported Attribution Results

Developers can customize the triggering timing of the event.

Please pass the "_event_name" of the event as follows:

4.4. Custom events

In addition to the predefined events listed above, developers can report custom events according to their own analysis needs.

The _event_name of custom events can be customized by the developer.

Here are the naming conventions for event names:

• String type
• Start with letters only.
• No more than 40 characters.
• Contain numbers, lowercase letters and underscores only

5. Set User Property

SolarEngine provides multiple methods for reporting user properties. You can use these methods to add or modify user properties.

It is recommended for you to select properties that change infrequently or hold significant value, for example, age, game level, location, first payment time and total payment amount. Other properties with higher change frequency can be reported and recorded through events.

User property settings can be set by calling userUpdate, userInit, userAdd, userUnset, userAppend, or userDelete.

Note:

The format requirements of user properties are consistent with those of event properties.

5.1. userSet Property & Reporting Format

5.1.1. General userSet Properties

Please ensure to report _account_id and _visitor_id completely, as they are required to identify users.

5.1.2. Custom userSet Properties

An event property is a JSON object, and each key-value represents a property.

All custom properties must be reported nested under properties.

key is the name of the property

• String type
• Can only start with a letter, not an underscore
• Contains numbers, lowercase letters and underscore "_"
• Maximum 40 characters

value is the value of the property

• Data Type: String, int, long, float, double, boolean, date, array, etc.
• For array elements, only string types are supported.
• All other types will be forced to be converted to string type.

Property type for custom properties

The data type of a custom property is determined by the system when it is first reported and cannot be modified later.

Note:

The data type of the property determines its calculation logic that can be selected in the analysis model. For example, the numerical type can perform calculations such as maximum value, minimum value, and summation, while the Boolean type can perform calculations of true numbers and false numbers. Therefore, before submitting the data, please consider the analysis scenarios and your business needs, formulate a complete event tracking plan, and determine the format according to the plan.

5.1.3. userSet Reporting Format

The reporting format of userSet is similar to the event reporting format, except that:

[{
  "_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": {
    "regtime": "2021-03-01 12:34:56.789", //custom property
    "roleName": "dashen" //custom property
  }
}]

5.2. userInit

If you want to upload a batch of user attributes, among which the existing user attributes will not update their values, and the non-existing attributes will be created and saved, you can call userInit to set them.

5.3. userUpdate

For general user attributes, you can call userUpdate to set them. The attributes uploaded in this way will overwrite the original attribute values. If the user attribute does not exist before, it will be created, and the data type will follow the value passed in.

5.4. userAdd

If you want to report a numeric attribute and accumulate its values, you can call userAdd. If the attribute has not been set, it will be assigned a value of 0 and then calculated. You can pass in a negative value, which is equivalent to a subtraction operation.

5.5. userUnset

When you want to clear the user attribute values of a user, you can call userUnset to clear the specified attributes (string array). If the attribute has not been created in the array, the attribute will not be created.

5.6. userAppend

You can call userAppend to append user attributes of array type. If the attribute does not exist, it will be created.

5.7. userDelete

You can call userDelete to delete users. After a user is deleted, you will no longer be able to query the user's user attributes, but the events generated by the user can still be queried.

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

API Update Log

2022-01-20