Events & Properties

Overview

Events are the foundation of analytics in Cryptique. Every user action—from page views to transactions—is captured as an event with associated properties.

Event Structure

Every event has this structure:

{
  // Required
  "event_name": "swap_completed",
  "distinct_id": "user_12345",
  "timestamp": "2024-01-15T10:30:00.000Z",
  
  // Auto-captured (default properties)
  "session_id": "sess_abc123",
  "current_url": "https://app.example.com/swap",
  "browser_name": "Chrome",
  "country": "US",
  // ... more default properties
  
  // Custom (your properties)
  "properties": {
    "input_token": "ETH",
    "output_token": "USDC", 
    "amount": 1.5,
    "slippage": 0.5
  }
}

Event Types

Auto-Events

Captured automatically only when auto-events="true" (or Cryptique.enableAutoEvents()). Examples of implemented names:

Event	Trigger (summary)
`page_view`	Load / route
`element_click`	Any click
`rage_click`	Rapid repeated clicks on the same element
`dead_click`	Click with no navigation or DOM change after a short window
`page_scroll`	Increasing scroll depth
`form_submit`	Form submit
`form_validation_error`	Native invalid field
`form_abandoned`	Started a form, left without submit
`media_play` / `media_pause`	Video or audio
`text_selection`	Text highlighted
`copy_action` / `context_menu`	Copy / right-click
`js_error` / `network_error`	Errors (when enabled)
`page_performance`	Core vitals-style summary after load
`exit_intent` / `page_summary`	Engagement / exit aggregates

See Auto-Events for the full catalog, script attributes, and JavaScript API. Custom properties on each event may also include group membership fields merged from set_group / add_group.

Custom Events

Tracked via SDK:

Cryptique.track('swap_completed', {
  input_token: 'ETH',
  output_token: 'USDC',
  amount: 1.5
});

Transaction Events

Generated from indexed smart contracts:

// Auto-generated when transaction detected
{
  "event_name": "contract_interaction",
  "event_category": "transaction",
  "properties": {
    "contract_name": "Swap Router",
    "method_name": "swapExactTokensForTokens",
    "transaction_hash": "0xabc...",
    "chain": "ethereum"
  }
}

Properties

Properties provide context to events. They come in several categories:

Default Properties

Auto-captured on every event:

Identifiers
Location
Device & Browser
Screen & Page
UTM & Web3

Property	Description
`team_id`	Your Cryptique team
`session_id`	Current session
`distinct_id`	User identifier
`website_id`	Site identifier
`event_type`	auto, custom, transaction
`event_name`	Name of the event
`event_category`	Category grouping
`timestamp`	Event time (ISO 8601)

Property	Description
`country`	Country code (US, GB, etc.)
`city`	City name
`region`	State/province
`latitude`	Approximate latitude
`longitude`	Approximate longitude
`timezone`	User timezone

Property	Description
`browser_name`	Chrome, Firefox, Safari, etc.
`browser_version`	Browser version
`os`	Operating system
`os_version`	OS version
`device_type`	desktop, mobile, tablet
`language`	Browser language

Property	Description
`screen_height`	Screen height (px)
`screen_width`	Screen width (px)
`viewport_height`	Viewport height (px)
`viewport_width`	Viewport width (px)
`dpi`	Device pixel ratio
`current_url`	Full page URL
`page_title`	Page title
`uri`	URL pathname
`referrer`	Previous page URL
`initial_referrer`	First referrer in session

Property	Description
`utm_source`	Campaign source
`utm_medium`	Campaign medium
`utm_campaign`	Campaign name
`utm_term`	Campaign term
`utm_content`	Campaign content
`utm_id`	Campaign ID
`is_web3_user`	Has connected wallet
`wallet_address`	Connected wallet (if any)

Custom Properties

Add your own properties to events:

Cryptique.track('purchase_completed', {
  // Strings
  product_name: 'Premium NFT',
  category: 'art',
  
  // Numbers
  price_usd: 150.00,
  quantity: 1,
  
  // Booleans
  is_first_purchase: true,
  used_discount: false,
  
  // Arrays
  tags: ['rare', 'animated', '1of1'],
  
  // Nested objects
  metadata: {
    collection: 'CryptoPunks',
    token_id: 1234
  }
});

Event-Specific Properties

Auto event payloads vary by event_name. Examples: element_click (abbreviated):

{
  "click_coordinates": { "x": 120, "y": 340 },
  "page_x": 120,
  "page_y": 540,
  "scroll_x": 0,
  "scroll_y": 200,
  "document_height": 3200,
  "document_width": 1280,
  "double_click": false,
  "element_category": "button",
  "element_tag_name": "button",
  "element_id": "btn-swap",
  "element_text": "Swap now"
}

page_scroll:

{
  "scroll_depth": 72,
  "max_scroll_reached": 72,
  "scroll_position": 2100,
  "document_height": 3200
}

Wallet lifecycle is not emitted as a built-in auto-event; track it explicitly with Cryptique.walletAddress() and Cryptique.track('wallet_connected', { ... }) if needed.

Property Data Types

Type	Example	Notes
String	`"ethereum"`	Max 255 chars for indexed fields
Number	`1500.50`	Integer or decimal
Boolean	`true` / `false`
Date	`"2024-01-15"`	ISO 8601 date
Datetime	`"2024-01-15T10:30:00Z"`	ISO 8601 with time
Array	`["ETH", "USDC"]`	Homogeneous type recommended
Object	`{name: "...", value: 100}`	Nested properties

Best Practices

Event Naming

Use snake_case with clear action verbs:

// ✅ Good
'swap_completed'
'nft_minted'
'liquidity_added'
'onboarding_step_completed'

// ❌ Avoid
'SwapCompleted'      // PascalCase
'swap-completed'     // kebab-case
'swap'               // Too vague
'user clicked swap'  // Spaces, unclear

Property Naming

// ✅ Good
{
  input_token: 'ETH',
  output_token: 'USDC',
  amount_usd: 1500.00,
  slippage_percent: 0.5
}

// ❌ Avoid
{
  inputToken: 'ETH',      // camelCase
  'Output Token': 'USDC', // Spaces
  amt: 1500.00,           // Abbreviated
  slippage: 0.5           // Missing unit
}

Property Values

// ✅ Good - Consistent, specific
{
  status: 'completed',     // Lowercase enum
  chain: 'ethereum',       // Lowercase
  amount: 1500.50,         // Number for math
  is_whale: true           // Boolean prefix
}

// ❌ Avoid
{
  status: 'COMPLETED',     // Inconsistent case
  chain: 'Ethereum',       // Inconsistent case
  amount: '1500.50',       // String for number
  whale: 'yes'             // String for boolean
}

High-Cardinality Properties

Avoid properties with unlimited unique values:

// ❌ High cardinality - Don't do this
{
  transaction_hash: '0xabc...',  // Unique per event
  user_input: 'arbitrary text',  // Unlimited values
  timestamp_ms: 1705312200000    // Use timestamp field
}

// ✅ Better - Category or bucket
{
  transaction_status: 'confirmed',  // Limited values
  input_length: 'medium',           // Bucketed
  // Use built-in timestamp instead
}

Limits

Limit	Value
Event name length	255 characters
Property name length	255 characters
String property value	8,192 characters
Properties per event	255
Array items	255
Object nesting depth	5 levels

Next Steps

Track Events

Learn the track() method

Auto-Events

Automatic event names and configuration

Groups

Group keys, membership, and enrichment

Default Properties

Full property reference

INTRO

DATA IN

DATA MODEL

BEST PRACTICES

Events & Properties

Overview

Event Structure

Event Types

Auto-Events

Custom Events

Transaction Events

Properties

Default Properties

Custom Properties

Event-Specific Properties

Property Data Types

Best Practices

Event Naming

Property Naming

Property Values

High-Cardinality Properties

Limits

Next Steps

Track Events

Auto-Events

Groups

Default Properties

INTRO

DATA IN

DATA MODEL

BEST PRACTICES

​Overview

​Event Structure

​Event Types

​Auto-Events

​Custom Events

​Transaction Events

​Properties

​Default Properties

​Custom Properties

​Event-Specific Properties

​Property Data Types

​Best Practices

​Event Naming

​Property Naming

​Property Values

​High-Cardinality Properties

​Limits

​Next Steps

Track Events

Auto-Events

Groups

Default Properties

Overview

Event Structure

Event Types

Auto-Events

Custom Events

Transaction Events

Properties

Default Properties

Custom Properties

Event-Specific Properties

Property Data Types

Best Practices

Event Naming

Property Naming

Property Values

High-Cardinality Properties

Limits

Next Steps