App SDK Predefined Events and Properties
|
Collect
1. Predefined Events
Event English Variable Name | Event Display Name | Property English Variable Name | Property Display Name | Property Value Type | Property Value Example or Explanation | Trigger Timing | Remarks |
---|---|---|---|---|---|---|---|
$AppStart | App Start | $is_first_time | Whether First Time | Boolean value | Indicates whether it is the first time the App is launched, please refer to the documentation Newly Added Users and First Day First Time Marking | Triggered when the App is launched or switched from the background to the foreground | Universal data collection for Android/iOS SDK, enabling the AutoTrack interface will automatically enable it, please refer to the integration documentation of the client SDK.
|
$resume_from_background | Whether awakened from the background | Boolean value | |||||
$screen_name | Page name | String | Package name.class name of the Activity (only applicable for Android platform, the startup logic on the iOS platform does not require jumping to a specific page to determine if the app is launched, so the iOS platform cannot collect the page name during startup) | ||||
$title | Page title | String | Title of the Activity (only applicable for Android platform, the startup logic on the iOS platform does not require jumping to a specific page to determine if the app is launched, so the iOS platform cannot collect the page title during startup) | ||||
$AppEnd | App exit | $event_duration | Event duration | Numerical value | Refers to the duration from app launch to app exit for this particular session, in seconds | Exit App or go to background on App triggered | |
$screen_name | Page name | String | Package name. Class name of Activity (Only available on Android. For iOS, there is no need to jump to a specific page to determine if the app is exited. Therefore, the page name cannot be collected when the app is exited on iOS.) | ||||
$title | Page title | String | Title of the Activity (Only available on Android. For iOS, there is no need to jump to a specific page to determine if the app is exited. Therefore, the page title cannot be collected when the app is exited on iOS.) | ||||
$AppViewScreen | App browsing page | $screen_name | Page name | String | Package name. Class name of Activity on Android / Class name of ViewController on iOS. The value of this property can be set manually. | Triggered when opening an Activity / ViewController page (For Android, by default, Fragment does not trigger browsing page event. If you want to collect it, you need to enable it separately.) | |
$title | Page title | String | Title of Activity (Android) / Title of ViewController (iOS) | ||||
$url | Page URL | String | Auto-tracking version: Android 3.2.8, iOS 1.11.5 | ||||
$referrer | Referring URL | String | Auto-tracking version: Android 3.2.8, iOS 1.11.5 | ||||
$AppClick | App Element Click | $screen_name | Page Name | String | Package name.class name of Activity (Android) / Class name of ViewController(iOS); the value of this attribute can be manually set | Triggered when a control is clicked For Android: CheckBox, RadioButton, button, SwitchCompat, Spinner, TextView, ImageView, ImageButton, SeekBar, RatingBar, RadioGroup, MenuItem, ExpandableListView, Dialog, ListView, GridView, TabHost, etc. For iOS: UIButton, UIBarButtonItem, UISwitch, UISlider, UISegment, UIPageControl, UIStepper, UILabel + gesture, UIImageView + gesture, UIAlertController, UIMenu, etc. | |
$title | Page Title | String | Title of the Activity (Android) / Title of the ViewController (iOS) | ||||
$element_position | Element Position | String | Position of the element within the module, starting from 0. Only under special controls, this attribute will have a value (such as UITableView and UICollectionView in iOS, ListView in Android). For controls where this attribute value cannot be collected, the value will be displayed as "Unknown" in the Sensors Analytics page. | ||||
$element_id | Element ID | String | Default value for Android; For iOS, each control is generally not set with an ID, so it will not be collected by default. Can be manually set | ||||
$element_content | Element content | String | If the element content set in the control code is not set in a control, or the control type is a picture, the property cannot be collected and displayed as "unknown" on the event analysis page. Therefore, if you find that the content of a button is not collected, you need to confirm the type of this button control with the customer's R and D students, and whether the element content is set in the code. | ||||
$element_type | Element type | String | The type of the control, such as Button | ||||
$element_selector | Element selector | String | This attribute mainly records the position of a button in the APP. This attribute is used when the App of Shence clicks the graph to display, and business personnel do not need to pay attention to the value logic of this attribute. | ||||
$element_path | Element path | String | The visual all-buried feature collects the value of this property and requires manual code to enable it | ||||
AppInstall / $AppInstall | App activation/First startup after App installation | $browser | Browser Name | String | Value parsed from user agent | It needs to call the trackInstallation/trackAppInstall API to collect this event. The event will only be triggered when the app is installed and opened for the first time, and will not be triggered on the second opening. | Sensors Analytics Android SDK v4.3.6+ and iOS SDK v2.1.14+ add the trackAppInstall interface. Calling this interface will collect the $AppInstall event. If the original activated event name is not $AppInstall, you need to use avirtual eventto merge the original activated event and $AppInstall for analysis. For details, please consult Sensors Analytics technical support. |
$utm_source | Advertising Campaign Source | String | The App Install event will have the $utm-related properties only after successfully tracking the app channel with Sensors Analytics App channel tracking method. For details, refer to Sensors Analytics App Channel Tracking. | ||||
$utm_medium | Advertising Campaign Medium | String | |||||
$utm_term | Advertising Campaign Term | String | |||||
$utm_content | Ad Campaign Content | String | |||||
$utm_campaign | Ad Campaign Name | String | |||||
$ios_install_source | / | String | Records the matching field when accurate matching of the app is made, such as IMEI, Android ID, Mac address, and IDFA. This field will be uploaded when collecting data on the app side, but it will be removed and not stored in the extractor module. Therefore, this property will not be stored. | ||||
$utm_matching_type | Channel Tracking Matching Mode | String | By default, there is no such property when collecting events on the app side. Instead, it is added in the extractor module. It records the mode of successful channel matching, such as device fingerprint fuzzy matching or device identification accurate matching. If there is no successful match, the attribute value will be displayed as "Unknown" on the event analysis page. | ||||
$matched_key | Channel Matching Keyword | String | By default, there is no such property when collecting events on the app side. Instead, it is added in the extractor module. It records the matching key field when the app channel tracking is successfully matched. For example, if it is matched with IMEI, then the MD5 hash of IMEI will be recorded. If it is matched through IP_UA, it will be recorded as IP_UA. If there is no successful match, the attribute value will be displayed as "Unknown" on the event analysis page. | ||||
$matching_key_list | Channel Matching Keyword List | String | Added since SA version 1.14; The property is not included by default when collecting events on the App side, but is added in the extractor module. It records all matching keywords of the activation event, such as the MD5 hashed IMEI, Android ID, OAID, IP_UA, etc. During matching, it is matched according to the priority of these keywords and the keywords recorded when clicking on the ad. | ||||
$channel_active_period_day | Effective Activation Window Period (in days) | Number | Records the information of the window period configuration, and can be used to trace the changes in activations caused by window period changes. | ||||
$channel_attribute_period_hour | Activation Attribution Window Period (in hours) | Number | |||||
asa_iad_info | Apple Search Ads Attribution Data | String | Not available for Android; For iOS integration, when the iOS system version is greater than or equal to 10.0 and IDFA permission is enabled, this property is available; | ||||
asa_adservices_info | Apple Search Ads Attribution Data | String | Not available for Android; For iOS integration, when the iOS system version is greater than or equal to 14.3 and IDFA permission is not available, this property is available. | ||||
AppCrashed | App Crash | app_crashed_reason | Crash Reason | String | Only collected when crash collection is enabled | APP Crash | |
$AppStartPassively | App Passive Start | $app_state | App State | String | iOS defaults to collecting, Android does not collect | iOS APP is system activated | This event is available on iOS but not on Android. |
$resume_from_background | Resumed from background | Boolean | |||||
$is_first_time | Is First Time | Boolean | Indicates whether it is the first time launching the app. Refer to the document New Users and First-day First-time Mark | ||||
$AppRemoteConfigChanged | Remote Control Configuration Changes | $app_remote_config | Remote Control Configuration Information | String | Get remote configuration. After the SDK loads the configuration and takes effect, it collects this event and collects the corresponding control information for troubleshooting. | SDK obtains remote configuration | Android SDK 4.4.1+ iOS SDK 2.1.8+ |
$AppDeeplinkLaunch | Deep Link Wakeup App | $deeplink_url | Deep Link URL | String | DeepLink URL that wakes up the app | When the app is woken up by DeepLink | User for analyzing the relevant data when the App is awakened by Deeplink; The $utm_xxx and $latest_utm_xxx attributes in this event cannot be directly collected by the SDK and need to be supplemented by the backend Android SDK 4.2.1+ iOS SDK 2.1.2+ |
$utm_source and other 5 attributes | Ad campaign source, etc. | String | |||||
$latest_utm_source and other 5 attributes | Latest ad campaign source, etc. | String | |||||
$AppDeeplinkMatchedResult | Deep link matching result | $deeplink_url | Deep link URL | String | Deep link URL that awakens the App | The event triggered after the SDK completes parsing the Deep link configuration | Android SDK 4.2.1+ iOS SDK 2.1.2+ |
$event_duration | Event duration | Numerical value | |||||
$deeplink_options | Deeplink Parameters | String | Deeplink parameters configured on the web page | ||||
$deeplink_match_fail_reason | Reason for Deeplink Match Failure | String | |||||
$utm_source and 5 other properties | Source of the advertising campaign and others | String | |||||
$AppPushClick | App Push Click | $app_push_msg_title | Push Message Title | String | Push is triggered when clicked | Android SDK v5.1.0+ Android plugin v3.3.4+ iOS SDK v2.5.3+ | |
$app_push_msg_content | Push message content | String | |||||
$app_push_service_name | Third-party push service provider | String | Possible values are:JPush | ||||
$app_push_channel | App push channel | String | Possible values are:HUAWEI、OPPO、vivo、Xiaomi、Meizu | ||||
Attributes that start with $sf | Godplan marketing cloud related properties | These attributes will only be included when clicking on the push sent by Sensors Analytics Marketing Cloud. For more information, please refer to this document | |||||
$ABTestTrigger | A/B Testing | $abtest_experiment_id | Specific experiment ID | string | Triggered when an experiment is hit | Android SDK v4.3.6+ iOS SDK v2.1.14+ | |
$abtest_experiment_group_id | Specific experiment group ID | string | |||||
$is_control_group | Whether it is a control group user | boolean | Indicates segmented user/random traffic user | ||||
$AppPageLeave | Page Leave | $event_duration | Event duration | Numerical value | The page exit event is triggered when the page is invisible, and the browsing duration is calculated. In this case, the page viewing duration is specified | After leaving the page, the page leaving event is reported | Android SDK v5.4.2+ iOS SDK v3.1.5+ |
$screen_name | page title | String | The package name of the Activity. Class name (Android)/ViewController class name (iOS); You can set the value of this property manually | ||||
$title | page title | String | Activity title (Android) /ViewController title (iOS) | ||||
$url | Page url | String | Automatic capture version Android: 3.2.8, iOS: 1.11.5 | ||||
$referrer | Forward address | String | Automatically collected version Android: 3.2.8, iOS: 1.11.5 | ||||
$PlanPopupDisplay | Popup Display | $sf_msg_title | Popup Title | String | Triggered when the popup display | Requires integration with SensorsFocus SDK, see Popup Reach Integration | |
$sf_msg_content | Popup Content | String | |||||
$sf_succeed | Message sent successfully | Boolean value | true/false, true represents success | ||||
$sf_fail_reason | Popup failure reason | String | If the popup is successful, display unknown | ||||
$PlanPopupClick | Popup clicks | $sf_msg_element_type | Popup button type | String | Popup element type: normal button, text link, image link, close icon, overlay | Triggered when the popup is clicked | Requires integrating SensorsFocus SDK, refer toPopup reach integration |
$sf_msg_element_action | Popup button action | String | Popup click action: jump, preset action, web only has URL jump, App only has URL, custom jump, copy, close | ||||
$sf_msg_element_content | Popup button copy | String | |||||
$sf_msg_action_id | Click Event ID | String | |||||
$sf_msg_image_url | Image URL | String | Image URL (CDN storage address) | ||||
$sf_close_type | Close button type | String | Close button type, only closing behavior has: closing overlay, popup upper right close icon, popup lower close icon, bottom button (set as the button to close the popup) |
2. All events have preset attributes
Attribute Name | Attribute Type | Default Display Name | Description | Remarks |
---|---|---|---|---|
$app_id | String | Application Unique Identifier | Unique identifier for the app | Supported by Android SDK version 4.1.0 Supported by iOS SDK version 2.0.9 |
$app_name | String | App Name | Name of the app | Supported by Android SDK version v4.2.8 Supported by iOS SDK version 2.1.8 |
$app_version | String | App Version | App version of the APP | |
$lib | String | SDK Type | SDK Type, such as Android/iOS | Android SDK v5.2.5, the value for HarmonyOS is Android |
$lib_version | String | SDK Version | SDK Version | |
$manufacturer | String | Device Manufacturer | Device Manufacturer | Android SDK v5.2.2, the value is all uppercase |
$brand | String | Device Brand | Device Brand | Android SDK v5.2.2, new attribute only collected on Android |
$model | String | Device Model | Device Model | |
$os | String | Operating System | Operating System | Android SDK v5.2.5 adds collection of Hongmeng system |
$os_version | String | Operating System Version | Operating System Version | Android SDK v5.2.5 adds collection of Hongmeng system version |
$referrer_title | String | Forward Page Title | Previous Page Title | Android SDK v4.4.7 and above support, v6.0.0 and above versions default enabled, v6.0.0 and below enabled through SAConfigOptions enableReferrerTitle configuration iOS SDK v2.2.5 and above support, enabled through SAConfigOptions enableReferrerTitle configuration; v4.0.0 and above versions default enabled |
$screen_height | Number | Screen Height | Screen Height (On iOS, it is logical resolution, which is the point pixel in development; On Android, it collects physical pixel points, for example, Android phone resolution is 1920 x 1080, and the collected value is this.) | |
$screen_width | Numerical | Screen Width | Screen Width (On iOS, it is logical resolution, which is the point pixel in development; On Android, it collects physical pixel points, for example, Android phone resolution is 1920 x 1080, and the collected value is this.) | |
$wifi | Boolean | Whether WiFi | Whether it is WiFi when the event is triggered | |
$carrier | String | Carrier Name | The name of the carrier on the device's SIM card at the time the event is triggered. If Android does not have READ_PHONE_STATE permission or no SIM card is inserted, the carrier name cannot be obtained; If iOS does not have a SIM card inserted, the carrier name cannot be obtained | Due to iOS system limitations, for iOS 16.4 and above versions, the iOS SDK cannot collect carrier information. That is, for iOS 16.4 and above systems, all events of iOS SDK do not have the preset property $carrier. Reference: iOS & iPadOS 16.4 Release Notes |
$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 if the phone is in airplane mode, without a SIM card, or not connected to WiFi, the network type cannot be obtained. | |
$timezone_offset | Numeric value | Timezone offset | App or system timezone | Supported in Android SDK version 4.1.0 Supported in iOS SDK version 2.0.9 |
$is_first_day | Boolean value | Whether it is the first day of visit | Indicates whether it is the first day to trigger an event. This attribute can be used to filter new and existing users. For specific value logic, please refer to the document New users and first-day-first-time marking | Supported in Android SDK version 1.6.27 Supported in iOS SDK version 1.6.29 |
$is_login_id | Boolean value | Whether it is a login ID | Determined when data is stored | |
$ip | String | IP | Received by parsing the HTTP request on the backend | |
$country | String | Country | Obtained through IP parsing | |
$province | String | Province | ||
$city | String | City | ||
$device_id | String | Device ID | For Android devices, it mainly uses Android ID. For iOS devices, it first attempts to obtain IDFA. If IDFA cannot be obtained, it uses IDFV. For specific value acquisition logic, please refer to the How to accurately identify users document | Support in Sensors Analytics Android SDK version 1.7.1. The value in the range of Android v6.2.0 to v6.2.5 is $anonymization_id. Support in Sensors Analytics iOS SDK version 1.10.18. The value in the range of iOS v4.2.0 to v4.2.3 is $anonymization_id |
$screen_orientation | String | Screen Orientation | Only collected when enableTrackScreenOrientation is enabled | Supported in Sensors Analytics Android/iOS SDK version 1.10.1 |
$latitude | Number | GPS Information | Latitude * 106 Only collected when enableTrackGPSLocation is enabled | Supported in Sensors Analytics Android/iOS SDK version 1.10.1 Android devices need to be passed manually |
$longitude | Metric | User Segment | Longitude * 106 Only available when enableTrackGPSLocation: is turned on | Android/iOS version 1.10.1 or later Android devices need to pass manually |
$geo_coordinate_system | String | Coordinate System | Only available when enableTrackGPSLocation: is turned on | Android version 5.2.2 or later iOS version 2.6.4 or later iOS devices default to WGS84 Android devices need to pass manually |
$anonymization_id | String | Anonymized ID | Base64-encoded and obfuscated $device_id | Android version 6.2.0 to 6.2.5 iOS version 4.2.0 to 4.2.3 SDG v0.8.11738 + SCA commands can be executed by contacting the Sensors Operation team |
3. Tracked and passed back pre-set event properties during channel matching and backfilling
Property Name | Property Type | Default Display Name | Description | Note |
---|---|---|---|---|
$channel_device_info | String | Records device information for channel matching | When tracking custom events with App Channel Tracking, channel matching can be conducted by calling - | Supported in SA 1.15+ |
$is_channel_callback_event | Boolean | Whether to perform channel matching callback | When tracking custom events with App Channel Tracking, channel matching can be conducted by calling - trackChannelEvent:properties: to track the events to be matched. After the backend matches the channel information, the result will be passed back to the channel partner. For specific usage, please refer to the SDK API documentation. | Supported in SA 1.15+; By default, this property is set to true only for the first occurrence of triggering a custom event with channel tracking, indicating a successful match and callback of channel data to the advertiser. For subsequent occurrences of triggering this event, the value of this property will be false. |
4. Preset user properties
Attribute name | Attribute type | Default display name | Instructions | Remarks |
---|---|---|---|---|
$first_visit_time | Datetime(Time) | First access time | After calling trackInstallation / trackAppInstall interface, when a new user starts the App for the first time, this property is assigned a value. | These properties are dependent on the calltrackInstallation / trackAppInstall interface, generally marked on the anonymous ID (Android ID/IDFA) user, if the login ID and the anonymous ID are not successfully associated, the login ID user has no value for this attribute value. |
$utm_source | String | Source of the first AD campaign | These properties are dependent on the calltrackInstallation / trackAppInstall interface, and use APP Channel tracking, after the matching is successful, the corresponding channel information (utm_ parameter) contained in the channel link is written into the user table. The channel matching mode and channel matching keyword record the matching channel mode and the matching keyword | |
$utm_medium | String | First advertising campaign medium | ||
$utm_term | String | First campaign keyword | ||
$utm_content | String | First campaign content | ||
$utm_campaign | String | First campaign name | ||
$utm_matching_type | String | Channel tracking matching mode | ||
$matched_key | String | Channel matching keyword | ||
$matching_key_list | String | Channel matching keyword list | Channel matching keyword list, including all possible keys for channel matching | Same as above, and SA 1.14+ version supports, channel matching keyword list, including all possible keyword for channel matching |
5. Others
Property Name | Property Type | Default Display Name | Description | Remark |
---|---|---|---|---|
$lib_plugin_version | List | SDK Plugin Version Number | This attribute is used to record the version number of the various plugins in Sensors Analytics, such as the Android plugin. Collection example: $lib_plugin_version:["android_plugin:4.2"] | It will only be collected with Android SDK v4.3.5+ and Android plugin v3.2.14+; |
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.