Title: Preset Events and Preset Properties
Locale: en
URL: https://sensorswave.com/en/docs/data-integration/preset-events-and-properties/
Description: Description of Sensors Wave preset events and properties
Sensors Wave includes a set of predefined events and predefined properties built into the SDK for automatically collecting basic user behavioral data and environmental information. Making proper use of Preset Events and Preset Properties helps you quickly build a data collection system, reduce manual tracking effort, and ensure standardization and consistency in data collection.

## Why Should You Understand Preset Events and Preset Properties?

Understanding Preset Events and Preset Properties can help you:

- **Reduce development effort**: The SDK automatically collects basic behavioral data without manual tracking
- **Ensure data standardization**: Use unified event and property naming to ensure data consistency
- **Get started with analysis quickly**: Immediately obtain basic user behavioral data to support fundamental analysis needs
- **Avoid naming conflicts**: Understand system-reserved property names to avoid conflicts between custom properties and Preset Properties
- **Improve data quality**: The SDK automatically handles data formatting and edge cases, ensuring data accuracy

## Core Concepts

### What Are Preset Events?

Preset Events are standardized events automatically collected by the SDK, used to record basic user behaviors such as page views, app launches, element clicks, etc. Preset Events use the `$` prefix in their naming to distinguish them from user-defined events.

**Characteristics of Preset Events**:

- Automatically collected by the SDK; no manual calls required
- Unified naming convention with the `$` prefix
- Cross-platform semantic consistency
- Include rich Preset Property information

### What Are Preset Properties?

Preset Properties are standardized properties automatically collected by the SDK, divided into two categories — Built-in Properties and business predefined properties:

- **Built-in Properties**: Core fields automatically generated by the system, such as `time`, `event_id`, `ssid`, etc., used for data storage, indexing, and querying
- **Business Predefined Properties**: Business-related properties automatically collected by the SDK, such as device information, browser information, geolocation, etc., named with the `$` prefix

**Characteristics of Preset Properties**:

- Automatically collected by the SDK to ensure data completeness
- Unified naming convention with the `$` prefix (business predefined properties)
- Standardized data formats and types
- Provide foundational dimensions for common analysis scenarios

## Preset Event List

Sensors Wave Preset Events are organized by reporting platform. Each platform has corresponding base events for recording user behavior.

### Web Preset Events

The Web SDK automatically collects the following Preset Events:

| Event Name | Display Name | Description | Trigger Timing |
|---------|---------|------|---------|
| `$PageView` | Web Page View | Triggered when a user views a page | Page load complete or route change |
| `$PageLoad` | Web Page Load | Triggered when page loading is complete | Page onload event fires |
| `$PageLeave` | Web Page Leave | Triggered when a user leaves a page | Page unload or beforeunload event fires |
| `$WebClick` | Web Page Click | Triggered when a user clicks a page element | Clicking an interactive element (link, button, etc.) |

**Use Cases**:

- **`$PageView`**: Analyze user page browsing paths, page dwell time, page popularity, etc.
- **`$PageLoad`**: Analyze page load performance, first contentful paint time, etc.
- **`$PageLeave`**: Analyze user exit behavior, page bounce rate, etc.
- **`$WebClick`**: Analyze user click behavior, hotspot areas, etc.

### App Preset Events

The App SDK (Android and iOS) automatically collects the following Preset Events:

| Event Name | Display Name | Description | Trigger Timing |
|---------|---------|------|---------|
| `$AppStart` | App Start | Triggered when the app launches | App enters foreground |
| `$AppEnd` | App End | Triggered when the app exits | App enters background or fully exits |
| `$AppPageView` | App Page View | Triggered when a user views an app page | Page (Activity/ViewController) enters |
| `$AppPageLeave` | App Page Leave | Triggered when a user leaves an app page | Page (Activity/ViewController) leaves |
| `$AppClick` | App Element Click | Triggered when a user clicks an app element | Clicking a button, view, or other interactive element |
| `$AppInstall` | App Install Activation | Triggered on first app install activation | First app launch |

**Use Cases**:

- **`$AppStart` / `$AppEnd`**: Analyze app launch count, session duration, session analysis, etc.
- **`$AppPageView` / `$AppPageLeave`**: Analyze page browsing paths, page dwell time, page popularity, etc.
- **`$AppClick`**: Analyze user interaction behavior, feature usage, etc.
- **`$AppInstall`**: Analyze new user activations, channel effectiveness, etc.

### WeChat Mini Program Preset Events

The Mini Program SDK automatically collects the following Preset Events:

| Event Name | Display Name | Description | Trigger Timing |
|---------|---------|------|---------|
| `$MPLaunch` | Mini Program Launch | Triggered when the mini program launches | Mini program initialization complete |
| `$MPShow` | Mini Program Show | Triggered when the mini program is shown | Mini program enters foreground |
| `$MPHide` | Mini Program Hide | Triggered when the mini program enters background | Mini program switches to background |
| `$MPPageView` | Mini Program Page View | Triggered when a user views a mini program page | Page load complete |
| `$MPPageLeave` | Mini Program Page Leave | Triggered when a user leaves a mini program page | Page unload or switch |
| `$MPClick` | Mini Program Element Click | Triggered when a user clicks a mini program element | Clicking an interactive element |
| `$MPShare` | Mini Program Share | Triggered when a user shares the mini program | Invoking share function |

**Use Cases**:

- **`$MPLaunch`**: Analyze mini program launch count, launch source scenarios, user activation, etc.
- **`$MPShow` / `$MPHide`**: Analyze mini program usage duration, session analysis, user stickiness, etc.
- **`$MPPageView` / `$MPPageLeave`**: Analyze page browsing paths, page dwell time, page popularity, etc.
- **`$MPClick`**: Analyze user interaction behavior, feature usage, click heatmaps, etc.
- **`$MPShare`**: Analyze sharing behavior, viral effects, fission analysis, etc.

### Cross-Platform Preset Events

The following events are supported across all platforms:

| Event Name | Display Name | Description | Trigger Timing |
|---------|---------|------|---------|
| `$ExpImpress` | Experiment Impression | Triggered when an experiment is exposed | User is assigned to an experiment strategy |
| `$FeatureImpress` | Feature Gate Impression | Triggered when a feature gate is exposed | User is assigned to a feature gate strategy |

**Use Cases**:

- **`$ExpImpress`**: Analyze experiment impression counts, experiment coverage, etc.
- **`$FeatureImpress`**: Analyze feature gate impression counts, feature coverage, etc.

## Preset Property List

Preset Properties are divided into Built-in Properties and business predefined properties. Built-in Properties are used for data storage and querying, while business predefined properties are used for data analysis.

### Built-in Properties

Built-in Properties are core fields automatically generated by Sensors Wave, used for data storage, indexing, querying, and user identity recognition. These properties cannot be overridden or modified.

| Property Name | Display Name | Description | Data Type | Collection Source |
|-------|-----------|------|---------|---------|
| `time` | Event Time | Timestamp when the event occurred (client-side time) | DateTime | JavaScript, Android, iOS |
| `event_id` | Event ID | Hash value of the event name, used for indexing and query acceleration | Int | - |
| `trace_id` | Trace ID | Client-generated unique ID for event deduplication; automatically filled with UUID if not reported | String | JavaScript, Android, iOS |
| `anon_id` | Anonymous ID | Unique ID identifying the device or browser, typically a device ID or UUID | String | JavaScript, Android, iOS |
| `user_id` | Login ID | User's Login ID, identifying the logged-in user's business account | String | JavaScript, Android, iOS |
| `event` | Event Name | Reported event name | String | JavaScript, Android, iOS |
| `ssid` | Server-Side Unique User ID | Server-generated unique user ID, hash-computed from distinct_id, used for user association and correction | Int64 | - |
| `received_at` | Event Received Time | Server-side timestamp when the data was received | DateTime | - |
| `created_at` | Event Stored Time | Timestamp when data was written to the database | DateTime | - |
| `updated_at` | Event Updated Time | Last update time of the data, only updated in scenarios like user identity association correction | DateTime | - |

> **Tip**: Built-in Properties do not need to be manually reported; they are automatically generated and managed by the SDK or server.

### SDK-Related Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$lib` | SDK Library | Type of SDK used | `"webjs"`, `"mpjs"`, `"go"`, `"java"`, `"android"`, `"ios"` | JavaScript, Android, iOS |
| `$lib_version` | SDK Library Version | SDK version number | `"3.0.2"` | JavaScript, Android, iOS |

### Cross-Platform Common Properties

Applicable to all clients (Web, App):

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$title` | Page Title | Title of the current page | `"Sensors Wave"` | JavaScript, Android, iOS |
| `$url` | Current Browsing URL | Full URL of the current page | `"https://example.com/page"` | JavaScript, Android, iOS |
| `$timezone_offset` | Timezone Offset | App or system timezone offset (unit: seconds) | `28800` (East 8th zone, UTC+8) | JavaScript, Android, iOS |
| `$referrer` | HTTP Referrer | HTTP Referrer, full URL of the referring page | `"https://www.baidu.com"` | JavaScript, Android, iOS |
| `$language` | Language | User's system language setting | `"en"`, `"zh-CN"` | JavaScript, Android, iOS |

### Device-Related Properties

Applicable to all clients (Web, App):

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$model` | Device Model | Device model information | `"xiaomi 15"` | JavaScript, Android, iOS |
| `$os` | Operating System | Device operating system | `"iOS"`, `"Android"`, `"Windows"` | JavaScript, Android, iOS |
| `$os_version` | OS Version | Operating system version number | `"10.15.7"`, `"14.0"` | JavaScript, Android, iOS |
| `$screen_height` | Screen Height | Device screen height (pixels) | `1080` | JavaScript, Android, iOS |
| `$screen_width` | Screen Width | Device screen width (pixels) | `1920` | JavaScript, Android, iOS |

### Browser-Related Properties

Applicable to Web only:

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$browser` | Browser | Browser type | `"Chrome"`, `"Safari"`, `"Firefox"` | JavaScript |
| `$browser_version` | Browser Version | Browser version number | `"125"`, `"16.5"` | JavaScript |
| `$pathname` | Current Web Path | Path portion of the current page | `"/page"`, `"/products/123"` | JavaScript |
| `$host` | Host Address | Host address of the current page | `"example.com"` | JavaScript |
| `$viewport_height` | Viewport Height | Browser viewport height (pixels) | `950` | JavaScript |
| `$viewport_width` | Viewport Width | Browser viewport width (pixels) | `1903` | JavaScript |
| `$search_engine` | Search Engine | User's referring search engine | `"google"`, `"baidu"` | JavaScript |
| `$referrer_host` | HTTP Referrer Host | Domain portion of the HTTP Referrer | `"www.baidu.com"` | JavaScript |

### App-Related Properties

Applicable to App only (Android and iOS):
| Property Name | Display Name | Description | Example Value |
|-------|-----------|------|-------|
| `$lib` | SDK Library | Type of SDK used | `"android"`, `"ios"` |
| `$lib_version` | SDK Library Version | SDK version number | `"3.0.2"` |
| `$device_id` | Device ID | The unique identifier of the device |  |
| `$network_type` | Network Type | Current network connection type | `"wifi"`, `"4G"`, `"5G"` |
| `$manufacturer` | Device Manufacturer | Device manufacturer | `"Google"`, `"Apple"`, `"Samsung"` |
| `$app_version` | App Version | Application version number | `"1.0.0"`, `"2.5.3"` |
| `$app_id` | App Unique Identifier | Application unique identifier | `"com.sol.analytics"` |
| `$app_name` | App Name | Application name | `"Sol"`, `"Sensors Wave"` |
| `$brand` | Device Brand | Device brand | `"xiaomi"`, `"huawei"`, `"apple"` |
| `$wifi` | WiFi at Event Time | Whether WiFi was being used when the event was triggered | `true`, `false` |
| `$timezone_offset` | Timezone Offset | App or system timezone offset (unit: seconds) | `28800` (East 8th zone, UTC+8) |
| `$referrer_title` | Previous Page Title | Title of the referring page | `"Home"`, `"Product List"` |
| `$region` | Region | User's region (country or region code) | `"us"`, `"cn"` |
| `$language` | Language | User's system language setting | `"en"`, `"zh-CN"` |

### Mini Program Related Properties

Applicable to Mini Programs only:

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$brand` | Device Brand | Device brand | `"xiaomi"`, `"huawei"`, `"apple"` | Mini Program |
| `$manufacturer` | Device Manufacturer | Device manufacturer | `"Google"`, `"Apple"`, `"Samsung"` | Mini Program |
| `$network_type` | Network Type | Current network connection type | `"wifi"`, `"4G"`, `"5G"` | Mini Program |
| `$url_path` | Page Path | Mini program page path | `"pages/index"`, `"pages/detail"` | Mini Program |
| `$url_query` | Page Query Parameters | Mini program page query parameters | `"id=123&source=home"` | Mini Program |

Applicable to all platforms; generated by the server based on client IP address parsing:

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$ip` | IP Address | Client IP address | `"192.168.1.1"` | - |
| `$city` | City | City resolved from IP | `"Qingdao"`, `"Beijing"` | - |
| `$province` | Province | Province resolved from IP | `"Shandong"`, `"Guangdong"` | - |
| `$country` | Country | Country resolved from IP | `"China"`, `"United States"` | - |

> **Tip**: IP-resolved properties are automatically generated by the server based on the client IP address; no client-side reporting is required.

### Advertising-Related Properties (UTM Parameters)

Applicable to Web and App, used for tracking advertising effectiveness:

The SDK automatically parses UTM parameters from the URL and reports them as User Properties, recording the user's ad source information. UTM parameters are automatically updated to the most recent visit value.

**Example URL**:

```
https://example.com/product?utm_source=newsletter&utm_medium=email&utm_campaign=product_launch&utm_term=new+product&utm_content=logolink
```

> **Note**: UTM parameters are User Properties, stored in the users table, recording the user's most recent ad source information.

### Event-Specific Properties

Certain Preset Events include event-specific Preset Properties in addition to the common Preset Properties.

#### $PageLoad Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$event_duration` | Page Load Duration | Time taken for the page to finish loading, unit: seconds | `1.5` | JavaScript |
| `$page_resource_size` | Page Resource Size | Size of page resources, unit: kb | `1000` | JavaScript |

#### $PageLeave Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$event_duration` | Page View Duration | Time the user spent on the page, unit: seconds | `30` | JavaScript |

#### $WebClick Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$element_type` | Element Type | HTML tag type of the clicked element | `"div"`, `"button"`, `"a"` | JavaScript |
| `$element_name` | Element Name | Name attribute value of the element | `"button"`, `"submit"` | JavaScript |
| `$element_id` | Element ID | ID attribute value of the element | `"id"`, `"submit-btn"` | JavaScript |
| `$element_class_name` | Element Class Name | Class attribute value of the element | `"class"`, `"btn-primary"` | JavaScript |
| `$element_target_url` | Element Target URL | Href attribute value of link elements | `"https://example.com"` | JavaScript |
| `$element_content` | Element Content | Text content of the element | Element text | JavaScript |
| `$element_selector` | Element Selector | CSS selector of the element | `"#id"`, `".class"` | JavaScript |
| `$element_path` | Element Path | Path of the element in the DOM tree | `"body > .class"` | JavaScript |
| `$page_x` | Click Distance from Left | Distance of the click position from the left side of the page (pixels) | `100` | JavaScript |
| `$page_y` | Click Distance from Top | Distance of the click position from the top of the page (pixels) | `200` | JavaScript |

#### $AppStart and $AppEnd Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$screen_name` | Screen Name | Name of the current screen | `"name"`, `"HomePage"` | Android, iOS |

**$AppEnd Additional Properties**:

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$event_duration` | Event Duration | Duration from App start to App end, unit: seconds | `180` | Android, iOS |

#### $AppPageView and $AppPageLeave Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$screen_name` | Screen Name | Name of the current screen | `"name"`, `"HomePage"` | Android, iOS |

#### $AppClick Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$event_duration` | Event Duration | Duration of page viewing, unit: seconds | `30` | Android, iOS |
| `$screen_name` | Screen Name | Name of the current screen | `"name"`, `"HomePage"` | Android, iOS |
| `$element_position` | Element Position | Position of the element in the module, starting from 0 | `0`, `1`, `2` | Android, iOS |
| `$element_id` | Element ID | ID of the element | Element ID | Android, iOS |
| `$element_content` | Element Content | Text content of the element | Element text | Android, iOS |
| `$element_type` | Element Type | Type of the control | `"Button"`, `"TextView"` | Android, iOS |
| `$element_selector` | Element Selector | Records the button's position in the app | Selector path | Android, iOS |
| `$element_path` | Element Path | Path of the element on the page | Path information | Android, iOS |

#### $MPLaunch and $MPShow Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$scene` | Launch Scene | Mini program launch scenario value | `1000`, `1011`, `1047` | Mini Program |

#### $MPHide Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$event_duration` | Event Duration | Duration the mini program was in foreground, unit: seconds | `180` | Mini Program |

#### $MPPageLeave Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$event_duration` | Event Duration | Page view duration, unit: seconds | `30` | Mini Program |

#### $MPClick Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$element_type` | Element Type | Type of the clicked element | `"view"`, `"button"`, `"text"` | Mini Program |
| `$element_name` | Element Name | Name attribute value of the element | `"submit-btn"`, `"nav-bar"` | Mini Program |
| `$element_id` | Element ID | ID attribute value of the element | `"button-1"`, `"page-header"` | Mini Program |
| `$element_content` | Element Content | Text content of the element | `"Submit"`, `"Confirm"` | Mini Program |
| `$element_selector` | Element Selector | Selector path of the element | `"#id"`, `".class"` | Mini Program |
| `$element_path` | Element Path | Path of the element on the page | `"page > .container > view"` | Mini Program |

#### $MPShare Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$share_method` | Share Method | Method of sharing | `"Share to Moments"`, `"Forward message card"` | Mini Program |

#### $FeatureImpress Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$feature_key` | Feature Gate Key | Unique identifier for the feature gate | `"new_ui_enabled"`, `"dark_mode"` | All platforms |
| `$feature_variant` | Feature Gate Variant | Variant value of the feature gate | `"pass"`, `"fail"` | All platforms |

#### $ExpImpress Specific Properties

| Property Name | Display Name | Description | Example Value | Collection Source |
|-------|-----------|------|-------|---------|
| `$exp_key` | Experiment Key | Unique identifier for the experiment | `"button_color_test"`, `"layout_v2"` | All platforms |
| `$exp_variant` | Experiment Variant | Variant value of the experiment | `"v0"`, `"v1"`, `"v2"` | All platforms |

## Preset User Properties

Preset User Properties describe basic user information and key timestamps, stored in the users table.

### Built-in User Properties

| Property Name | Display Name | Description | Data Type |
|-------|-------|------|---------|
| `ssid` | Server-Side Unique User ID | Server-generated unique user ID, hash-computed from distinct_id, used for user association and correction | Int64 |
| `user_id` | Login ID | User's Login ID, identifying the logged-in user's business account | String |
| `anon_ids` | Anonymous ID List | List of Anonymous IDs used by the same user | Array |
| `created_at` | User Created Time | Time when the user was first recorded | DateTime |
| `updated_at` | User Updated Time | Last update time of user properties | DateTime |
| `aid` | User Auto-Increment ID | User's auto-increment ID for internal indexing | Int |

### Feature-Related User Properties

When a user is assigned to a feature gate, the system automatically records the following User Properties:

| Property Name | Display Name | Description | Example Value |
|-------|-------|------|-------|
| `$feature_{ID}` | {Feature Gate Name}_{ID} | Records the feature gate status assigned to the user | `"pass"` / `"fail"` |

**Description**:

- **pass**: User passed the feature gate and can access the new feature
- **fail**: User did not pass the feature gate and cannot access the new feature

**Example**:

```javascript
// User assigned to feature gate with ID 123, passed
{
  $feature_123: "pass"
}

// User assigned to feature gate with ID 456, not passed
{
  $feature_456: "fail"
}
```

### UTM-Related User Properties

When a user visits through a link with UTM parameters, the system automatically records the following User Properties:

| Property Name | Display Name | Description | Example Value |
|-------|-------|------|-------|
| `$utm_source` | Ad Source | Identifies the traffic source, such as search engine, website name | `"newsletter"`, `"google"` |
| `$utm_medium` | Ad Medium | Identifies the marketing medium, such as email, CPC | `"email"`, `"cpc"`, `"social"` |
| `$utm_campaign` | Ad Campaign | Identifies the specific marketing campaign | `"product_launch"`, `"summer_sale"` |
| `$utm_term` | Ad Keyword | Identifies paid search keywords | `"new+product"`, `"data+analytics"` |
| `$utm_content` | Ad Content | Used to distinguish different content or links within the same ad | `"logolink"`, `"textlink"` |
| `$initial_utm_source` | Initial Ad Source | The ad source when the user first visited | `"newsletter"`, `"google"` |
| `$initial_utm_medium` | Initial Ad Medium | The ad medium when the user first visited | `"email"`, `"cpc"`, `"social"` |
| `$initial_utm_campaign` | Initial Ad Campaign | The ad campaign when the user first visited | `"product_launch"`, `"summer_sale"` |
| `$initial_utm_term` | Initial Ad Keyword | The ad keyword when the user first visited | `"new+product"`, `"data+analytics"` |

**Description**:

- `$utm_*` properties record the user's most recent ad source information, updated with each visit containing UTM parameters
- `$initial_utm_*` properties record the user's first visit ad source information and do not change once set
- Initial UTM properties help you analyze users' original acquisition channels and track user attribution

### Experiment-Related User Properties

When a user is assigned to an experiment, the system automatically records the following User Properties:

| Property Name | Display Name | Description | Example Value |
|-------|-------|------|-------|
| `$exp_{ID}` | {Experiment Name}_{ID} | Records the experiment variant assigned to the user | `"v0"`, `"v1"`, `"v2"` |

**Description**:

- Experiment variant identifier, such as `"v0"` (control group), `"v1"`, `"v2"`, etc.
- Used to record which experiment variant the user was assigned to

**Example**:

```javascript
// User assigned to experiment with ID 789, assigned to v1 variant
{
  $exp_789: "v1"
}

// User assigned to experiment with ID 1000, assigned to control group
{
  $exp_1000: "v0"
}
```

## How to Use Preset Properties

### Automatic Collection

Most Preset Properties are automatically collected by the SDK without manual reporting. Simply integrate the SDK correctly to automatically obtain these properties.

```javascript
// Web SDK example: SDK automatically collects Preset Properties
sensorswave.trackEvent('PageView');

// The actual event sent includes Preset Properties:
// {
//   event: "PageView",
//   time: 1769595185716,
//   $url: "https://example.com/products",
//   $pathname: "/products",
//   $browser: "Chrome",
//   $browser_version: "125",
//   $os: "Windows",
//   $os_version: "10",
//   $screen_width: 1920,
//   $screen_height: 1080,
//   ...
// }
```

### Manual Override (Optional)

Certain Preset Properties support manual override. You can provide custom values when reporting events:

```javascript
// Override Preset Property values
sensorswave.trackEvent('Purchase', {
  $referrer: 'https://custom-referrer.com',  // Override the default $referrer
  order_id: 'ORDER-001',                     // Custom Event Property
  total_amount: 299.00
});
```

> **Note**:
> - Built-in Properties (e.g., `time`, `event_id`, `ssid`) cannot be overridden
> - Only override Preset Properties when there is a clear need; otherwise, it may cause data inconsistency

### Using in Analysis

Preset Properties can be used in data analysis just like custom properties:

- **Filtering**: Filter events by specific browser, operating system, traffic source
- **Grouping**: Group statistics by device model, geolocation, ad source, and other dimensions
- **Aggregation**: Calculate event counts, conversion rates, and other Metrics across different dimensions

**Example: Analyze page views by browser type**

1. Select event: `$PageView`
2. Grouping dimension: Select `$browser`
3. View results: Distribution of page views across Chrome, Safari, Firefox, and other browsers

## Best Practices

### 1. Understand the Collection Scope of Preset Properties

Different platform SDKs collect different Preset Properties:

- **Web SDK**: Collects browser, device, URL, and related properties
- **App SDK**: Collects device, network, app version, and related properties
- **Mini Program SDK**: Collects device brand, network type, page path, and related properties
- **Server-side**: Collects IP-resolved properties

When designing your analysis plan, understand the Preset Properties supported by the target platform and avoid relying on properties that don't exist.

### 2. Avoid Conflicts with Preset Properties

Custom properties should not use the `$` prefix to avoid naming conflicts with Preset Properties:

```javascript
// Not recommended: using the $ prefix
sensorswave.trackEvent('Purchase', {
  $custom_field: 'value'  // May conflict with Preset Properties
});

// Recommended: not using the $ prefix
sensorswave.trackEvent('Purchase', {
  custom_field: 'value'   // Clearly distinguishes custom properties
});
```

### 3. Leverage Preset Properties to Reduce Tracking Effort

Fully utilize the Preset Properties automatically collected by the SDK to avoid redundant tracking:

```javascript
// Not recommended: manually reporting browser information
sensorswave.trackEvent('PageView', {
  browser: navigator.userAgent,  // SDK already auto-collects $browser
  url: window.location.href      // SDK already auto-collects $url
});

// Recommended: rely on SDK automatic collection
sensorswave.trackEvent('PageView', {
  page_category: 'product'  // Only report custom properties not collected by the SDK
});
```

### 4. Use UTM Parameters Properly

Use UTM parameters consistently in marketing campaigns to track traffic sources:

**Recommended practices**:

- Set complete UTM parameters for each marketing campaign
- Use consistent naming conventions (lowercase, underscore-separated)
- Establish UTM parameter management guidelines within the team

**Examples**:

```
# Email marketing campaign
https://example.com/product?utm_source=newsletter&utm_medium=email&utm_campaign=summer_sale

# Google Ads
https://example.com/product?utm_source=google&utm_medium=cpc&utm_campaign=brand_keywords&utm_term=sensors+wave

# Social media promotion
https://example.com/product?utm_source=wechat&utm_medium=social&utm_campaign=product_launch&utm_content=banner
```

### 5. Monitor Preset Property Data Quality

Regularly check the data quality of Preset Properties to ensure the SDK is working properly:

- Check coverage rates for properties like `$browser`, `$os`, etc.
- Verify the accuracy of properties like `$url`, `$referrer`, etc.
- Monitor the parsing success rate for IP-resolved properties like `$ip`, `$city`, etc.

## Important Notes

### Built-in Properties Cannot Be Modified

Built-in Properties (e.g., `time`, `event_id`, `ssid`) are automatically generated by the system and cannot be manually overridden or modified. Any attempt to override these properties will be ignored.

### Preset Property Availability

- **Client-collected properties**: Only automatically collected when events are reported from the client; server-side tracking will not include these properties
- **IP-resolved properties**: Depend on the client IP address; if the IP address cannot be resolved (e.g., internal network IP), the related properties may be empty
- **UTM parameters**: Only collected when the URL contains UTM parameters; otherwise, the related properties will be empty

### Preset Property Naming Restrictions

- The `$` prefix is reserved for the system, used only for Preset Properties
- Custom properties should not use the `$` prefix
- Do not create custom properties with the same name as Preset Properties

### Cross-Platform Differences

Preset Properties vary across platforms:

- **Web**: Includes browser-related properties (e.g., `$browser`, `$url`)
- **App**: Includes app-related properties (e.g., `$app_version`, `$network_type`)
- **Mini Program**: Includes mini program-related properties (e.g., `$url_path`, `$url_query`)
- **Common properties**: Supported across all platforms (e.g., `$os`, `$ip`)

Be aware of property availability when conducting cross-platform analysis.

## Related Documentation

- [Data Model](data-model.mdx): Understand the role of events and properties in the overall data model
- [Events and Properties](events-and-properties.mdx): Learn how to design custom events and properties
- [Property Data Types](property-data-types.mdx): Learn about the property data types supported by Sensors Wave and their usage guidelines
- [How to Properly Identify Users](user-identification.mdx): Understand the meaning of user identification-related Preset Properties (`anon_id`, `user_id`, `ssid`)

---

**Last updated**: January 19, 2026