Skip to main content

User Object

Overview​

The user object contains detailed information about customers and visitors as they interact with your website or application, enabling comprehensive user identification, personalization, and analytics. This object plays a crucial role in understanding visitor behavior, preferences, and engagement patterns while supporting compliance with data privacy regulations through automatic hashing and anonymization features.

Each user object represents a single customer or visitor with their associated contact information, demographic details, order history, and custom properties that enable precise user segmentation and personalized experiences across all touchpoints.

Core Structure​

The user object consists of several logical groups of properties:

  • Core Identification - Essential user IDs and contact information
  • Personal Information - Names and demographic details
  • Location Data - Address and geographic information
  • Order History - Purchase behavior and lifetime value metrics
  • Custom Properties - Flexible attributes for business-specific segmentation

Complete Reference​

user object

id string recommended

info

Unique customer identifier in your system.

id: "CUSTOMER_INTERNAL_ID"

email string|array recommended

info

Customer email address(es) provided in plaintext or as SHA-256 hashed values.

email: "[email protected]" 
// or
email: ["[email protected]", "[email protected]"]
// or
email: ["3e1ufd1rdnh8l1rfz6xlreyw2yryd4zrf8zsk1pxh2x8wbsp2mw1g93rs5nx68dq"]

phone string|array recommended

info

Customer phone number(s) in E.164 format (plaintext) or as SHA-256 hashed values.

phone: "+40712345678"
// or
phone: ["+40712345678", "+4079876543"]
// or
phone: ["unw5r66oikql4n4tlg2c54bkd2npephsbwwhxuoxreu6ph8uv6k424y9x15opy9y"]

first_name string recommended

info

Customer first name

first_name: "John"

last_name string recommended

info

Customer last name

last_name: "Doe"

country string

info

Country name or ISO country code

country: "Romania"

region string recommended

info

State, province, or region name

region: "Bucuresti"

city string recommended

info

City or locality name

city: "Bucuresti"

street string

info

Street address including number

street: "Strada Principala 1"

postal_code string

info

Postal code or ZIP code

postal_code: "700000"

orders_total_number number recommended

info

Cumulative number of orders placed by this user

orders_total_number: 5

orders_canceled_number number recommended

info

Cumulative number of orders placed and canceled by this user

orders_canceled_number: 0

orders_total_value number recommended

info

Cumulative lifetime user orders value (decimal format: 2500.50)

orders_total_value: 1234.99

orders_refunded_value number recommended

info

Cumulative lifetime user orders value canceled (decimal format: 2500.50)

orders_refunded_value: 250.99

predicted_value number

info

Predicted lifetime value of a customer for your business

predicted_value: 100.99

created_at number recommended

info

Timestamp in milliseconds since Unix epoch representing the first time the user was recorded

created_at: 1754926521690

properties object recommended

info

Custom Customer Properties Examples

User Segmentation

Use the properties object to store custom user attributes, with property names defined by each business as needed, that enable advanced segmentation, personalization, and analytics across your marketing campaigns.

properties: {
  customer_type: "returning",
  membership_level: "platinum",
  preferred_category: ["electronics", "fashion"],
  last_purchase_date: "2024-12-15",
  average_order_value: "350.00",
  payment_method_preference: "card",
  registration_date: "2023-06-15"
}

Implementation Examples​

{
  // Customer identification
  id: "CUST_ECOM_12345",
  email: ["[email protected]", "[email protected]"],
  phone: ["+1555123456", "+1555987654"],
  first_name: "Sarah",
  last_name: "Johnson",
  
  // Location information
  country: "United States",
  region: "California",
  city: "San Francisco",
  street: "123 Market Street, Apt 4B",
  postal_code: "94105",
  
  // Purchase history
  orders_total_number: 8,
  orders_canceled_number: 1,
  orders_total_value: 2156.75,
  orders_refunded_value: 299.99,
  predicted_value: 3500.00,
  created_at: 1640995200000,
  
  // Customer segmentation
  properties: {
    customer_segment: "loyal",
    acquisition_channel: "paid_search",
    preferred_categories: ["electronics", "home_garden"],
    loyalty_tier: "gold",
    marketing_consent: true,
    preferred_payment_method: "credit_card",
    average_order_value: 269.59,
    purchase_frequency: "quarterly"
  }
}

Contact Information Strategies​

The user object supports multiple formats for contact information to ensure maximum compatibility and privacy options:

{
  id: "CUST_MULTI_001",
  // Multiple email addresses
  email: [
    "[email protected]",      // Primary email
    "[email protected]",         // Work email
    "[email protected]"          // Alternative email
  ],
  // Multiple phone numbers
  phone: [
    "+1555123456",              // Primary phone
    "+1555987654"               // Alternative phone
  ],
  first_name: "Jennifer",
  last_name: "Wilson"
}

Customer Lifecycle Tracking​

The user object enables comprehensive customer lifecycle analysis through order history and value metrics:

{
  id: "CUST_NEW_001",
  email: ["[email protected]"],
  first_name: "Emma",
  last_name: "Thompson",
  
  // New customer metrics
  orders_total_number: 1,
  orders_canceled_number: 0,
  orders_total_value: 89.99,
  orders_refunded_value: 0.00,
  predicted_value: 450.00,
  created_at: 1704067200000,   // Recent creation date
  
  properties: {
    customer_segment: "new",
    acquisition_channel: "social_media",
    first_purchase_category: "fashion",
    onboarding_completed: true,
    newsletter_subscribed: true
  }
}

Geographic and Demographic Segmentation​

European Customer Examples​

{
  id: "CUST_DE_001",
  email: ["[email protected]"],
  first_name: "Hans",
  last_name: "Mueller",
  
  // German location
  country: "Germany",
  region: "Baden-Württemberg", 
  city: "Stuttgart",
  street: "Königstraße 123",
  postal_code: "70173",
  
  properties: {
    communication_language: "de",
    currency_preference: "EUR",
    gdpr_consent: true,
    marketing_consent: false,
    timezone: "Europe/Berlin",
    vat_exempt: false
  }
}

Custom Properties Strategy​

User properties enable powerful segmentation and personalization capabilities:

properties: {
  // Shopping behavior
  browsing_pattern: "research_heavy",
  cart_abandonment_rate: 0.25,
  price_sensitivity: "medium",
  seasonal_shopper: true,
  
  // Engagement metrics
  email_open_rate: 0.45,
  social_media_follower: true,
  review_contributor: true,
  referral_program_member: true,
  
  // Preferences
  preferred_contact_method: "email",
  notification_frequency: "weekly",
  content_preference: ["video", "articles"],
  device_preference: "mobile"
}

Privacy and Compliance Features​

Automatic Data Protection​

The user object includes built-in privacy protection:

// Data is automatically hashed with SHA-256
{
  email: "[email protected]",
  // Becomes: "3e1ufd1rdnh8l1rfz6xlreyw2yryd4zrf8zsk1pxh2x8wbsp2mw1g93rs5nx68dq"
  
  phone: "+1555123456",
  // Becomes: "unw5r66oikql4n4tlg2c54bkd2npephsbwwhxuoxreu6ph8uv6k424y9x15opy9y"
}
{
  id: "CUST_CONSENT_001",
  email: ["[email protected]"],
  properties: {
    // Consent tracking
    gdpr_consent: true,
    marketing_consent: false,
    analytics_consent: true,
    cookie_consent: "essential_only",
    consent_date: "2024-01-15",
    
    // Privacy preferences
    data_retention_period: "2_years",
    right_to_be_forgotten: false,
    data_portability_requested: false,
    communication_opt_out: ["sms", "phone"]
  }
}

Usage in Events​

The user object is used across all event types for identification and personalization:

Integration Patterns​

Progressive Data Collection​

// Initial anonymous visitor
{
  id: "ANON_12345",
  properties: {
    visitor_type: "anonymous",
    session_count: 1,
    pages_viewed: 3
  }
}

// After email capture
{
  id: "ANON_12345",
  email: ["[email protected]"],
  properties: {
    visitor_type: "identified",
    lead_source: "newsletter_signup",
    session_count: 1
  }
}

// After first purchase
{
  id: "CUST_12345",            // Updated ID
  email: ["[email protected]"],
  first_name: "John",
  last_name: "Doe",
  orders_total_number: 1,
  orders_total_value: 89.99,
  properties: {
    customer_segment: "new",
    acquisition_channel: "email_marketing"
  }
}

Best Practices​

Data Quality​

  • Consistent Identification - Use stable user IDs across all events and sessions
  • Complete Contact Information - Provide multiple contact methods when available
  • Accurate Order History - Maintain up-to-date purchase and value metrics
  • Relevant Properties - Include properties that enable meaningful segmentation

Privacy Compliance​

  • Consent Management - Respect user privacy preferences and consent status
  • Data Minimization - Collect only necessary information for business purposes
  • Secure Transmission - Always use HTTPS for transmitting user data
  • Regular Audits - Monitor data collection practices for compliance

Performance Optimization​

  • Essential Data First - Prioritize critical identification fields
  • Incremental Enhancement - Add additional data as it becomes available
  • Property Standardization - Use consistent naming for custom properties
  • Data Validation - Ensure email and phone number formats are correct

Customer Experience​

  • Personalization - Use customer data to improve user experience
  • Segmentation Strategy - Group customers for targeted marketing
  • Lifecycle Tracking - Monitor customer journey and value progression
  • Preference Management - Honor customer communication and privacy preferences