User

Broadly speaking, a user refers to each unique individual who interacts with the product. Regardless of the number of devices they use or switch between, they are treated as a single user and identified with a unique cross-device and cross-platform ID: account ID. The account ID requires registration or login to be generated.

Narrowly speaking, a user refers to each unique device that accesses the product. Even if multiple individuals use the same device or an individual uses multiple devices, each device is counted as a separate user and identified with a unique device-centered ID: visitor ID.

However, in real life, a user might have a visitor ID after install and register for an account ID later. Therefore, we still need another ID to connect the user's behavior before and after registration. This ID is referred to as the user ID in the SolarEngine system.

In short, the user ID is to link the user's entire lifecycle and serves as a cross-platform identification ID. As it involves cross-platform recognition, in the user ID genration rules, the account ID takes precedence over the visitor ID in terms of priority.

User Identification

SolarEngine uses device ID, user ID, account ID and visitor ID to identify users.

Device ID: A unique device identifier generated by SDK, with the attribute name "_distinct_id".
User ID: A unique user identifier generated based on user identification rules (see below), with the attribute name "_user_id".
Account ID: Reported by the developer, with the attribute name "_account_id".
Visitor ID: Reported by the developer, with the attribute name "_visitor_id". If not provided, it takes the value of "_distinct_id".

Identification Rules

Basic Rules:

A single user ID can only be bound to 1 account ID and 1 visitor ID.
The binding priority is given to account ID over visitor ID.
One account ID can only be bound to 1 user ID.
One visitor ID can only be bound to 1 user ID.

Detailed Description:

When only an account ID is present,

If the account ID is already bound to a user ID, the data belongs to the bound user ID.
If the account ID is not bound to an existing user ID, a new user ID is created and bound.

When only a visitor ID is present,

If the visitor ID is already bound to a user ID, the data belongs to the bound user ID.
If the visitor ID is not bound to an existing user ID, a new user ID is created and bound.

When both an account ID and a visitor ID are present, and the account ID is already bound to a user ID, the data belongs to the bound user ID. Then check the binding status of the visitor ID:

If the visitor ID is already bound to a user ID, the binding status remains unchanged.
If the visitor ID is not bound to any user ID, the following check is performed:

If the account ID is already bound to another visitor ID, the visitor ID is not bound to any user ID.
If the account ID is not bound to any visitor ID, the visitor ID is bound to the user ID that the account ID is bound to.

When both an account ID and a visitor ID are present, and the account ID is not bound to an existing user ID, the binding status of the visitor ID is checked:

If the visitor ID is bound to a user ID and the bound user ID is already associated with an account ID, a new user ID is created and bound to the current account ID.
If the visitor ID is bound to a user ID but the bound user ID is not associated with an account ID, the current account ID is bound to the user ID.
If the visitor ID is not bound to any user ID, a new user ID is created, and the current account ID, along with the visitor ID, is bound to the newly created user ID.

User Properties

User IDs can only be used to count the number of users but cannot meet more in-depth user analysis requirements. Therefore, SolarEngine provides the concept of user properties, allowing our clients to report user-related properties and utilize them within SolarEngine user analysis models to gain further insights into user behavior.

It is recommended to select properties that change infrequently or hold significant value, such as first payment time and total payment amount. Other properties with higher change frequency can be reported and recorded through events.

User properties are divided into preset user properties and custom user properties.

Preset User Properties

Here are the user properties collected by default.

Field Name	Description	Example	Data Type
_tenant_id	The Tenant ID to which the AppKey belongs.	157	string
_prokey	The Product ID to which the AppKey belongs.	546279e4b8514d56	string
_user_id	User IDs generated based on SE user identification rules.	90901129412	int
_account_id	Account IDs reported by the developer.	aid25491084	string
_visitor_id	Visitor IDs reported by the developer.	vid8709901241	string
_active_time	App activation time = The "_ts" in the user's first data record.	2023/9/16 19:13	date
_reg_time	The "_ts" in the user's first Account ID-included data record.	2023/9/16 19:13	date
_update_time	The "_ts" in the user's last data record.	2023/9/16 19:13	date
_user_operation	The "_userset_type" in the user's last data record.	init	string
_server_time	The time when the server receives the user's last data record.	2023/9/16 19:13	date

Custom User Properties

In addition to preset ones, you can also customize user properties based on your analysis requirements. It is recommended to synchronize these properties in the event tracking plan to enbale information sharing among all team members.

Data Reporting Format Table

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"
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"]

Device

Many of our clients do not enforce user login in their applications. In such cases, the device ID serves as the visitor ID. As for applications with few multi-device logins or without a login system at all, like some IAA hyper casual games, we can directly use the device ID as a unique identifier for users.

In this context, we developed the Device Table to record and update device-level properties and advertising-related data in real time.

Device ID (_distinct_id) Generation Rules:

Platform	Device ID
Android	Retrieve android_ID by default. If it fails, then take the UUID.
iOS	Retrieve and encrypt IDFV by default. If it fails, then take the UUID.

Device Table

When a device generates an event for the first time, its device ID and properties of this event will be added into the device table in real time.

The device table updates its properties daily at 2:00 a.m. for devices added the day before, using the latest non-empty property values reported.

Field Name	Description	Example	Type
_tenant_id	Tenant ID	1fca0a4b93fa7170	string
_prokey	Product ID	540c8f9f1519f770	string
_appkey	The 16-character AppKey, equals "attribution_app_id" in the ROI device table.	546279e4b8514d56	string
_distinct_id	Device ID: _android_id, _idfv, cookie_id, or OpenID	3e4416a9d42f4566	string
_uuid	UUID (Universally Unique Identifier) generated through Android system APIs.	99ae3a5b-750c-4f5f-aeb9-f128ab8a0ea0	string
_idfa	IDFA (Identifier for Advertisers) for iOS devices.	1e2dfa89-496a-47fd-9941-df1fc4e6484a	string
_idfv	IDFV (Identifier for Vendor) for iOS devices.	599f9c00-92dc-4b5c-9464-7971f01f8370	string
_imei	IMEI (International Mobile Equipment Identity) for Android devices.	8.61886E+14	string
_imei2	IMEI2 / IMEISV (IMEI Software Version) for Android devices.	8.61886E+14	string
_gaid	GAID (Google Advertising ID) for Android devices.	bd4b382b-2eeb-4aea-90c4-02b7f28a04b3	string
_oaid	OAID (Open Anonymous Identification) for Android devices.	fdebebfd-c64f-e6c5-7eea-b7f73da79380	string
_android_id	Android ID	55ae62239e982d88	string
_meid	MEID (Mobile Equipment Identifier) for Android devices.	0cf091d3-83da-42df-9b23-a05bdc9cce7a	string
_mac	MAC address	08:00:27:11:22:33	string
_ua	User Agent	Mozilla/5.0 (iPhone; CPU iPhone OS 13_3_1 like Mac OS X)	string
_active_time	App Activation Time, "_ts"	06:34.7	DateTime64
_update_time	Last update time	08:02.9	DateTime64
_server_time	The time when the server received the user's last data record.	45:13.7	DateTime64
_db_time	Database Time	1.662E+12	Int64
_language	Device Language	zh-han	string
_time_zone	Device Timezone	GMT+08:00	string
_manufacturer	Device Manufacturer	Apple	string
_platform	Operating Platform, e.g.0: Other1: Android2: iOS3: Windows4: Mac5: Web6: WeChat	2	number
_os_version	Operating System Version	14.3.1	number
_screen_width	Device Screen Width	1080	number
_screen_height	Device Screen Height	1920	number
_density	Pixel Density	2.62	number
_device_model	Device Model	iPhone 9,1	string
_device_type	Device Type, e.g.0: Other1: Android Phone2: Android Pad3: iPhone4: iPad5: Mac6: PC	3	number
_app_version	App Version	1.0.10.404	string
_app_version_code	Build Number	819	string
_package_name	Package Name	com.aike.dashenguilai.ad	string
_app_name	App Name	指上谈兵	string
_channel	App Distribution Platforms:Default AppStore for iOS devices.	AppStore	string
_ip	IP Address	1.119.176.34	string
_ipv6	IPv6	392c:3e1:5158:f0ac:92ae:ed3:e852:4d42	string
_country	Country	CN	string
_country_code	Country Code	CN	string
_province	Province	bj	string
_city	City	beijing	string
attribution_platform	Attribution Platform		string
promotion_platform	Promotion Platform		string
promotion_account_id	Promotion Account ID		string
promotion_account_name	Promotion Account Name		string
campaign_name	Campaign Name		string
campaign_id	Campaign ID		string
offer_name	Offer Name		string
offer_id	Offer ID		string
creative_name	Creative Name		string
creative_id	Creative ID		string
sub-channel	Sub-Channel		string
cost_amt	Advertising Costs		double
monetization_platform_list	Monetization Platforms	["kuaishou","toutiao","mintegral"]	array
iap_revenue_amt_total	IAP Revenue (Total)
iap_revenue_amt_h0	IAP Revenue (Hour 0)
iap_revenue_amt_d0	IAP Revenue (Day 0)
iap_revenue_amt_d1	IAP Revenue (Day 1)
iap_revenue_amt_d3	IAP Revenue (Day 3)
iap_revenue_amt_d7	IAP Revenue (Day 7)
iap_revenue_amt_d14	IAP Revenue (Day 14)
iap_revenue_amt_d30	IAP Revenue (Day 30)
iap_revenue_amt_d60	IAP Revenue (Day 60)
all_estimate_revenue_amt_total	Estimated Revenue (Total)
all_estimate_revenue_amt_h0	Estimated Revenue (Hour 0)
all_estimate_revenue_amt_d0	Estimated Revenue (Day 0)
all_estimate_revenue_amt_d1	Estimated Revenue (Day 1)
all_estimate_revenue_amt_d3	Estimated Revenue (Day 3)
all_estimate_revenue_amt_d7	Estimated Revenue (Day 7)
all_estimate_revenue_amt_d14	Estimated Revenue (Day 14)
all_estimate_revenue_amt_d30	Estimated Revenue (Day 30)
all_estimate_revenue_amt_d60	Estimated Revenue (Day 60)
all_real_revenue_amt_total	Actual Revenue (Total)
all_real_revenue_amt_h0	Actual Revenue (Hour 0)
all_real_revenue_amt_d0	Actual Revenue (Day 0)
all_real_revenue_amt_d1	Actual Revenue (Day 1)
all_real_revenue_amt_d3	Actual Revenue (Day 3)
all_real_revenue_amt_d7	Actual Revenue (Day 7)
all_real_revenue_amt_d14	Actual Revenue (Day 14)
all_real_revenue_amt_d30	Actual Revenue (Day 30)
all_real_revenue_amt_d60	Actual Revenue (Day 60)
monetization_properties	Used to differentiate the monetization platforms and their respective estimated & actual revenue.		map

The Application of Device Table

The device table can be used in the following scenarios:

User Analysis

Device properties can be used as the conditions to filter analysis subjects or group users.

Multiple analysis models support device-level user behavior analysis.

Online Parameter

Taking "_distinct_id" as the traffic diversion entity, you can use properties in the device table as conditions to further filter the audience.

A/B Testing

Taking "_distinct_id" as the traffic diversion entity, you can use properties in the device table as conditions to further filter the audience.

Event

Events represent specific actions that users perform within a product (App/Mini-program/Web Page). These events can include interactions such as app launches, registration, login, page views, purchases, or any other meaningful actions. Some events occur only once in a user's lifecycle, such as registration. However, most events occur multiple times, such as app launches, ad impressions, purchases and so on.

A complete event should consist of the following elements:

•Who: User information, such as the user ID.

•When: The time when the event occurs.

•Where: The location where the event occurs.

•How: Refers to how the user engages in the event. It includes various aspects, such as the device and browser used, app version, operating system, channel of acquisition, etc. You can also customize more properties as needed.

After a user is acquired, there will be many events to occur. These events are independent and arranged in chronological order (see pic). For each user, there is only one piece of record that integrates all their properties (see pic).

Event data is stored in an event table, while user data is stored in a user table. These two tables are associated with each other using the user ID as a common identifier.

Due to different event collection methods, SolarEngine divides events into preset events and self-reported events (event tracking).

Preset Events

Preset events do not require any additional tracking code inserted. They are automatically collected and recorded by the SolarEngine SDK, including app install, app launch and app exit.

Event Name	Event Identifier	Description
App Install	_appInstall	Automatically reported every time the app is installed and opened for the first time.
App Launch	_appStart	Automatically reported every time the app is opened, either from a closed state or transitioning from the background to the foreground after being inactive for more than 30 seconds.
App Exit	_appEnd	Automatically reported every time the app is closed or when it remains inactive in the background for more than 30 seconds.

Self-Reported Events

In practical business operations, besides preset events, developers often need to define and report more events for analysis. Therefore, SolarEngine provides two methods, SDK and API, for our clients to report events according to their own needs.

In SolarEngine, self-reported events are categorized into three types: predefined events, automatically captured events, and custom events.

Predefined Events

1) In-App Ad Impression

Automatically reported when displaying ads within the app, which is essential for ad revenue measurement in ROI analysis and user analysis. (Event Name: "_appImp")

2) In-App Ad Click

Automatically reported when users click ads within the app. (Event Name: "_appClick")

3) In-App Purchase

Automatically reported when users make purchases within the app (Event name: "_appPur"), which is essential for IAP revenue measurement. It is also a key event for training the payment prediction model, so if you are using our payment prediction services, "_appPur" will be a mandatory event to report.

4) Order

Automatically reported when users place orders within the app. (Event Name: "_appOrder")

5) Registration

Automatically reported when users register within the app. (Event Name: "_appReg")

6) Login

Automatically reported when users log into the app. (Event Name: "_appLogin")

7) Attribution

Allows our customers to send us the attribution results from a third-party attribution platform or SANs. You can define when and how to report this event. (Event Name: "_appAttr")

Automatically Collected Events

You can set up automatically collected events when initializing the SolarEngine SDK.

1) _appViewScreen

Report when users view a specific page within the app.

2) _appElementClick

Report when users click a specific element within the app.

Custom Events

In addition to the events listed above, you can also define and report your own personalized events.

Here are the naming conventions for custom events:

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

Event Properties

Event properties are divided into: general event properties, public event properties, predefined event properties, automatically captured event properties and custom event properties, each corresponding to the events mentioned above.

General Event Properties

General event properties are reported by the SolarEngine SDK.

Field Name	Description	Example	Data Type
_tenant_id	Tenant ID	1fca0a4b93fa7170	string
_prokey	Product ID	540c8f9f1519f770	string
_appkey	AppKey	546279e4b8514d56	string
_source_type	Data Source: record "sdk" by default if reported by SDK.	sdk	string
_event_name	Event Name	_appInstall	string
_user_id	The unique user identifier created by the SolarEngine system.	6.21562E+18	Int64
_account_id	Account ID: the value developers assign to their users.	aid25491084	string
_visitor_id	Visitor ID: take the value of _distinct_id instead without _visitor_id.	vid8709901241	string
_session_id	Session ID: identify the duration of a user's visit. App: Start from opening the app, and end when closing it. Web: Start from landing on the web page, and end when closing it.	3e4a4f9d2258cc41ee86dd09132bc61c	string
_event_id	Event identifier generated by SDK.	56e3704cf535e5e6dccdc421e37b201e	string
_event_time	Event trigger time, equals "_ts".	21:11.8	DateTime64
_server_time	The time when the server received data.	21:12.5	DateTime64
_db_time	Database Time	1.662E+12	Int64
_ds	Date when the event occurs.	2022/11/19	date
_ts	Timestamp	1.63179E+12	long
_idfa	IDFA for iOS	1e2dfa89-496a-47fd-9941-df1fc4e6484a	string
_idfv	IDFV for iOS	599f9c00-92dc-4b5c-9464-7971f01f8370	string
_uuid	UUID for Android	99ae3a5b-750c-4f5f-aeb9-f128ab8a0ea0	string
_imei	IMEI for Android	8.61886E+14	string
_imei2	IMEI2 for Android	8.61886E+14	string
_gaid	GAID for Android	bd4b382b-2eeb-4aea-90c4-02b7f28a04b3	string
_oaid	OAID for Android	fdebebfd-c64f-e6c5-7eea-b7f73da79380	string
_android_id	Android ID	55ae62239e982d88	string
_ua	User Agent	Mozilla/5.0 (iPhone; CPU iPhone OS 13_3_1 like Mac OS X)	string
_language	Device Language	zh-han	string
_time_zone	Device Timezone	GMT+08:00	string
_manufacturer	Device Manufacturer	Apple	string
_platform	Operating Platform, e.g. 0: Other 1: Android 2: iOS 3: Windows 4: Mac 5: Web 6: WeChat	2	number
_os_version	Operating System Version	14.3.1	number
_resolution	Resolution (not collected for now)		string
_screen_width	Device Screen Width	1080	number
_screen_height	Device Screen Height	1920	number
_density	Pixel Density	2.62	number
_device_model	Device Model	iPhone 9,1	string
_device_name	Device Name	iPadAir4	string
_device_type	Device Type, e.g. 0: Other 1: Android Phone 2: Android Pad 3: iPhone 4: iPad 5: Mac 6: PC	3	number
_network_type	Network Type, e.g. 0: No network connection 1: Unknown 2: 2G 3: 3G 4: 4G 5: 5G 6: 6G or more 7: WiFi	4	number
_carrier	Network Carrier		string
_app_version	App Version	1.0.10.404	string
_app_version_code	Build Number	819	string
_package_name	Package Name	com.aike.dashenguilai.ad	string
_app_name	App Name	指上谈兵	string
_channel	App Distribution Platforms: Default AppStore for iOS devices.	AppStore	string
_lib	SDK Type, e.g. 0: Other 1: Android 2: iOS 3: JavaScript 4: WeChat Mini Program 6: OPPO Quick App	2	number
_lib_version	Integrated SDK Version	1.6.6	string
_duration	Event duration for "_appEnd"in milliseconds. Call the timeEvent functionality for timing.	1280	number
_is_first_day	Whether a first-day event or not	true	boolean
_is_first_time	Whether a first-time event or not	false	boolean
_browser	Browser	Chrome, Firefox	string
_browser_version	Browser Version	Chrome 61.0	string
_page_title	Title of the current page	Cart	string
_page_name	Address of the current page	com.aike.dashenguilai.android.cart	string
_referrer_title	Title of the previous page	Index	string
_referrer_name	Address of the previous page	com.aike.dashenguilai.android.index	string
_log_count	The daily incremental sequence number of event data; used to track event data loss.	25	number
_distinct_id	Device ID iOS: Default IDFV Android: Default Android ID Web: Default cookie_id WeChat: Default open ID Optional: For apps and WeChat, if no device IDs listed above are available, then take UUID+13-bit current timestamp.	35f06a1106cd442d	string
_distinct_id_type	1001: default _distinct_id 1002: optional _distinct_id 1003: custom _distinct_id	1001	decimal
_distinct_index	Create indexes for segmentation/user packages to accelerate queries.	1.24125E+12	Int64
_is_attr	Whether self-attribute or not True: 1 False: 0	0	boolean
_adnetwork	Advertising channel ID	toutiao	string
_sub_channel	Sub-channel	103300	string
_adaccount_id	Ad account ID	1.65596E+15	string
_adaccount_name	Ad account name	xxx科技全量18	string
_adcampaign_id	Ad campaign ID	1.68071E+15	string
_adcampaign_name	Ad campaign name	小鸭快冲计划157-1024	string
_adoffer_id	Ad offer ID	1.68522E+15	string
_adoffer_name	Ad offer name	小鸭快冲单元406-1024	string
_adcreative_id	Ad creative ID	1.68013E+15	string
_adcreative_name	Ad creative name	自动创建20210901178921	string
_ad_platform	Advertising platforms, e.g. (value: name), csj：穿山甲国内版 pangle：穿山甲国际版 tencent：腾讯优量汇 baidu：百度百青藤 kuaishou：快手 oppo：OPPO vivo：vivo mi：小米 huawei：华为 applovin：Applovin sigmob：Sigmob mintegral：Mintegral oneway：OneWay vungle：Vungle facebook：Facebook admob：AdMob unity：UnityAds is：IronSource adtiming：AdTiming klein：游可赢 fyber：Fyber chartboost：Chartboost adcolony：Adcolony	csj	string
_mediation_platform	Mediation platforms, like GroMore and TopOn. Record "custom" if no mediation platform is used.	gromore	string
_ad_appid	The App ID on monetization platforms.	a603f46266d902	string
_placement_id	The Placement ID on mediation platforms.		string
_ad_id	The Placement ID on monetization platforms.	943508343	string
_ad_type	Ad types, e.g. (value: explanation), 1：Rewarded Video Ads 2：Splash Ads 3：Interstitial Ads 4：Full Screen Videos 5：Banner Ads 6：In-Feed Ads 7：Native Video Ads 8：Playable Ads 9：Pre-movie Ads 0：Other	1	string
_bid_type	Whether Header Bidding or not	0	string
_ad_ecpm	The eCPM of the current ad that received exposure. (Raw currency: CNY)	1.2206	number
_currency_type	Revenue Currency Type (following ISO 4217)	CNY	string
_is_rendered	Whether the ad is filled successfully. True: 1 False: 0	1	number
_order_id	The order ID generated by the system for this purchase	2.02111E+21	string
_pay_amount	The amount paid for this purchase (Unit: yuan)	128	string
_pay_type	Payment methods, such as alipay, weixin, applepay, paypal, etc.	applepay	string
_product_id	Purchased item ID	1700923511	string
_product_name	Purchased item name	Package 1	string
_product_num	Quantity of items purchased	1	number
_pay_status	Payment status 1: successful 2: failed 3: restored	1	string
_abgroup_id	Test ID in A/B testing		string
_abexp_id	Version ID in A/B testing		string
_bool_properties	Resolve bool type properties by calling "properties"		Map
_str_properties	Resolve string type properties by calling "properties"		Map
_dec_properties	Resolve decimal type properties by calling "properties"		Map
_arr_properties	Resolve array type properties by calling "properties"		Map
_date_properties	Resolve date type properties by calling "properties"		Map
_fail_reason	The reason of failure	BANK_ERROR	string
_reg_type	Registration type	WeChat	string
_login_type	Login type	WeChat	string
_status	Completion status of user behavior in the corresponding event	success	string
_attribution_platform	Attribution platform
_ip	IP address (prioritize the value passed in, then parse through Header if necessary)	1.119.176.34	string
_country	Country (parsed based on IP)	CN	string
_country_code	Country code (parsed based on IP)	CN	string
_province	Province (parsed based on IP)	bj	string
_city	City (parsed based on IP)	beijing	string
_ipv6	IPv6	392c:3e1:5158:f0ac:92ae:ed3:e852:4d42	string
_page_host	Page URL domain	"xxx.com/a/a.action" extracted from "xxx.com/a/a.action?id=123"	string
_referrer_host	Previous page URL domain	"xxx.com/a/a.action" extracted from "xxx.com/a/a.action?id=123"	string
_element_id	Element ID	Collect elements with the "ID" property.	string
_element_content	Element content	Collect text only, such as </span></a>. It cannot be captured if the content is an image.	string
_element_name	Element name	Collect elements with the "name" property.	string
_element_class_name	Element class name	Collect elements with the "class" property.	string
_element_type	Element type	button	string
_element_target_url	Element target URL		string
_launch_scene	Mini Program Launch Scene ID
_combination_id	Combination ID, set as null if not captured	6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b	string
_group_id_list	Online parameter group ID list, set as null if not captured	"124","431","412"	array (string)
_enter_group_id	Online Parameter Group ID （The user's entered group ID is parsed by the server. If the requested parameters are default or not present in the configuration file, this value will be "null". The SDK needs to establish an agreement with the server on a specific field for transmitting the value.）	0	number
_enter_group_status	User device status when entering groups		number
_experiment_id	Experiment ID		string
_experiment_group_id	Experiment Group ID		string
_experiment_group_id_list	Experiment Group ID List		array (string)
_experiment_status	Experiment Status (whether debugging or not)		decimal
_custom_id	Custom attribute ID		Map
_event_custom_id	Custom event attribute ID		Map
_user_custom_id	Custom user attribute ID		Map
_event_type	Event Type		decimal
_report_type	Event Type		decimal

Custom Event Properties

After defining custom events, you are also prompted to set up their properties according to the integration documentation for different platforms.

Note that the data type of custom event properties is determined by their data types reported for the first time and cannot be changed once confirmed.

Data Reporting Format Table

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.	"diamond", "北京", "1234", "true"
date	"yyyy-MM-dd HH:mm:ss.SSS", "yyyy-MM-dd HH:mm:ss", or "yyyy-MM-dd 00:00:00"	"2023-12-25 12:34:56", "2023-12-25 12:34:56.789", "2023-12-25 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"]

Predefined Event Properties

Predefined event properties include general event properties, custom event properties and properties specific to predefined events.

Here is an explanation of properties specific to predefined events.

1）_appImp

Field Name	Description	Example	Data Type	Limit
_ad_platform	Monetization platforms, for example (value: name), csj：穿山甲国内版 pangle：穿山甲国际版 tencent：腾讯优量汇 baidu：百度百青藤 kuaishou：快手 oppo：OPPO vivo：vivo mi：小米 huawei：华为 applovin：Applovin sigmob：Sigmob mintegral：Mintegral oneway：OneWay vungle：Vungle facebook：Facebook admob：AdMob unity：UnityAds is：IronSource adtiming：AdTiming klein：游可赢 fyber：Fyber chartboost：Chartboost adcolony：Adcolony	csj	string	Required
_ad_appid	The App ID on monetization platforms.	5043562	string	Required
_mediation_platform	Mediation platforms, like GroMore and TopOn. Record "custom" if no mediation platform is used.	gromore	string	Required
_ad_id	The Placement ID on monetization platforms.	943508343	string	Required
_ad_type	Ad types, for example (value: explanation), 1：Rewarded Video Ads 2：Splash Ads 3：Interstitial Ads 4：Full Screen Videos 5：Banner Ads 6：In-Feed Ads 7：Native Video Ads 8：Playable Ads 9：Pre-movie Ads 0：Other	1	number	Required
_ad_ecpm	The eCPM of the current ad that received exposure. (Raw currency: CNY)	34.00	number	Required
_currency_type	Revenue Currency Type (following ISO 4217)	CNY	string	Required
_is_rendered	Whether the ad is filled successfully.	true	boolean	Required

2）_appClick

Field Name	Description	Example	Data Type	Limit
_ad_platform	Monetization platforms, for example (value: name), csj：穿山甲国内版 pangle：穿山甲国际版 tencent：腾讯优量汇 baidu：百度百青藤 kuaishou：快手 oppo：OPPO vivo：vivo mi：小米 huawei：华为 applovin：Applovin sigmob：Sigmob mintegral：Mintegral oneway：OneWay vungle：Vungle facebook：Facebook admob：AdMob unity：UnityAds is：IronSource adtiming：AdTiming klein：游可赢 fyber：Fyber chartboost：Chartboost adcolony：Adcolony	csj	string	Required
_mediation_platform	Mediation platforms, like GroMore and TopOn. Record "custom" if no mediation platform is used.	gromore	string	Required
_ad_id	The Placement ID on monetization platforms.	943508343	string	Required
_ad_type	Ad types, for example (value: explanation), 1：Rewarded Video Ads 2：Splash Ads 3：Interstitial Ads 4：Full Screen Videos 5：Banner Ads 6：In-Feed Ads 7：Native Video Ads 8：Playable Ads 9：Pre-movie Ads 0：Other	1	number	Required

3）_appPur

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

4）_appOrder

Field Name	Description	Example	Data Type	Limit
_order_id	The order ID generated by the system for this order	2341242342676398724	string	Required (Limit 128 characters)
_pay_amount	The payment amount of the order (Unit: yuan)	128.00	number	Required
_currency_type	The currency type of the order (following ISO 4217)	CNY	string	Required
_pay_type	Payment methods, such as alipay, weixin, applepay, paypal, etc.	Alipay	string	Limit 32 characters
_status	Order status	success	string	Optional

5）_appReg

Field Name	Description	Example	Data Type	Limit
_reg_type	Payment methods, such as alipay, weixin, applepay, paypal, etc.	WeChat	string	Required (Limit 32 characters)
_status	Registration Status	success	string	Optional

6）_appLogin

Field Name	Description	Example	Data Type	Limit
_login_type	Login type such as "WeChat", "QQ" and other custom values	WeChat	string	Required (Limit 32 characters)
_status	Login status	success	string

7）_appAttr

Field Name	Description	Example	Data Type	Limit
_is_attr	Whether self-attribute or not true：yes fales：no	true	boolean	Optional (send true if no value)
_adnetwork	Channel ID (should match the channel ID in ROI analysis)	toutiao	string	Required
_sub_channel	Sub-channels for advertising	103300	string
_adaccount_id	Ad account ID for advertising	1655958321988611	string
_adaccount_name	Ad account name for advertising	xxx科技全量18	string
_adcampaign_id	Ad campaign ID for advertising	1680711982033293	string
_adcampaign_name	Ad campaign name for advertising	小鸭快冲计划157-1024	string
_adoffer_id	Ad offer ID for advertising	1685219082855528	string
_adoffer_name	Ad offer name for advertising	小鸭快冲单元406-1024	string
_adcreative_id	Ad creative ID for advertising	1680128668901378	string
_adcreative_name	Ad creative name for advertising	Auto create 20210901178921	string
_attribution_platform	Monitoring platform		string	Required

Automatically Captured Event Properties

Automatically captured event properties include general event properties, self-reported custom event properties, and predefined properties for the event.

1）_appViewScreen

Field Name	Description
_page_title	Title of the current page
_page_name	Address of the current page
_referrer_title	Title of the previous page
_referrer_name	Address of the previous page
_page_host	URL of the current page
_referrer_host	URL of the previous page
_combination_id	Combination ID, set as null if no value obtained
_group_id_list	Group ID, set as null if no value obtained
_session_id	Session ID, identifying app start to app exit

2）_appElementClick

Field Name	Description
_element_id	Element ID
_element_content	Element content
_element_name	Element name
_element_class_name	Element class name
_element_type	Element type
_element_target_url	Element target URL
_combination_id	Combination ID, set as null if no value obtained
_group_id_list	Group ID, set as null if no value obtained
_session_id	Session ID, identifying app start to app exit

First Time/Day Properties

When analyzing user behavior, we might pay more attention to events that occur on the first day after app installation, or for the first time after user acquisition regardless of whether it's on the first day or later. Therefore, we developed two more identifiers for each event: "_is_first_day" and "_is_first_time".

The value of these two identifiers is either true or false.

Data Reporting Method	Event	Assignment Method	Server-Side Validation & Correction
SDK Data Reporting	App install, launch, purchase, ad impressions	SDK assignment	Perform validation & correction if the value is true. Do not perform any correction if the value is false.
SDK Data Reporting	Other events (including custom events)	SDK assignment	Save directly without any correction.
API Data Reporting	App install, launch, purchase, ad impressions	Developer assignment	Perform validation & correction if the value is true. Do not perform any correction if the value is false.
API Data Reporting	Other events (including custom events)	Developer assignment	Save directly without any correction.

As you can see, we will validate and correct the value of the two markers for certain important events like "_appInstall" based on the user data reported before, so that the markers can be more reliable.

If you decide to report data through API, the responsibility for value assignment accuracy and accountability lies with the developer.

Event Tracking Plan

Given the high complexity of user behavior and huge quantity of events, it is recommended that you and your team establish a unified event tracking plan document to standardize the process and maintain data consistency.

Event data can be reported through either SDK or API. The only difference between these two methods is that SDK automatically collects certain events for you, such as app install, launch and exit, while API requires you to create customized code for each event you want to track.

SDK/API integration is performed on an application level, so please use different AppKeys for different apps.

Considerations

Determine user identification method, such as user ID, or device ID.
Determine events, event properties, and event triggers.
Determine user properties.
Prioritize the implementation of event tracking.

Naming Conventions

In event tracking, custom event identifiers and custom property identifiers must adhere to the following naming conventions: they can consist of lowercase letters, numbers and underscores, but cannot begin with an underscore, contain spaces, or exceed 40 characters.

The data type of property values is determined by the format type used in the initial reporting. Subsequent reports will only accept inputs of the same type. Otherwise, the data will be considered erroneous and will not be stored in the database.
Event identifiers and property identifiers are for development personnel to use and should be filled in by technical staff.
For event triggers, it is recommended to align the calibration internally between operations and development personnel, and then fill in the information uniformly to ensure data consistency and accuracy.

Data Access