SolarEngine integration plan
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Real-time API | Callback | User level | ✅ | ✅ |
Before you start connecting SolarEngine data, make sure that you have read the AE system's user identification rules and understand how AE identifies a user through #distinct_id and #account_id
SolarEngine provides a real-time API export feature that supports sending back event data such as activations in real time. For details, see the SolarEngine official documentation
Integration process
- Integrate the SolarEngine SDK and the AE SDK, and pass in the distinct ID of the AE SDK through the SolarEngine SDK's API for setting super event properties
- Log in to the AE backend, go to the Third-party Integration module, add a SolarEngine integration, complete the related configuration, and copy the callback URL
- Log in to the SolarEngine backend and complete the data callback configuration
- Check whether the AE system receives the data successfully, and build reports
1. Client SDK configuration
1.1 Integrate the SolarEngine SDK and the AE SDK
First, integrate the SolarEngine SDK and the AE SDK into your app and complete the initialization configuration. The integration documentation for the SolarEngine SDK and the AE SDK is as follows:
1.2 Configure the SDK
After integrating the SDKs, set the distinct ID and account ID of the AE SDK in the SolarEngine SDK. We recommend using SolarEngine's API for setting super event properties
Note the order:
- Initialize the AE SDK
- Get the distinct ID of the AE SDK
- Call SolarEngine's API for setting super properties to set the distinct ID of the AE SDK as a super property of the SolarEngine SDK
- Initialize the SolarEngine SDK
- When the account ID of the AE SDK becomes available (that is, when the user logs in to an account or a character goes online), call the login API of the AE SDK, and call SolarEngine's API for setting super properties again to set the account ID as a super property of the SolarEngine SDK
The following is a code sample for Android:
// Initialize the AE SDK
TDAnalytics.init(context, APPID, SERVER_URL);
// Get the distinct ID of the AE SDK
String te_distinct_id = TDAnalytics.getDistinctId();
// Use the API for setting super event properties to set the AE distinct ID as a super property of the SolarEngine SDK
SolarEngineManager.getInstance().setSuperProperties(context, "te_distinct_id", te_distinct_id);
// Initialize the SolarEngine SDK
SolarEngineConfig config = new SolarEngineConfig.Builder().build();
SolarEngineManager.getInstance().initialize(context, "appkey applied for by the developer","userId applied for by the developer",config);
// .....
// After the user logs in
// Get the account ID
String te_account_id = "login_id";
// Call login in the TE SDK
TDAnalytics.login(te_account_id);
// Use the API for setting super event properties to set the AE account ID as a super property of the SolarEngine SDK
SolarEngineManager.getInstance().setSuperProperties(context,"te_account_id", te_account_id);
2. Plan configuration
After completing the SDK configuration, log in to the AE backend and complete the SolarEngine configuration in the Third-party Integration module. The image below shows the SolarEngine configuration page:
2.1 User identification fields
Because SolarEngine sends back user-level data, you need to set user identification rules for it. Based on this configuration, the AE system sets these fields as the user identification fields of the data when it converts the callback data.
If you configured the client SDK as described in the previous step of this document, use the following configuration:
- Field associated with the account ID: event_custom_params.te_account_id
- Field associated with the distinct ID: event_custom_params.te_distinct_id
2.2 Event Data Configuration
After you turn on the Event Data Configuration switch, the data sent back (including activation events and in-app events) is written to the event table
We recommend that you enable event data ingestion. Note, however, that by default, we receive all data sent back by SolarEngine. If too many event types are sent back, the event volume of the AE project can grow excessively. Therefore, when you set up callbacks on the SolarEngine platform, we recommend that you select only the necessary events.
2.3 User Properties Configuration
By default, the AE system automatically writes the attribution fields in the SolarEngine callback data to standardized user properties. The following are the fields written to user properties and their meanings:
| SolarEngine field | Standardized field | Description |
|---|---|---|
| channel_name | te_ads_object.media_source | Media source |
| adplan_name | te_ads_object.campaign_name | Campaign name |
| adgroup_name | te_ads_object.ad_group_name | Ad group name |
| adcreative_name | te_ads_object.ad_name | Ad name |
To make changes, click Configure Rules to go to the ingestion rule configuration page, as shown below
Here, you can change which events user properties come from. If you do not want user properties to be written frequently, turn off Include all events and change the source event name to install. With this configuration, the AE system extracts the fields to be written to user properties only from the install events sent back by SolarEngine. The default Integration method is user_setOnce, which means only the first reported information is kept.
To turn off user property ingestion, stop all rules:
2.4 Configuration
Finally, in the integration configuration module, you can control the details of data pulling, such as the event name after ingestion.
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_mapping | Event name after ingestion. Customizable. The key is the SolarEngine event name, and the value is the event name after ingestion. The default is the activation event: install |
2.5 End Point
End Point shows the URL where the AE system receives SolarEngine callback data.
Note that the endpoint URL includes the callback parameters for apps. If you want to send back mini program/mini game data, see the mini program/mini game callback parameters section
Copy this URL directly, and enter it when you configure the callback in the next step:
If no URL is displayed here, open Project Settings → Settings → Implementation from the menu in the upper-right corner and configure the URL for public network. This URL is the data reporting URL configured in the AE SDK. After configuring it, go back to End Point on the SolarEngine configuration page and copy the endpoint URL.
3. Complete the callback configuration in SolarEngine
3.1 Configure the callback link on the real-time API data export page of the SolarEngine backend
After creating the plan in the AE backend, log in to the SolarEngine backend, select the project whose data you want to send back, and select App Settings > Data Export > Real-time API Export in the Attribution module to configure SolarEngine real-time callbacks
Fill in the fields according to the following rules:
- For the callback type, select Activation
- For the callback URL, enter the callback URL you got in the AE backend
- For callback URL parsing, we recommend that you fill it in according to section 3.2
- For the callback method, select POST
- You can change the timeout and number of retries as needed. If you have no special requirements, use the default values
After completing the configuration, click Submit
3.2 SolarEngine callback parameters
The following are the parameters that SolarEngine callbacks support. When configuring, we recommend that the parameter names you enter match the selected values. You can get all the fields we recommend sending back from the table below. Make sure to send back the event_name, event_time, and event_custom_params fields; otherwise, data conversion may fail
3.2.1 App callback parameters
| Parameter name | Used by default | Value (example) | Description |
|---|---|---|---|
| event_type | Yes | Enum values: preset, custom | Whether it is a preset event |
| event_name | Yes | Event name: install, startup, etc... | Event name |
| attribution_time | Yes | 2023/7/1 22:47 | Attribution time |
| attribution_touch_type | Yes | click | Attribution touchpoint type |
| attribution_method | Yes | Enum values: deviceid fingerprint | Attribution method |
| attribution_lbw | 86400 | Attribution lookback window | |
| attribution_ttit | 68 | Attribution time difference | |
| channel_name | Yes | Mintegral | Name of the attributed channel |
| app_name | Yes | Cat EscapeInfinity | App name |
| appkey | Yes | appkey | |
| app_platform | Yes | ios | App platform |
| landing_page_url | https://apps.apple.com/us/app/cat-escape-infinity/id6445884698 | App landing page URL | |
| turl_id | Ev2Evya | Tracking link short link ID | |
| turl_string | Tracking link short link | ||
| turl_campaign_id | Yes | 7b35b6bd982780f729fcf4ff925b9c4e | Unique ID of the tracking link |
| turl_campaign_name | Yes | Cat Escape Infinity-IOS | Tracking link name |
| channel_id | Yes | 8221 | Channel ID of the tracking link |
| ry_touchpoint_ts | Yes | 1688222783854 | Touchpoint time |
| attribution_type | Yes | ua | Attribution type (fixed to UA acquisition) |
| account_id | Yes | Ad account ID | |
| adgroup_id | Yes | Ad group ID on the ad platform | |
| adgroup_name | Yes | CatEscapeInfinity_CN_FO_0404_WX_iOS_MTG_1 | Ad group name on the ad platform |
| adplan_id | Yes | ss_Duomm_CN_FO_0404_WX_iOS_MTG_1 | Campaign ID on the ad platform |
| adplan_name | Yes | Campaign name on the ad platform | |
| adcreative_id | Yes | 1804913040 | Ad creative ID on the ad platform |
| adcreative_name | Yes | wadmm_21186_0_V_1203_mtg_nndb_cn_1024x768_cy.mp4 | Ad creative name on the ad platform |
| adcreative_type | Yes | Ad creative type on the ad platform | |
| site_id | Yes | mtg1183741824 | Sub-channel ID on the ad platform |
| site_name | Yes | Sub-channel name on the ad platform | |
| ad_type | Yes | Ad type on the ad platform | |
| placement_id | Yes | Ad placement ID on the ad platform | |
| conversion_id | Unique ID of the conversion received by the ad platform | ||
| click_id | mtg64a03bfe52979a0001a8cb4y | Unique click ID on the ad platform | |
| impression_id | Unique impression ID on the ad platform | ||
| request_id | 7434D04B787321D534C7268DD8D4D52E | Unique request ID on the ad platform | |
| callback_id | Unique callback ID on the ad platform | ||
| callback_url | Callback URL of the ad platform | ||
| custom_params_1 | Custom parameter data 1-10 of the ad platform | ||
| custom_params_2 | Custom parameter data 1-10 of the ad platform | ||
| custom_params_3 | Custom parameter data 1-10 of the ad platform | ||
| custom_params_4 | Custom parameter data 1-10 of the ad platform | ||
| custom_params_5 | Custom parameter data 1-10 of the ad platform | ||
| custom_params_6 | Custom parameter data 1-10 of the ad platform | ||
| custom_params_7 | Custom parameter data 1-10 of the ad platform | ||
| custom_params_8 | Custom parameter data 1-10 of the ad platform | ||
| custom_params_9 | Custom parameter data 1-10 of the ad platform | ||
| custom_params_10 | Custom parameter data 1-10 of the ad platform | ||
| device_id | Yes | B9BBB98D-FFEE-448D-A9BE-52883FF230FD | Unique ID of the attributed device |
| device_id_type | Yes | distinct_id | distinct_id |
| device_id_md5_type | distinct_id_md5 | distinct_id_md5 | |
| device_id_md5 | 55a6187afabbe2ed4c6e9bc0fdca423d | MD5 of the unique ID of the attributed device | |
| gaid | gaid | ||
| gaid_md5 | gaid_md5 | ||
| imei1 | imei1 | ||
| imei1_md5 | imei1_md5 | ||
| imei2 | imei2 | ||
| imei2_md5 | imei2_md5 | ||
| oaid | oaid | ||
| oaid_md5 | oaid_md5 | ||
| mac | mac | ||
| mac_md5 | mac_md5 | ||
| android_id | android_id | ||
| android_id_md5 | android_id_md5 | ||
| idfa | 49BB9C2F-E0DB-46B8-9C68-21C4C7FB30CC | idfa | |
| idfa_md5 | 1225a829ea48f2fc62a2d3faee263829 | idfa_md5 | |
| idfv | B9BBB98D-FFEE-448D-A9BE-52883FF230FD | idfv | |
| idfv_md5 | 55a6187afabbe2ed4c6e9bc0fdca423d | idfv_md5 | |
| ipv4 | 110.154.208.22 | ipv4 | |
| ipv6 | ipv6 | ||
| ua | Yes | Mozilla/5.0 (iPad; CPU OS 14_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 | ua |
| manufacturer | Yes | apple | Brand |
| model | Yes | iPad11,6 | Device model |
| os | Yes | Enum values 1: Android 2: iOS | OS |
| os_version | Yes | 14.2 | Version |
| ua_device_type | iPad | Device type parsed from the UA | |
| ua_os | IOS | OS parsed from the UA | |
| ua_osv | 14.2 | OS version parsed from the UA | |
| language | Yes | zh-Hans-CN | Language |
| country | Yes | CN | Country |
| city | Yes | City | |
| att_status | Enum values: denied, restricted, authorized, unknown, empty | ||
| lat_status | Enum values: enable, disable, unknown, empty | ||
| network_type | Yes | Enum values: 0: no network 1: unknown 2: 2G 3: 3G 4: 4G 5: 5G 6: 6G or next-generation network 9: WIFI | Network status when the data was uploaded |
| carrier | Yes | Carrier | |
| install_time | 1688222848242 | Activation time | |
| event_time | Yes | 1689781058000 | Time when the server received the event |
| channel_package_name | default | Channel package name | |
| app_version | Yes | 1.0.2 | App version |
| bundleid | Yes | jp.os.catescape | app bundle id |
| event_data | Yes | ||
| collector_version | 1.1.8.0 | SDK version | |
| integration_type | Enum values: sdk api s2s | Integration method | |
| event_custom_params | Yes | Customer's custom event property content | |
| caid | caid value of the event | ||
| caid_md5 | MD5 of the event's caid | ||
| event_account_id | account_id of the event |
3.2.2 Mini program/mini game callback parameters
If you are connecting a mini program or mini game, use the following callback URL. Replace {receiver-host} with the reporting URL, and replace {app-id} below with the project's APP ID:
https://{receiver-host}/attribution/callback/solarengine/{app-id}?appkey=appkey&app_name=app_name&app_platform=app_platform&app_type=app_type&event_name=event_name&country=country¤t_event_time=current_event_time&channel_name=channel_name&os=os&os_version=os_version&brand=brand&model=model&ua=ua&user_id=user_id&account_id=account_id&adgroup_id=adgroup_id&adgroup_name=adgroup_name&adplan_id=adplan_id&adplan_name=adplan_name&adcreative_id=adcreative_id&adcreative_name=adcreative_name&adcreative_type=adcreative_type&scene_id=scene_id&custom_params=custom_params&ad_platform=ad_platform&ad_type=ad_type&ad_appid=ad_appid&ad_id=ad_id&mediation_platform=mediation_platform&ad_ecpm=ad_ecpm&order_id=order_id&order_amount=order_amount¤cy_type=currency_type&purchase_type=purchase_type&product_id=product_id&product_name=product_name&product_num=product_num®ister_type=register_type&login_type=login_type
Common event fields for mini programs/mini games:
| Field name | Recommended | Value (example) | Description |
|---|---|---|---|
| appkey | Yes | 9b716df699b77694 | Unique identifier of the app created in the SE backend |
| app_name | Yes | App name | App name |
| app_platform | Yes | miniprogram | Operating system: miniprogram or minigame |
| app_type | Yes | Platform type: wechat, douyin | |
| event_name | Yes | startup | Event name. Fixed values: install (activation), startup (launch), register (registration), login (login), order (order), purchase (payment), adimpression (ad impression)... |
| country | Yes | CHN | Country |
| install_time | 1637823377000 | Install time | |
| current_event_time | Yes | 1637823377000 | Time when the current event occurred |
| report_time | 1637823377000 | Time when the server received the event | |
| integration_type | sdk | Integration method. Fixed to sdk | |
| collector_version | 1.8.0 | Collector version | |
| attribution_method | path | Attribution method: path attribution (path), click attribution (click) | |
| channel_id | 8221 | Channel ID | |
| channel_name | Yes | tiktok | Channel Name |
| turl_campaign_id | 871bbfa4560283c5a0ca00483c529c63 | Tracking link ID | |
| turl_campaign_name | Tracking link name_Mintegral | Tracking link name | |
| openid | oUFfk5coGBwScTmIsr008qL93ANk | Unique user ID within the current mini program | |
| anonymous_openid | Douyin only. Unique ID of the anonymous user within the current mini program | ||
| unionid | f7510d9ab*********** | Unique user ID across different mini programs of the same developer | |
| device_id | oUFfk5UyO--kSbPVEuC5zWtqYvbs | Device ID | |
| device_id_type | openid | Device ID type | |
| container_name | toutiao | Host app name. Douyin only | |
| os | Yes | android | OS platform of the host app |
| os_version | Yes | 10 | OS version of the host app |
| brand | Yes | HUAWEI | Device manufacturer of the host app |
| model | Yes | Mate 40 | Device model of the host app |
| language | zh-han | Device language of the host app | |
| ipv4 | 1.1.1.1 | User's public IPv4 address | |
| ua | Yes | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36 | UA |
| user_id | Yes | Account ID (user ID) | |
| account_id | Yes | Ad account ID | |
| adgroup_id | Yes | Ad group ID | |
| adgroup_name | Yes | Ad group name | |
| adplan_id | Yes | Campaign ID | |
| adplan_name | Yes | Campaign name | |
| adcreative_id | Yes | Ad creative ID | |
| adcreative_name | Yes | Ad creative name | |
| adcreative_type | Yes | Creative type (such as large image, small image, or video) | |
| material_1 | Material ID_1 | ||
| material_2 | Material ID_2 | ||
| material_3 | Material ID_3 | ||
| material_4 | Material ID_4 | ||
| material_5 | Material ID_5 | ||
| material_6 | Material ID_6 | ||
| click_id | Ad click ID | ||
| impression_id | Ad impression ID | ||
| request_id | Ad request ID | ||
| callback_id | Channel callback ID | ||
| callback_url | Channel callback URL | ||
| site_id | Traffic media ID (such as Ocean Engine's Toutiao, Pangle, and Douyin). | ||
| site_name | Traffic media name (such as Ocean Engine's Toutiao, Pangle, and Douyin). | ||
| scene_id | Yes | 1 | Scene value |
| path | index/xxx | Launch page path of the mini program | |
| query_info | { "channel_id": "234234", "turl_id": "234234", ...} | Query information obtained from the mini program platform: SE parameters + parameters appended by the channel | |
| custom_params | Yes | { "add_cart": "234234", //custom parameters. "sku": "234234", "level_up": "234234" ... } | /Nested custom event parameters, with up to 10 parameters. |
Event-specific fields for mini programs/mini games:
| Event | Field name | Recommended | Description |
|---|---|---|---|
| adimpression | ad_platform | Yes | Monetization platform |
| ad_type | Yes | Type of the displayed ad | |
| ad_appid | Yes | App ID on the monetization platform | |
| ad_id | Yes | Monetization ad unit ID on the monetization platform | |
| mediation_platform | Yes | Mediation platform identifier. If there is no mediation platform identifier, set it to "custom" | |
| ad_ecpm | Yes | Ad eCPM (monetization revenue per 1,000 ad impressions; 0 or a negative value means it was not passed), unit: CNY | |
| is_rendered | Whether the ad was rendered successfully. Enum values: YES: succeeded NO: failed If you do not need this metric, pass YES | ||
| adclick | ad_platform | Yes | Monetization platform |
| ad_type | Yes | Type of the displayed ad | |
| ad_id | Yes | Monetization ad unit ID on the monetization platform | |
| mediation_platform | Yes | Mediation platform identifier. If there is no mediation platform identifier, set it to "custom" | |
| purchase | order_id | Yes | Order ID |
| order_amount | Yes | Amount paid for this purchase | |
| currency_type | Yes | Payment currency type, following the ISO 4217 international standard, such as CNY and USD | |
| purchase_type | Yes | Payment method, such as alipay, weixin, applepay, and paypal | |
| product_id | Yes | ID of the purchased product | |
| product_name | Yes | Product name | |
| product_num | Yes | Quantity of products purchased | |
| order | order_id | Yes | Order ID |
| order_amount | Yes | Order amount, unit: CNY | |
| currency_type | Yes | Currency type of the displayed revenue, following the ISO 4217 international standard, such as CNY and USD | |
| purchase_type | Yes | Payment method, such as alipay, weixin, applepay, and paypal | |
| register | register_type | Yes | Registration type, a custom value such as "WeChat" or "QQ" |
| login | login_type | Yes | Login type, a custom value such as "WeChat" or "QQ" |
4. Data ingestion
4.1 Data ingestion rules
By default, we write the pulled data to the AE project as events according to the following rules:
- The event_time field in the data is used as the event's data time #event_time
- The event_name in the data is used as the event name of the data
- All other fields are ingested
4.2 Standardized fields
| Original field | Standardized field | Description |
|---|---|---|
| account_id | te_ads_object.ad_account_id | Ad account ID |
| adplan_name | te_ads_object.campaign_name | Campaign name |
| adplan_id | te_ads_object.campaign_id | Campaign ID |
| adgroup_name | te_ads_object.ad_group_name | Ad group name, or the Unit name for monetization ads |
| adgroup_id | te_ads_object.ad_group_id | Ad group ID, or the Unit ID for monetization ads |
| adcreative_name | te_ads_object.ad_name | Ad name |
| adcreative_id | te_ads_object.ad_id | Ad ID |
| placement_id | te_ads_object.placement | Ad placement |
| channel_name | te_ads_object.media_source | Media source or monetization channel |
| bundleid | te_ads_object.app_id | App ID |
| app_name | te_ads_object.app_name | App name |
| app_platform | te_ads_object.platform | Platform, such as Android or iOS |
| country | te_ads_object.country | Country or region code |