Event Types & Schemas
Complete reference for supported event types, data schemas, and parameter requirements. Use this reference when implementing event tracking in ClickBeam or configuring Event Settings.
Supported Event Types
Tandem Beam supports 9 standardized event types that work across all platforms:
Common Event Data Structure
All events share a common base structure with event-specific fields:
{
"event_name": "purchase", // Required: Event type
"event_data": {
"event_id": "unique-id-123", // Required: Unique identifier
"value": 99.99, // Optional: Monetary value
"currency": "USD", // Optional: ISO 4217 code
"transaction_id": "TXN-123", // Optional: Transaction identifier
"content_ids": ["prod-1"], // Optional: Product/content IDs
"content_type": "product", // Optional: Content type
"content_name": "Product Name" // Optional: Content name
},
"user_data": {
"email_hash": "sha256_hash", // Optional: Hashed email
"phone_hash": "sha256_hash" // Optional: Hashed phone
},
"action_source": "website" // Required: Event source
}
Event Type Details
purchase
Track completed purchases and transactions.
Required Fields:
- •
event_id(string) - Unique event identifier
Recommended Fields:
- •
value(number) - Purchase amount - •
currency(string) - ISO 4217 code (USD, EUR, GBP) - •
transaction_id(string) - Order/transaction ID - •
content_ids(array) - Product IDs purchased - •
content_type(string) - "product"
User Data (Optional):
- •
email_hash(string) - Hashed customer email - •
phone_hash(string) - Hashed customer phone
lead
Track form submissions and lead generation events.
Required Fields:
- •
event_id(string) - Unique event identifier
Recommended Fields:
- •
value(number) - Lead value estimate - •
currency(string) - Currency code - •
content_name(string) - Form name or description - •
content_category(string) - Lead category
User Data (Recommended):
- •
email_hash(string) - Lead email (hashed) - •
phone_hash(string) - Lead phone (hashed)
contact
Track contact form submissions and customer inquiries.
Required Fields:
- •
event_id(string) - Unique event identifier
Recommended Fields:
- •
content_name(string) - Form or page name - •
content_category(string) - Contact type/category
sign_up
Track user account registrations and sign-ups.
Required Fields:
- •
event_id(string) - Unique event identifier
Recommended Fields:
- •
method(string) - Registration method (email, social, etc.) - •
content_name(string) - "Account Registration"
add_to_cart
Track when users add products to shopping cart.
Required Fields:
- •
event_id(string) - Unique event identifier
Recommended Fields:
- •
value(number) - Product price - •
currency(string) - Currency code - •
content_ids(array) - Product ID added - •
content_name(string) - Product name - •
content_type(string) - "product"
initiate_checkout
Track when checkout process is initiated.
Required Fields:
- •
event_id(string) - Unique event identifier
Recommended Fields:
- •
value(number) - Cart total value - •
currency(string) - Currency code - •
num_items(number) - Number of items in cart - •
content_ids(array) - Product IDs in cart
page_view
Track page views. Automatically tracked by ClickBeam - manual calls optional.
Required Fields:
- •
event_id(string) - Unique event identifier
Optional Override:
While ClickBeam auto-tracks page views, you can manually call beam('trackPageView', {...})
with custom data. System deduplicates automatically.
view_content
Track product or content page views.
Required Fields:
- •
event_id(string) - Unique event identifier
Recommended Fields:
- •
content_ids(array) - Viewed product/content IDs - •
content_name(string) - Product/content name - •
content_type(string) - "product", "article", etc. - •
content_category(string) - Product category
phone_call
Tracks phone calls received via Invoca. Created automatically when Invoca sends a post-call webhook. If the call results in a sale, a separate purchase event is also created with the sale amount.
Automatically Populated Fields:
- •
transaction_id(string) - Invoca transaction ID - •
call_duration(number) - Call length in seconds - •
call_status(string) - Call result (e.g., "sale", "no_sale") - •
promo_number(string) - Invoca tracking phone number
Sale Fields (when call results in purchase):
- •
value(number) - Sale amount - •
currency(string) - Currency code (e.g., "USD")
Session Matching:
- •
beam_session_id- Direct session match via ClickBeam injection into Invoca poolParams - • If no session match, the event is still recorded in Intelligence for call volume tracking
Automatically Tracked Fields
In addition to event_data, Tandem Beam automatically captures contextual information:
Browser & Device Data
- •
user_agent- Browser identification - •
ip_address- User IP (hashed) - •
screen_size- Device screen dimensions - •
viewport_size- Browser viewport - •
language- Browser language - •
timezone- User timezone
Session & Attribution
- •
url- Page URL where event occurred - •
referrer- Previous page URL - •
utm_params- UTM campaign parameters - •
query_params- URL query string - •
laser_beam_session- Session ID - •
originating_platform- Platform attribution - •
vendor_ids- Platform click IDs - •
tandem_tracking- Source attribution metadata
Field Data Types & Validation
Data Type Requirements
| Field | Type | Example |
|---|---|---|
event_id |
string | "purchase-12345" |
value |
number | 99.99 |
currency |
string (3 chars) | "USD", "EUR", "GBP" |
content_ids |
array of strings | ["prod-1", "prod-2"] |
email_hash |
string (64 chars) | SHA-256 hash |
phone_hash |
string (64 chars) | SHA-256 hash |
Validation Notes
- • Numbers: Use numeric types (99.99) not strings ("99.99")
- • Currency: Must be valid ISO 4217 codes, uppercase preferred
- • PII Hashing: Raw email/phone will be rejected by API (400 error)
- • Event IDs: Should be unique per event to prevent deduplication issues
Next Steps
Use these event schemas when implementing ClickBeam tracking or creating Event Settings.