Skip to main content
Event properties capture user interactions and activities within your application. Unlike user properties (which describe who users are), event properties describe what users do. This documentation outlines how to structure and use event properties effectively.

​
Core Event Structure

Each event in the system follows this data model:
PropertyTypeRequiredDescription
contact_idStringYesA unique user identifier
timestampTimestampYesWhen the event happened in UTC
event_nameStringYesName corresponding to the triggered event
event_instance_idStringNoUnique identifier for this specific event instance
metadataJSONNoAdditional contextual data about the event

​
Common Event Types

Events that track how users move through your application:
  • page_viewed
    • Metadata:
      • page_name: Name of the page (e.g., “homepage”, “product_detail”)
      • page_url: Full URL of the page
      • referrer_url: Where the user came from
      • session_id: Current session identifier
  • feature_accessed
    • Metadata:
      • feature_name: Name of accessed feature (e.g., “search”, “filters”)
      • feature_location: Where in the app the feature appears

​
Transaction Events

Events that track commerce and financial activities:
  • product_viewed
    • Metadata:
      • product_id: Unique product identifier
      • product_name: Name of the product
      • product_category: Category of the product
      • product_price: Current price
      • currency: Currency code (e.g., “USD”)
  • product_added_to_cart
    • Metadata:
      • product_id: Product identifier
      • quantity: Number of items added
      • variant_id: Product variant (if applicable)
      • cart_id: Current cart identifier
      • cart_value: New total cart value
  • checkout_started
    • Metadata:
      • cart_id: Cart identifier
      • cart_value: Total value
      • item_count: Number of items
      • coupon_code: Applied discount code (if any)
  • order_completed
    • Metadata:
      • order_id: Unique order identifier
      • order_value: Total value of order
      • payment_method: Method used (e.g., “credit_card”, “paypal”)
      • shipping_method: Chosen shipping option
      • products: Array of purchased product IDs
      • quantities: Array of quantities (corresponding to products)

​
Messaging Events

Events that track communication and notification activities:
  • message_sent
    • Metadata:
      • message_id: Unique identifier for the message
      • message_type: Type of message (e.g., “text”, “email”, “push”)
      • recipient_id: ID of the recipient
      • template_id: If using a template, the template identifier
      • campaign_id: Associated marketing campaign (if applicable)
  • message_delivered
    • Metadata:
      • message_id: Message identifier
      • delivery_timestamp: When message was delivered
      • delivery_status: Status (e.g., “delivered”, “failed”)
  • message_opened
    • Metadata:
      • message_id: Message identifier
      • open_timestamp: When message was opened
      • device_type: Device used to open (e.g., “mobile”, “desktop”)
  • message_clicked
    • Metadata:
      • message_id: Message identifier
      • link_id: Identifier for the specific link
      • link_url: Target URL
      • click_timestamp: When click occurred

​
Engagement Events

Events that track how users interact with content:
  • content_viewed
    • Metadata:
      • content_id: Content identifier
      • content_type: Type of content (e.g., “article”, “video”)
      • category: Content category
      • duration: Time spent viewing (seconds)
  • video_played
    • Metadata:
      • video_id: Video identifier
      • video_title: Video title
      • duration: Length of video in seconds
      • play_position: Starting position in seconds
      • quality: Selected video quality

​
Account Events

Events tracking user account activities:
  • user_registered
    • Metadata:
      • registration_method: How they signed up (e.g., “email”, “google”)
      • referral_source: Where they came from
      • initial_plan: Selected plan (if applicable)
  • user_logged_in
    • Metadata:
      • login_method: Authentication method used
      • device_type: Type of device used
      • app_version: Application version

​
Industry-Specific Events

​
E-commerce Events

  • product_searched
    • Metadata:
      • search_term: User’s search query
      • filter_applied: Any filters used
      • results_count: Number of results
      • category_context: Category being searched
  • wishlist_updated
    • Metadata:
      • product_id: Product identifier
      • action: “added” or “removed”
      • wishlist_count: New total count
  • review_submitted
    • Metadata:
      • product_id: Product identifier
      • rating: Numerical rating (e.g., 1-5)
      • review_length: Character count of review
      • has_media: Contains photos/videos (boolean)

​
Gaming Events

  • game_started
    • Metadata:
      • game_mode: Selected mode
      • map_id: Game environment
      • character_id: Selected character/class
      • difficulty: Game difficulty
  • level_completed
    • Metadata:
      • level_id: Level identifier
      • score: Achieved score
      • time_taken: Completion time in seconds
      • attempts: Number of attempts
      • stars_earned: Achievement rating
  • in_app_purchase
    • Metadata:
      • item_id: Purchased item identifier
      • item_type: Type of virtual item
      • price: Cost in real currency
      • currency: Currency code
      • purchase_location: Where in game purchase was made

​
Food Delivery Events

  • restaurant_searched
    • Metadata:
      • search_term: Search keywords
      • cuisine_filter: Any cuisine filters applied
      • location: Search location
      • results_count: Number of results
  • menu_item_viewed
    • Metadata:
      • restaurant_id: Restaurant identifier
      • item_id: Menu item identifier
      • item_category: Food category
      • item_price: Price
      • dietary_tags: Array of applicable dietary tags
  • delivery_status_changed
    • Metadata:
      • order_id: Order identifier
      • new_status: Current status (e.g., “preparing”, “out_for_delivery”)
      • estimated_arrival: Updated ETA
      • driver_id: Delivery person identifier
⌘I