Title: Events and Properties
Locale: en
URL: https://sensorswave.com/en/docs/data-integration/events-and-properties/
Description: Definitions, naming conventions, and usage guidelines for events and properties
Events are the core of the Sensors Wave data model, recording specific actions performed by users in your application. Event Properties and User Properties provide contextual information for events, enabling multi-dimensional data analysis. Properly designing events, Event Properties, and User Properties is the foundation for effective data analysis and directly impacts the depth and value of your analysis.

## Why Should You Understand Events and Properties?

Properly designing events, Event Properties, and User Properties can help you:

- **Accurately record user behavior**: Capture key business actions and user intent, supporting comprehensive behavioral analysis
- **Increase analysis flexibility**: Filter, group, and aggregate events across multiple dimensions using Event Properties and User Properties
- **Reduce maintenance costs**: Use generic events with properties, avoiding the need to create new events for every minor variation
- **Improve data quality**: Follow naming conventions and best practices to ensure data consistency and scalability
- **Enable precise Cohorts**: Build accurate user profiles through User Properties, supporting personalized analysis

## Core Concepts

### What Is an Event?

An event is a specific action performed by a user in your application or an activity that occurs in the system. Each event represents a user action worth tracking and analyzing.

**Composition of an Event**:

Each event contains the following core elements:

- **Event Name** (`event`): A name describing the user behavior, such as `PageView`, `Purchase`, `UserLogin`
- **Event Time** (`time`): The timestamp when the event occurred (client-side time)
- **User Identifiers**:
  - `distinct_id`: The currently active unique user identifier
  - `anon_id`: Anonymous ID, identifying the device or browser
  - `login_id`: Login ID, identifying the logged-in user
  - `ssid`: Server-generated unique user ID used for data analysis
- **Event Properties**: Detailed information and context describing the event, such as product ID, amount, traffic source, etc.
- **User Property Snapshot**: The state of the user's properties at the moment the event occurred

**Common Event Types**:

| Business Scenario | Typical Events | Description |
|---------|---------|------|
| **E-commerce Platform** | `ProductView`, `AddToCart`, `Purchase` | Product browsing, add to cart, purchase behavior |
| **Content Platform** | `ArticleRead`, `VideoPlay`, `ContentShare` | Content consumption and sharing behavior |
| **SaaS Application** | `UserSignup`, `FeatureUsed`, `SubscriptionRenew` | User registration, feature usage, subscription renewal |
| **Mobile Application** | `AppOpen`, `ScreenView`, `NotificationClick` | App open, page view, notification click |

### What Are Event Properties?

Event Properties describe the specific context and details when an event occurs. Event Properties are reported together with the event and provide the necessary dimensions and details for analysis.

**Characteristics of Event Properties**:

- Associated with a specific event, describing the details of "this particular action"
- Recorded only when the event occurs; not persisted to the user dimension
- Can be used for event filtering, grouping, aggregation, and other analyses
- Different instances of the same event can have different property values

**Event Property Examples**:

For a `Purchase` event, common Event Properties include:

```javascript
{
  event: "Purchase",
  properties: {
    order_id: "ORDER-2026-001",      // Order ID
    total_amount: 299.00,            // Total order amount
    currency: "CNY",                 // Currency type
    payment_method: "alipay",        // Payment method
    item_count: 3,                   // Number of items
    product_category: "electronics", // Product category
    discount_amount: 20.00,          // Discount amount
    shipping_method: "express"       // Shipping method
  }
}
```

### What Are User Properties?

User Properties describe user characteristics and status, such as demographic information, behavioral preferences, account information, etc. Unlike Event Properties, User Properties are persistently stored and represent the overall profile of a user at a given point in time.

**Characteristics of User Properties**:

- Describe the overall characteristics of a user, rather than a single action
- Stored in the user dimension table; can be updated at any time
- Used for Cohorts, segmentation, and personalized analysis
- Support multiple data types: String, Number, Boolean, Datetime, List

**User Property Examples**:

```javascript
// Set User Properties
sensorswave.setUserProfile({
  user_id: "user_12345",
  name: "John",
  age: 28,
  gender: "male",
  city: "Beijing",
  membership_level: "gold",
  registration_date: "2025-01-15",
  total_purchase_count: 15,
  total_spent: 4580.00,
  favorite_categories: ["electronics", "books", "sports"],
  is_vip: true,
  last_login_date: "2026-01-22"
});
```

**Common User Property Types**:

| Category | Typical Properties | Description |
|------|---------|------|
| **Demographics** | `age`, `gender`, `city`, `occupation` | Describes basic user characteristics |
| **Account Information** | `membership_level`, `registration_date`, `account_status` | Describes user account status |
| **Behavioral Traits** | `total_purchase_count`, `last_login_date`, `avg_session_duration` | Describes user behavior patterns |
| **Preferences** | `favorite_categories`, `preferred_payment_method`, `language` | Describes user preferences and habits |
| **Business Metrics** | `total_spent`, `lifetime_value`, `churn_risk_score` | Describes user business value |

**User Property Update Methods**:

Sensors Wave supports multiple User Property update operations:

```javascript
// 1. Set (set) - Set or update User Properties
sensorswave.setUserProfile({
  city: "Shanghai",
  membership_level: "platinum"
});

// 2. Set Once (set_once) - Set only when the property doesn't exist
sensorswave.setOnceUserProfile({
  first_visit_date: "2026-01-22",
  registration_channel: "wechat"
});

// 3. Increment (increment) - Increment numeric properties
sensorswave.incrementUserProfile({
  total_purchase_count: 1,
  total_spent: 299.00
});

// 4. Append (append) - Append values to list properties
sensorswave.appendUserProfile({
  favorite_categories: "home_appliances"
});

// 5. Unset (unset) - Delete specified properties
sensorswave.unsetUserProfile(["old_field_1", "old_field_2"]);
```

### Event Properties vs User Properties

Understanding the difference between Event Properties and User Properties is crucial for properly designing your data model:

| Dimension | Event Properties | User Properties |
|---------|---------|---------|
| **Data Scope** | Describes the details of a single event | Describes the overall characteristics of a user |
| **Storage Method** | Stored in the events table, recorded with the event | Stored as a snapshot in the events table; the latest value is stored in the users table |
| **Update Method** | Recorded when the event occurs, cannot be modified | Can be updated, added, or deleted at any time (users table only) |
| **Analysis Use** | Event filtering, group statistics, trend analysis | Cohort, Retention, conversion analysis |
| **Example** | Order amount, product category, page URL | User age, membership level, registration time |

**Recommendations**:

- **Use Event Properties**: When information is related to a specific action and may have different values across different events
  - Product SKU (different purchase events may involve different products)
  - Page URL (different browsing events visit different pages)
  - Order amount (each purchase has a different amount)
  - Video duration (each video has a different playback duration)

- **Use User Properties**: When information describes an overall user characteristic and is relatively stable
  - User age (relatively fixed)
  - Membership level (remains unchanged for a period of time)
  - Registration time (never changes)
  - City (relatively stable)

> **Note**: The same piece of information can serve as both an Event Property and a User Property. For example, a user's membership level at the time of a purchase can be recorded as an Event Property (describing the status at the time of purchase), while the current membership level can also be stored as a User Property (describing the user's current status).

## Event Design Principles

### 1. Use Appropriate Event Granularity

Events should be neither too broad nor too specific. Event granularity should match the level at which you plan to analyze user behavior.

**Recommended practices**:
- Use generic event names with properties to distinguish details
  - Event: `PageView`, property: `page_name: "/home"` or `page_name: "/pricing"`
  - Event: `ButtonClick`, property: `button_name: "add_to_cart"` or `button_name: "checkout"`
  - Event: `VideoPlay`, property: `video_id: "V12345"`, `video_category: "tutorial"`

**Practices to avoid**:
- (Not recommended) Creating separate events for each page
  - `HomePageView`, `PricingPageView`, `ProductPageView` (too specific)
- (Not recommended) Creating separate events for each button
  - `AddToCartButtonClick`, `CheckoutButtonClick` (too specific)
- (Not recommended) Using overly broad event names
  - `UserAction`, `Click` (too broad, lacking semantics)

**Comparison example**:

```javascript
// Not recommended: separate events for each page
sensorswave.trackEvent('HomePageView');
sensorswave.trackEvent('PricingPageView');
sensorswave.trackEvent('ProductPageView');

// Recommended: generic event with properties
sensorswave.trackEvent('PageView', {
  page_name: '/home',
  page_title: 'Home Page',
  page_category: 'marketing'
});

sensorswave.trackEvent('PageView', {
  page_name: '/pricing',
  page_title: 'Pricing',
  page_category: 'marketing'
});
```

### 2. Event Naming Conventions

Consistent naming conventions help maintain data consistency and reduce team collaboration costs.

**Event name conventions**:

- **Use PascalCase (recommended)**: e.g., `PageView`, `UserLogin`, `AddToCart`
- **Use "Object + Action" format**: e.g., `ProductView` (product viewed), `OrderCreate` (order created)
- **Keep semantics clear**: Event names should clearly express the specific user action
- **Avoid abbreviations**: Unless they are widely recognized abbreviations (e.g., `URL`, `ID`)
- **Historical compatibility**: If existing tracking data uses snake_case, you may continue with that style, but always **maintain consistency** within the same application
- **Preset Events**: SDK preset system events (e.g., `$Identify`, `$ABImpress`) uniformly use the `$` prefix + PascalCase format

**Recommended examples**:
```javascript
PageView          // Page view
ProductView       // Product view
AddToCart         // Add to cart
OrderCreate       // Order creation
Purchase          // Purchase
UserSignup        // User registration
VideoPlay         // Video play
ButtonClick       // Button click
```

**Not recommended examples**:
```javascript
page_view         // snake_case (unless there is historical data)
ViewProduct       // Should use "Object + Action" format
Click             // Too broad
PV                // Avoid abbreviations
purchase_2026     // Do not include dates in event names
```

**Historical data compatibility note**:

If your application already uses snake_case format (e.g., `page_view`, `add_to_cart`) and has a large amount of historical data, you may continue using that format, but please note:
- **Maintain consistency**: All events within the same application must use the same naming style
- **New applications**: For new projects, PascalCase is strongly recommended
- **Standardize within the team**: Establish a unified naming convention document within the team and strictly enforce it

### 3. Event Property Naming Conventions

**Property name conventions**:

- **Use snake_case**: e.g., `order_id`, `total_amount`, `page_url`
- **Keep names concise and descriptive**: e.g., `product_name` rather than `pn`
- **Avoid conflicts with Preset Properties**: Do not use the `$` prefix (reserved for the system)
- **Standardize units and formats**: e.g., use a consistent currency unit for amounts, use seconds consistently for time

**Correct examples**:
```javascript
(Recommended) order_id          // Order ID
(Recommended) total_amount      // Total amount
(Recommended) product_name      // Product name
(Recommended) page_url          // Page URL
(Recommended) video_duration    // Video duration (seconds)
```

**Incorrect examples**:
```javascript
(Not recommended) OrderID           // Should use snake_case
(Not recommended) totalAmount       // Should use snake_case
(Not recommended) $custom_prop      // Avoid the $ prefix
(Not recommended) mp_source         // Avoid the mp_ prefix
(Not recommended) pn                // Avoid abbreviations
```

### 4. Use Explicit Property Value Types

Property value data types should remain consistent; avoid mixing different types.

**Supported data types**:

Sensors Wave supports the following five data types:

| Data Type | Description | Example |
|---------|------|------|
| **String** | Text data | `"alipay"`, `"electronics"` |
| **Number (Numeric)** | Integer or floating point | `299.00`, `42` |
| **Boolean** | True or false | `true`, `false` |
| **Datetime** | Date and time | `"2026-01-21T10:30:00Z"` |
| **List** | Array containing multiple values | `["red", "blue"]`, `[1, 2, 3]` |

**Recommended practices**:
- Use the same data type for the same property across all events
  - `total_amount` should always be Numeric
  - `payment_method` should always be String
  - `is_member` should always be Boolean

**Practices to avoid**:
- Mixing different data types for the same property
  - `total_amount: "299"` and `total_amount: 299` (String vs Number)
  - `is_member: "true"` and `is_member: true` (String vs Boolean)

### 5. Use Super Properties

Super Properties are Event Properties that are tracked with nearly every event (typically > 80%), providing uniform contextual information.

**Common Super Properties**:

- **Device information**: `device_type`, `os_name`, `os_version`, `browser_name`
- **Application information**: `app_version`, `app_build_number`
- **Geolocation**: `country`, `region`, `city`
- **Traffic source**: `utm_source`, `utm_medium`, `utm_campaign`
- **Session information**: `session_id`, `referrer`

**Code example**:

```javascript
// Register Super Properties; all subsequent events will automatically include these properties
sensorswave.registerSuperProperties({
  app_version: '2.5.0',
  device_type: 'mobile',
  os_name: 'iOS',
  os_version: '17.2'
});

// Subsequently tracked events will automatically include Super Properties
sensorswave.trackEvent('Purchase', {
  order_id: 'ORDER-001',
  total_amount: 299.00
});
// The actual event sent includes:
// { order_id, total_amount, app_version, device_type, os_name, os_version }
```

## Event Property Design Best Practices

### 1. Consider Analysis Needs When Designing Event Properties

Before adding Event Properties, think about how you will use these properties for analysis.

**Analysis dimensions**:
- **Filtering**: Which events do you need to filter? (e.g., only orders with amount > 100)
- **Grouping**: What dimensions do you need to group by? (e.g., by payment method, product category)
- **Aggregation**: What Metrics do you need to calculate? (e.g., total amount, average order value)

**Example: Purchase event property design**:

```javascript
sensorswave.trackEvent('Purchase', {
  // Unique identifier
  order_id: 'ORDER-2026-001',

  // Amount-related (for aggregation analysis)
  total_amount: 299.00,
  discount_amount: 20.00,
  tax_amount: 15.00,
  currency: 'CNY',

  // Product information (for grouping analysis)
  product_category: 'electronics',
  product_brand: 'Apple',
  item_count: 2,

  // Payment information (for filtering and grouping)
  payment_method: 'alipay',
  payment_status: 'success',

  // Channel information (for source analysis)
  order_source: 'mobile_app',
  referrer_channel: 'wechat'
});
```

### 2. Maintain Property Value Consistency

Property values with the same semantics should use a unified format and wording.

**Recommended practices**:
- Establish enumeration standards for property values
  - `payment_method` values should be standardized as: `alipay`, `wechat`, `credit_card`
  - `order_status` values should be standardized as: `pending`, `paid`, `shipped`, `completed`
- Use lowercase letters with underscores
  - (Recommended) `payment_method: "credit_card"`
  - (Not recommended) `payment_method: "Credit Card"` or `"CreditCard"`

**Practices to avoid**:
- Using multiple representations for the same property value
  - Mixing `payment_method: "alipay"`, `"Alipay"`, `"ALIPAY"`
  - Mixing `order_status: "paid"`, `"PAID"`, `"Paid"`

### 3. Avoid Dynamic Property Names

Do not dynamically generate property names based on business data. Instead, use fixed property names with dynamic property values.

**Recommended practice**:
```javascript
// Use fixed property names with dynamic property values
sensorswave.trackEvent('Purchase', {
  product_category: 'electronics',
  product_name: 'Wireless Bluetooth Headphones'
});
```

**Practice to avoid**:
```javascript
// Do not use dynamic property names
sensorswave.trackEvent('Purchase', {
  'product_electronics': 'Wireless Bluetooth Headphones'
});
```

### 4. Control Property Quantity

Although Sensors Wave supports up to 255 properties per event, that doesn't mean you should track every possible property.

**Recommended practices**:
- Keep 5-20 core properties per event
- Only track properties that add analytical value
- Regularly review and clean up unused properties

**Practices to avoid**:
- Reporting all database fields as Event Properties
- Tracking redundant or duplicate property information

### 5. Handle Sensitive Information

Do not store sensitive personal information or security credentials in Event Properties.

**Sensitive information to avoid tracking**:
- Passwords, access tokens, API keys
- Full credit card numbers, ID numbers
- Unencrypted personal health information
- Full phone numbers, email addresses (unless in compliance with privacy policies)

**Recommended practices**:
- Use masked or hashed values
  - `phone_last4: "8888"` (keep only last 4 digits)
  - `email_domain: "gmail.com"` (keep only domain)
- Use identifiers instead of raw values
  - `user_id: "U123456"` instead of full personal information

## Code Examples

### JavaScript SDK Example

```javascript
// Basic event tracking
sensorswave.trackEvent('PageView', {
  page_url: window.location.href,
  page_title: document.title,
  page_category: 'product',
  referrer: document.referrer
});

// Purchase event
sensorswave.trackEvent('Purchase', {
  order_id: 'ORDER-2026-001',
  total_amount: 299.00,
  currency: 'CNY',
  payment_method: 'alipay',
  product_category: 'electronics',
  item_count: 2
});

// Using Super Properties
sensorswave.registerSuperProperties({
  app_version: '2.5.0',
  platform: 'web',
  language: 'zh-CN'
});

// Set User Properties
sensorswave.setUserProfile({
  user_id: 'user_12345',
  name: 'John',
  age: 28,
  city: 'Beijing',
  membership_level: 'gold'
});

// Set Once User Properties (registration info)
sensorswave.setOnceUserProfile({
  registration_date: '2025-01-15',
  first_channel: 'wechat'
});

// Increment User Properties (after purchase)
sensorswave.incrementUserProfile({
  total_purchase_count: 1,
  total_spent: 299.00
});

// Append to list properties (browsing history)
sensorswave.appendUserProfile({
  browsed_categories: 'electronics'
});
```

### Go SDK Example

```go
// Basic event tracking
user := sensorswave.User{
    LoginID: "user123",
}

err := client.TrackEvent(user, "Purchase", sensorswave.Properties{
    "order_id":         "ORDER-2026-001",
    "total_amount":     299.00,
    "currency":         "CNY",
    "payment_method":   "alipay",
    "product_category": "electronics",
    "item_count":       2,
})

// Using the full event structure
event := sensorswave.NewEvent("anon-123", "user123", "ProductView").
    WithProperties(sensorswave.NewProperties().
        Set("product_id", "SKU-12345").
        Set("product_name", "Wireless Bluetooth Headphones").
        Set("category", "electronics"))

err = client.Track(event)

// Set user profile properties
err = client.ProfileSet(user, sensorswave.Properties{
    "name":             "John",
    "age":              28,
    "city":             "Beijing",
    "membership_level": "gold",
})

// Set Once user profile properties
err = client.ProfileSetOnce(user, sensorswave.Properties{
    "registration_date": "2025-01-15",
    "first_channel":     "wechat",
})

// Increment user profile properties
err = client.ProfileIncrement(user, sensorswave.Properties{
    "total_purchase_count": 1,
    "total_spent":          299.00,
})
```

### Android SDK Example

```java
// Basic event tracking
JSONObject properties = new JSONObject();
properties.put("order_id", "ORDER-2026-001");
properties.put("total_amount", 299.00);
properties.put("currency", "CNY");
properties.put("payment_method", "alipay");
properties.put("item_count", 2);

sensorswave.track("Purchase", properties);

// Set Super Properties
JSONObject superProperties = new JSONObject();
superProperties.put("app_version", "2.5.0");
superProperties.put("platform", "android");
sensorswave.registerSuperProperties(superProperties);

// Set User Properties
JSONObject userProperties = new JSONObject();
userProperties.put("name", "John");
userProperties.put("age", 28);
userProperties.put("city", "Beijing");
userProperties.put("membership_level", "gold");
sensorswave.setUserProfile(userProperties);

// Set Once User Properties
JSONObject onceProperties = new JSONObject();
onceProperties.put("registration_date", "2025-01-15");
onceProperties.put("first_channel", "wechat");
sensorswave.setOnceUserProfile(onceProperties);

// Increment User Properties
JSONObject incrementProperties = new JSONObject();
incrementProperties.put("total_purchase_count", 1);
incrementProperties.put("total_spent", 299.00);
sensorswave.incrementUserProfile(incrementProperties);
```

### iOS SDK Example

```swift
// Basic event tracking
let properties: [String: Any] = [
    "order_id": "ORDER-2026-001",
    "total_amount": 299.00,
    "currency": "CNY",
    "payment_method": "alipay",
    "item_count": 2
]

sensorswave.track("Purchase", properties: properties)

// Set Super Properties
let superProperties: [String: Any] = [
    "app_version": "2.5.0",
    "platform": "ios"
]
sensorswave.registerSuperProperties(superProperties)

// Set User Properties
let userProperties: [String: Any] = [
    "name": "John",
    "age": 28,
    "city": "Beijing",
    "membership_level": "gold"
]
sensorswave.setUserProfile(userProperties)

// Set Once User Properties
let onceProperties: [String: Any] = [
    "registration_date": "2025-01-15",
    "first_channel": "wechat"
]
sensorswave.setOnceUserProfile(onceProperties)

// Increment User Properties
let incrementProperties: [String: Any] = [
    "total_purchase_count": 1,
    "total_spent": 299.00
]
sensorswave.incrementUserProfile(incrementProperties)
```

## Data Limits

Understanding the data limits of Sensors Wave helps you better design events and properties:

| Limit | Value | Description |
|-------|-------|------|
| **Event type count** | 1,000 | Maximum number of distinct event names |
| **Properties per event** | 255 | Maximum number of Event Properties associated with a single event |
| **Total Event Properties** | 500 | Maximum total number of all Event Properties |
| **Total User Properties** | 500 | Maximum total number of all User Properties |
| **Property name length** | 255 characters | Exceeding this will be truncated |
| **Property value length (String)** | 255 characters | Exceeding this will be truncated |
| **List property size (Event Property)** | 8 KB | Exceeding this will be truncated |
| **List property size (User Property)** | 256 KB | Exceeding this will be truncated |

> **Tips**:
> - The event type limit is 1,000. It is recommended to use generic event names with properties to distinguish details, rather than creating new events for every minor variation
> - Event Properties and User Properties each have a limit of 500. It is recommended to regularly clean up unused properties
> - While a single event can have 255 properties, keeping 5-20 core properties is recommended to ensure data simplicity

## User Property Design Best Practices

### 1. Choose the Right Property Type

Choose the correct User Property type based on the nature of the information and usage scenario.

**Standard User Properties (Profile Properties)**:
- Describe basic user characteristics and status
- Set using the `setUserProfile()` method
- Suitable for most scenarios

**Set Once Properties**:
- Only take effect on first set; subsequent sets will not overwrite
- Use the `setOnceUserProfile()` method
- Suitable for immutable information like registration time, first source

**Increment Properties**:
- Perform increment operations on numeric properties
- Use the `incrementUserProfile()` method
- Suitable for cumulative Metrics like purchase count, total spend

**List Properties (Append)**:
- Append new values to a list, preserving history
- Use the `appendUserProfile()` method
- Suitable for browsed categories, used features, etc.

**Example**:

```javascript
// Set Once - registration information
sensorswave.setOnceUserProfile({
  registration_date: "2026-01-22",
  first_channel: "wechat",
  first_device: "iOS"
});

// Standard Set - updatable user information
sensorswave.setUserProfile({
  city: "Beijing",
  membership_level: "gold",
  last_login_date: "2026-01-22"
});

// Increment - business Metrics
sensorswave.incrementUserProfile({
  total_purchase_count: 1,
  total_spent: 299.00,
  login_days: 1
});

// Append - behavior history
sensorswave.appendUserProfile({
  browsed_categories: "electronics",
  used_features: "video_chat"
});
```

### 2. Keep User Properties Up-to-Date

User Properties should reflect the user's current state and need to be updated in a timely manner.

**Recommended practices**:
- Update User Properties when key business events occur
  - After a user completes a purchase, update `total_purchase_count` and `total_spent`
  - After a user upgrades membership, update `membership_level` and `membership_upgrade_date`
  - After a user updates personal information, sync the corresponding User Properties

- Periodically batch-update calculated properties
  - Calculate user active days, last-30-day spending, etc. daily
  - Periodically update user lifecycle stage, churn risk score, etc.

**Code example**:

```javascript
// Sync User Properties during a purchase event
sensorswave.trackEvent('Purchase', {
  order_id: 'ORDER-001',
  total_amount: 299.00
});

// Simultaneously update cumulative consumption data
sensorswave.incrementUserProfile({
  total_purchase_count: 1,
  total_spent: 299.00
});

sensorswave.setUserProfile({
  last_purchase_date: new Date().toISOString(),
  latest_purchase_amount: 299.00
});
```

### 3. Design Properties for Cohorts

When designing User Properties, consider future Cohort and segmentation needs.

**Common Cohort dimensions**:

| Cohort Type | Related Properties | Cohort Example |
|---------|---------|---------|
| **Demographic Cohort** | `age`, `gender`, `city`, `occupation` | Female users aged 25-35 in Beijing |
| **Behavioral Cohort** | `total_purchase_count`, `avg_order_value`, `last_active_date` | Users active in the last 30 days with 3+ purchases |
| **Value Cohort** | `total_spent`, `lifetime_value`, `membership_level` | Gold members with cumulative spending over $5,000 |
| **Lifecycle Cohort** | `registration_date`, `days_since_last_purchase`, `churn_risk` | Users registered 90+ days ago but not logged in for 30 days (churn risk) |
| **Preference Cohort** | `favorite_categories`, `preferred_payment_method`, `content_preferences` | Users who prefer electronics and use Alipay |

**Example**:

```javascript
// Design User Properties that support fine-grained Cohorts
sensorswave.setUserProfile({
  // Demographics
  age: 28,
  gender: "female",
  city: "Beijing",

  // Behavioral Metrics
  total_purchase_count: 15,
  avg_order_value: 458.50,
  last_active_date: "2026-01-22",
  active_days_last_30: 18,

  // Value Metrics
  total_spent: 6877.50,
  lifetime_value: 8500.00,
  membership_level: "gold",

  // Lifecycle
  registration_date: "2025-01-15",
  days_since_registration: 372,
  days_since_last_purchase: 5,
  user_lifecycle_stage: "active",

  // Preferences
  favorite_categories: ["electronics", "books"],
  preferred_payment_method: "alipay",
  preferred_delivery_time: "evening"
});
```

### 4. Avoid Sensitive Information

User Properties should not contain sensitive personally identifiable information (PII).

**Sensitive information to avoid storing**:
- Full name, ID number, passport number
- Full phone number, full email address
- Passwords, payment passwords, security question answers
- Credit card numbers, bank account numbers
- Detailed home address, GPS coordinates

**Recommended alternatives**:
- Use encrypted or masked identifiers
  - `user_id: "U123456"` instead of real name
  - `phone_area_code: "010"` or `phone_last4: "8888"` instead of full phone number
  - `email_domain: "gmail.com"` instead of full email

- Use derived or aggregated data
  - `age: 28` or `age_group: "25-30"` instead of birth date
  - `city: "Beijing"` instead of detailed address
  - `region: "North China"` instead of precise location

### 5. User Property Naming Conventions

Like Event Properties, User Properties should follow consistent naming conventions.

**Naming conventions**:
- Use snake_case: `membership_level`, `total_spent`
- Keep semantics clear: `registration_date` rather than `reg_dt`
- Avoid the `$` prefix (reserved for the system)
- Boolean types use `is_`, `has_` prefix: `is_vip`, `has_purchased`
- Datetime types use `_date`, `_time` suffix: `last_login_date`, `registration_date`
- Count types use `_count` suffix: `login_count`, `purchase_count`

**Example**:

```javascript
// Recommended naming
{
  membership_level: "gold",
  total_spent: 5000.00,
  is_vip: true,
  has_purchased: true,
  registration_date: "2025-01-15",
  last_login_date: "2026-01-22",
  total_purchase_count: 15
}

// Not recommended naming
{
  membershipLevel: "gold",     // Should use snake_case
  $custom_field: "value",      // Avoid $ prefix
  reg_dt: "2025-01-15",        // Avoid abbreviations
  vip: true,                   // Should be is_vip
  purchases: 15                // Should be total_purchase_count
}
```

### 6. Control User Property Quantity

Although Sensors Wave supports a large number of User Properties, keep the count reasonable.

**Recommended practices**:
- Maintain 20-50 core User Properties
- Regularly clean up unused properties
- Prioritize high-value, frequently used properties
- Avoid syncing all database fields as User Properties

**Practices to avoid**:
- Creating hundreds of User Properties
- Retaining large numbers of legacy properties
- Storing redundant or computable properties

## Implementation Recommendations

### Event Design Considerations

- **Avoid frequently changing event semantics**: Once an event is defined and in use, its semantics should remain stable. If changes are needed, create a new event and gradually migrate
- **Distinguish the responsibilities of events and properties**: Don't create new events for every minor variation; use properties to distinguish
- **Consider long-term scalability**: When designing events, consider future expansion needs and avoid being overly specific

### Property Design Considerations

**Event Properties**:
- **Avoid property value explosion**: Some properties (e.g., `page_url`, `product_id`) may have tens of thousands of distinct values, which can affect analysis performance. Consider using categories or groups to reduce cardinality
- **Timezone consistency**: Ensure all datetime properties use a consistent timezone (UTC is recommended)
- **Null value handling**: Clearly define how to handle missing or null values; avoid mixing `null`, empty strings, `undefined`, etc.

**User Properties**:
- **Update at the right time**: Ensure User Properties are updated at the correct moment to avoid data inconsistency
  - (Recommended) Update purchase count and spend immediately after a purchase event
  - (Not recommended) Delay updating User Properties by hours or days
- **Choose the correct update operation**:
  - Use `setOnceUserProfile` for immutable properties like registration time
  - Use `incrementUserProfile` for cumulative values like purchase count and spend
  - Use `appendUserProfile` for browsing history, interest tags, etc.
  - Do not use `setUserProfile` for cumulative properties, as it will overwrite the data
- **Avoid semantic conflicts**:
  - Do not use both `total_orders` and `order_count` with overlapping semantics
  - Ensure property names are clear and unambiguous

### Data Quality Monitoring

- **Establish anomaly monitoring**: Monitor event reporting volume, property completeness, and other Metrics; detect anomalies promptly
- **Regular data audits**: Periodically check data quality; identify non-standard events and properties
- **Version management**: Establish version management and rollback mechanisms for SDK upgrades or tracking code changes

## Related Documentation

- [Data Model](data-model.mdx): Understand the role of events, Event Properties, and User Properties in the overall data model
- [Property Data Types](property-data-types.mdx): Learn about the property data types supported by Sensors Wave and their usage guidelines
- [Preset Events and Preset Properties](preset-events-and-properties.mdx): Learn about the Preset Events and Preset Properties automatically collected by Sensors Wave
- [Tracking Strategy](tracking-strategy.mdx): Choose the right tracking approach

---

**Last updated**: January 19, 2026