Game SDK pre-defined events and properties
|
Collect
1. App Platform
Description
Referring to the game SDK, after being integrated by clients, it is ultimately packaged into an app and runs on Android & iOS platforms
1.1. Pre-defined events
| Event variable name (English) | Event display name | Attribute variable name (English) | Attribute display name | Attribute value type | Attribute value example or description | Trigger condition |
|---|---|---|---|---|---|---|
| $AppStart | App Start | $is_first_time | Whether it is the first time | Boolean value | Indicates whether it is the first time the app is launched. For more details, please refer to the documentNew users and first-day first-time marking | Triggered when starting the app or switching back to the app from the background |
| $resume_from_background | Whether awakened from the background | Boolean value | ||||
| $AppEnd | App exit | $event_duration | Event duration | Numerical value | Refers to the duration from app launch to app exit in seconds | Triggered when quitting the app or the app goes to the background |
| $AppInstall | App activation / First launch after app installation | $browser | Browser name | String | Value parsed from the user agent (UA) | It needs to call the trackAppInstall interface to collect this event and will only be triggered after the first app launch following installation. It will not be triggered upon the second call. |
| $utm_source | Advertising Campaign Source | String | To use Sensors Analytics App Channel Tracking, the AppInstall event requires a successful channel match to have $utm related attributes. Refer to Sensors Analytics' App Channel Tracking for more information. | |||
| $utm_medium | Advertising Campaign Medium | String | ||||
| $utm_term | Advertising Campaign Term | String | ||||
| $utm_content | Advertising Campaign Content | String | ||||
| $utm_campaign | Advertising Campaign Name | String | ||||
| $ios_install_source | / | String | Record the matching field when accurately matching an App, such as IMEI, Android ID, Mac address, IDFA. This field is uploaded when collecting data on the App side, but will be removed by the extractor module and not stored in the database. Therefore, this attribute will not be stored. | |||
| $utm_matching_type | Channel tracking matching mode | String | By default, this property is not included when collecting events on the App side, but is added by the extractor module. It records the successful channel matching mode, such as fuzzy device fingerprint matching or precise device identification matching. If no successful match is made, the value of this property will be displayed as "Unknown" on the event analysis page. | |||
| $matched_key | Channel matching keyword | String | By default, this property is not included when collecting events on the App side, but is added by the extractor module. It records the matching key field, such as the MD5 of the successfully matched IMEI, or IP_UA for IP_UA matching. If no successful match is made, the value of this property will be displayed as "Unknown" on the event analysis page. | |||
| $matching_key_list | Channel matching keyword list | String | Supported since SA 1.14. By default, this property is not included when collecting events on the App side, but is added by the extractor module. It records all the matching keywords for the activation event, such as the MD5 of the IMEI, Android ID, oaid, IP_UA, etc. When matching, it will prioritize these keywords and match them with the keywords recorded when the ad was clicked. | |||
| $channel_active_period_day | Active period window (days) | Numeric | Records the information of the window period configuration. The activation changes caused by changes in the window period can also be traced. | |||
| $channel_attribute_period_hour | Activation Attribution Window (hours) | Value | ||||
| $AppRemoteConfigChanged | Remote control configuration changed | $app_remote_config | Remote control configuration information | String | When obtaining remote configuration, after the SDK loads the configuration and takes effect, this event is collected along with the corresponding control information for troubleshooting. | SDK Obtains Remote Configuration |
1.2. Pre-defined attributes for all events
| Attribute Name | Attribute Type | Default Display Name | Description | Remarks |
|---|---|---|---|---|
| $app_id | String | Unique Identifier for the App | Unique identifier for the app | |
| $app_name | String | App Name | Application's Name | |
| $app_version | String | App Version | APP's Application Version | |
| $lib | String | SDK Type | SDK Type, e.g. Android/iOS | |
| $lib_version | String | SDK Version | SDK Version | |
| $manufacturer | String | Device Manufacturer | Device Manufacturer | |
| $brand | String | Device Brand | Device Brand | Only collected on Android |
| $model | String | Device Model | Device Model | |
| $os | String | Operating System | Operating System | |
| $os_version | String | Operational System Version | Operational System Version | |
| $screen_height | Numeric | Screen Height | Screen Height (On iOS, it is logical resolution in development points; On Android, it collects the physical pixel points. For example, if the resolution of the Android phone is 1920 x 1080, it collects this value.) | |
| $screen_width | Numeric | Screen Width | Screen Width (On iOS, it refers to the logical resolution, which is the point pixel in development; while on Android, it refers to the physical pixel, for example, if the resolution of an Android phone is 1920 x 1080, it will collect this value.) | |
| $wifi | Boolean | WiFi Indicator | Indicates whether it is WiFi when the event is triggered | |
| $carrier | String | Carrier Name | The carrier name of the device's SIM card when the event is triggered. If Android does not have the READ_PHONE_STATE permission or there is no SIM card inserted, the carrier name cannot be obtained. If there is no SIM card inserted in iOS, the carrier name cannot be obtained. | |
| $network_type | String | Network Type | The network type when the event is triggered. If the SDK does not have permission to access the network type or the phone is in airplane mode, no SIM card is inserted, or there is no WiFi connection, the network type cannot be obtained. | |
| $timezone_offset | Number | Timezone Offset | The timezone offset of the app or system. | |
| $is_first_day | Boolean | Whether it is the first day of visit | Indicates whether it is the first day of triggering the event. This attribute can be used to filter new and existing users. For specific value logic, please refer to the document on new user and first-day first-time marking | |
| $is_login_id | Boolean value | Whether the Login ID is | Added when data is stored | |
| $ip | String | IP | Obtained by parsing the HTTP request on the back end | |
| $country | String | Country | Obtained from IP parsing | |
| $province | String | Province | ||
| $city | String | City | ||
| $device_id | String | Device ID | For Android devices, it mainly takes Android ID; for iOS devices, it first tries to obtain IDFA. If it fails to obtain IDFA, it takes IDFV. The specific logic for obtaining the value can be referred to in the document How to accurately identify users |
1.3. Predefined User Property
| Property Name | Property Type | Default Display Name | Description | Remarks |
|---|---|---|---|---|
| $first_visit_time | Datetime | First Visit Time | After calling the trackAppInstall interface, the first time the user starts the App, this property will be assigned a value. | This property is set when calling the trackAppInstall interface, usually marked on anonymous ID (Android ID/IDFA) users. If the login ID and anonymous ID are not associated successfully, the property value of the login ID user will be empty. |
| $utm_source | String | First Ad Campaign Source | These attributes rely on calling the trackAppInstall interface and using APP Channel Tracking. After successful matching, the corresponding channel information (utm_ parameters) contained in the channel link will be written to the user profile. The channel tracking matching mode and channel matching keyword record the matching channel method and which keyword was used to make the match. | |
| $utm_medium | String | First Ad Campaign Medium | ||
| $utm_term | String | First Ad Campaign Keyword | ||
| $utm_content | String | First ad campaign content | ||
| $utm_campaign | String | First ad campaign name | ||
| $utm_matching_type | String | Channel tracking matching type | ||
$matched_key | String | Channel Matching Keyword | ||
| matching_key_list | string | Channel Matching Keyword List | Channel Matching Keyword List, including all possible keys used for channel matching. | Same as above, and supported by SA 1.14+ version. Channel Matching Keyword List, including all possible keywords used for channel matching. |
1.4. Others
| Attribute Name | Attribute Type | Default Display Name | Description | Notes |
|---|---|---|---|---|
| $lib_plugin_version | List | SDK Plugin Version | This property is used to record the version number of the Sensory Analysis plugin, for example: Android plugin; Collection example: $lib_plugin_version:["android_plugin:4.2"] | Usually collected when the SDK is integrated in the form of a third-party framework plugin |
2. PC Platform
Description
- Refers to the game SDK, which is integrated by the client and finally runs on the PC platform (including Windows & macOS)
- Currently, only Unity SDK and Unreal Engine SDK support the PC platform
2.1. Predefined Event
| Event English Variable Name | Event Display Name | Property English Variable Name | Event Property Display Name | Property Value Type | Example or description of attribute value | Trigger timing | Remarks |
|---|---|---|---|---|---|---|---|
| $AppStart | App Start | $is_first_time | Whether it is the first time | Boolean value | Indicates whether it is the first time the app is started. Refer to the documentNew Users and First-day First-time Markings | Triggered when the app is started or switched from the background to the app | Unreal Engine SDK is not supported yet |
| $AppEnd | App Exit | $event_duration | Event Duration | Numeric value | Specifically refers to the duration from the app start to the app exit, in seconds | Triggered when exiting the app or when the app goes to the background | Unreal Engine SDK is not supported yet |
| $AppInstall | App Activation / App First Launch After Installation | $browser | Browser Name | String | The value parsed from the User Agent (UA) | This event needs to be collected by calling the trackAppInstall API. It will only be triggered when the app is launched for the first time after installation, and will not be triggered upon subsequent launches. | Unreal Engine SDK v0.0.3 and later versions are supported. |
| $channel_active_period_day | Effective Activation Window (Days) | Numeric | Record information about the configuration of the activation window period. It can be used to trace changes in activations caused by changes in the window period. | ||||
| $channel_attribute_period_hour | Activation Attribution Window (Hours) | Numeric |
2.2. Preset properties for all events
| Property Name | Attribute Type | Default Display Name | Description | Remarks |
|---|---|---|---|---|
| $app_id | String | App Unique Identifier | Unique identifier for the app | Not supported by Unreal Engine SDK at the moment |
| $app_name | String | App Name | Name of the app | Not supported by Unreal Engine SDK at the moment |
| $app_version | String | App Version | Version of the app | |
| $lib | String | SDK Type | The type of SDK, such as Android/iOS | |
| $lib_version | String | SDK Version | SDK version | |
| $manufacturer | String | Device manufacturer | Device manufacturer, Windows result is graphics card manufacturer | Unreal Engine SDK does not support for now |
| $model | String | Device model | Device model | Unreal Engine SDK does not support for now |
| $os | String | Operating System | Operating System | |
| $os_version | String | Operating System Version | Operating System Version | |
| $screen_height | Numeric | Screen Height | Screen Height | |
| $screen_width | Numeric | Screen Width | Screen Width | |
| $timezone_offset | Numerical value | Timezone offset | App or system timezone | |
| $is_first_day | Boolean value | Whether it is the first day of visit | Indicates whether it is the first day the event is triggered. This attribute can be used to filter new and old users. For specific value logic, please refer to the document Newly added users and first day first-time marking | |
| $is_login_id | Boolean value | Whether it is a login ID | Determined when data is stored | |
| $ip | String | IP | Obtained by parsing the HTTP request on the backend | |
| $country | String | Country | Obtained by IP resolution | |
| $province | String | Province | ||
| $city | String | City | ||
| $device_id | String | Device ID |
2.3. Predefined User Properties
Description
Unreal Engine SDK v0.0.3 and later versions are supported
| Property Name | Property Type | Default Display Name | Description | Remarks |
|---|---|---|---|---|
| $first_visit_time | Datetime | First Visit Time | After calling the trackAppInstall interface, the first launch time of the app for new users is assigned to this property. | This property is set when calling the trackAppInstall interface and is generally tagged on anonymous ID users. If the association between login ID and anonymous ID is not successful, the property value for the login ID user is not available. |
| $matching_key_list | String | Channel Matching Keyword List | The list of channel matching keywords, including all possible keys for channel matching. | Same as above, and supported in SA 1.14+ version. The channel matching keyword list includes all possible keywords for channel matching. |
3. Mini Game Platform
Description
The main platforms of mini-games include:
- Non-H5 mini-games: WeChat mini-games, QQ mini-games, Byte mini-games, etc.
- H5 mini-games: H5 mini-games
3.1. Preset Events
| Event English Variable Name | Event Display Name | Triggered Occasion | Corresponding Lifecycle | Non-H5 mini-games | H5 mini-games |
|---|---|---|---|---|---|
| $MPShow | Mini-program Display | Triggered when the mini-game is hot-started or brought to the foreground from the background | Triggered when the onShow lifecycle function of the mini-game is triggered | Supported | Not supported |
| $MPHide | Mini-program enters the background | Triggered when the mini-game enters the background | The onHide lifecycle function of triggering mini-games is triggered | Support | Not Supported |
3.2. Common properties for all events
| Field Name | Type | Description | Non-H5 mini-game | H5 mini-game |
|---|---|---|---|---|
| $lib | String | SDK Type | Supported | Supported |
| $lib_version | String | SDK version | Supported | Supported |
| $app_id | String | App ID of the mini program | Support | Not supported |
| $brand | String | Brand | Support | Not supported |
| $screen_height | Numeric | Screen height | Support | Support |
| $screen_width | Numeric | Screen width | Support | Support |
| $model | String | Device type | Supported | Supported |
| $manufacturer | String | Device manufacturer | Supported | Supported |
| $mp_client_app_version | String | Version of the client application | Supported | Not Supported |
| $mp_client_basic_library_version | String | lib version | Supported | Not Supported |
| $os | String | Operating System | Supported | Supported |
| $os_version | String | Operating System Version | Supported | Supported |
| $is_first_day | Boolean | Whether it is the first day of visit (From the first visit of new users to 23:59:59 on the day, it is true; after that, it is false. The judgment flag is stored in WeChat storage) | Supported | Supported |
| $is_login_id | Boolean | Whether it is a login ID (added after data is imported into the database) | Supported | Supported |
| $ip | String | Attributes carried by SDK data request | Supported | Supported |
| $timezone_offset | Numeric | Timezone offset | Supported | Supported |
| $country | String | Obtained from IP resolution | Supported | Supported |
| $province | String | Obtained from IP resolution | Supported | Supported |
| $city | String | IP Resolved | Supported | Supported |
| $network_type | String | Network Type | Supported | Supported |
| $browser | String | Browser Type, resolved from UA | Supported | Supported |
| $browser_version | String | Browser Version, resolved from UA | Supported | Supported |
Note: The content of this document is a technical document that provides details on how to use the Sensors product and does not include sales terms; the specific content of enterprise procurement products and technical services shall be subject to the commercial procurement contract.
Popular Searches