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 and SDK packages 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

     Entry: 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.

• When reporting data using the API, if you do not provide the value of _visitor_id, SolarEngine SDK will use _distinct_id as the visitor ID by default.
• If you have your own visitor ID system, you can assign values of your own.

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.

• When the event you report occurs after the login, you need to report the _account_id of the user.
• When the event occurs when users did not logged in or logged out, please leave _account_id blank.

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:

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

Debug address:

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

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

• 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 advertising and data callback, 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 the following three categories:

• Preset Events: This type of event is triggered by the SDK according to rules and has a fixed _event_name, such as install, startup and exit. When you access data through the API, you need to configure the triggering timing for these three preset events and report them to SolarEngine through the API. If preset events are not reported, analytics cannot be performed.
• Predefined Events: This type of event has clearly defined meanings in the SolarEngine system. They have a certain _event_name, and need to be reported by the developer when the corresponding event occurs, such as in-app ad impression, in-app purchase, etc.
• Custom Events: Events that developers can define by themselves and report after event tracking.

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 identification parameters 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.

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

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

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 its data passed for the first time, when the system will automatically recognize the format of the first reported data. Once determined, it cannot be modified.

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.

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 placed 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 installation.

    The _event_name of the installation event is:

• APP side: _appInstall
• Mini program/mini game: _mpInstall
• Web side: _webInstall

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:

• APP side: _appStart
• Mini program/mini game: _mpStart
• Web side: _webStart

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:

• APP side: _appEnd
• Mini program/mini game: _mpEnd
• Web end: _webEnd

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:

• APP: _appImp
• MiniPogram/MiniGame: _mpImp
• Web: _webImp

Properties that need to be reported for ad impression event:

(For the corresponding fields of each mediation platform, please refer to:  ROI Analysis—Third-Party Account Management—Mediation Platform—Others)

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:

• APP: _appClick
• MiniProgram/MiniGame: _mpClick
• Web: _webClick

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:

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:

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:

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:

• APP: _appAttr
• MiniProgram/MiniGame: _mpAttr
• Web: _webAttr

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 its data passed for the first time, when the system will automatically recognize the format of the first reported data. Once determined, it cannot be modified.

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:

• _type: Pass event for events; pass userset for userSet.
• _userset_type: A required property for user set data, not including event_name property.

[{
  "_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

• First version of API Integration Document