Code Examples

Developer reference for custom events, dataLayer integration, and event structures

This page provides comprehensive code examples for developers integrating with ListenLayer.

Quick Links: SDK API • DataLayer Events • DataLayer Push Back • Event Structure

---

Custom Events

Send custom events to ListenLayer using the SDK API or dataLayer. Custom events are available in your data warehouse and reporting.

SDK API: Custom Events

Use _ll.track() to send custom events directly.

Direct custom events reduce data loss by minimizing latency between event emittance and processing. Use this for critical events, or if you see inaccuracies in your data.

Basic Usage

// Simple event
_ll.track('button_clicked');

// With parameters
_ll.track('feature_used', {
  feature: 'export',
  format: 'csv',
  record_count: 150
});

// With revenue value
_ll.track('subscription_upgraded', {
  from_plan: 'starter',
  to_plan: 'enterprise',
  value: 299
});

Waiting for SDK Ready

When calling SDK methods early in the page lifecycle, use _ll.waitFor() to ensure ListenLayer is ready before executing your code.

// Callback-based (recommended)
_ll.waitFor(function() {
  _ll.track('page_loaded', { section: 'pricing' });
});

// Promise-based (modern syntax)
_ll.ready().then(() => {
  _ll.track('app_ready', { component: 'dashboard' });
});

// With async/await
async function trackEvent() {
  await _ll.ready();
  _ll.track('feature_ready', { module: 'checkout' });
}

Multiple Calls

You can safely call _ll.waitFor() multiple times—each callback runs when ready:

_ll.waitFor(function() {
  _ll.track('widget_loaded', { id: 'hero-video' });
});

_ll.waitFor(function() {
  _ll.ecommerce.viewItem({
    items: [{ item_id: 'SKU-001', item_name: 'Widget Pro' }]
  });
});

_ll.waitFor(function() {
  _ll.identifyPerson({ email: user.email });
});

With DOM Events

Combine waitFor with DOM events for guaranteed execution:

document.addEventListener('DOMContentLoaded', function() {
  _ll.waitFor(function() {
    _ll.track('dom_ready', { page: 'checkout' });
  });
});

If you're using GTM or loading ListenLayer asynchronously, also add the stub script to catch early calls. See Installation: Custom Events for setup instructions.

Parameter Rules

Rule	Limit
Max parameters per event	50
Key max length	50 characters (truncated)
String value max length	500 characters (truncated)
Allowed value types	string, number, boolean, null

Parameters must be flat. Nested objects and arrays are not supported and will be skipped. Use flat key-value pairs only.

Event Name Rules

Rule	Details
Must start with	Letter (a-z, A-Z)
Allowed characters	Alphanumeric, underscore, dot, hyphen
Max length	100 characters
Cannot use	Reserved names (see below)

Reserved Event Names

These names are reserved for ListenLayer's automatic tracking and cannot be used with _ll.track():

Core Events pageview, pv, session_state, ss, consent, possiblePerson, pp

Click Events click, linkClick, buttonClick, ctaClick, downloadClick, telClick, mailtoClick

Form Events form, formLoad, formVisible, formStart, formFieldStart, formFieldComplete, formStepChange, formValidationFail, formSubmit, formAbandon, form_load, form_visible, form_start, form_field_start, form_field_complete, form_step_change, form_validation_fail, form_submit, form_abandon, fl, fv, fs, ffs, ffc, fsc, fvf, fsu, fab

Engagement Events scroll, scrollDepth, contentEngagement, pageExit

Identity Events identify, identifyPerson

Chat Events chat, chatLoaded, chatOpened, chatStarted, chatMessageSent, chatMessageReceived, chatEmailCaptured, chatMeetingBooked, chatOfflineForm, chatEnded, chat_loaded, chat_opened, chat_started, chat_message_sent, chat_message_received, chat_email_captured, chat_meeting_booked, chat_offline_form, chat_ended, chs, cho, che, cms, cmr, cec, cmb, cof

Video Events video, videoLoaded, videoPlay, videoPause, videoProgress, videoSeek, videoEnd, videoFullscreen, videoMute, videoUnmute, video_loaded, video_play, video_pause, video_progress, video_seek, video_end, video_fullscreen, video_mute, video_unmute, vpl, vpa, vpr, vpg, ven, vsk, vmt, vum, vfs, vxf

Scheduling Events scheduling, schedulingLoaded, schedulingOpened, schedulingDateSelected, schedulingTimeSelected, schedulingFormStarted, schedulingScheduled, schedulingCancelled, schedulingRescheduled, scheduling_loaded, scheduling_opened, scheduling_date_selected, scheduling_time_selected, scheduling_form_started, scheduling_scheduled, scheduling_cancelled, scheduling_rescheduled, sld, sop, sds, sts, sfs, sch, sca, srs, sbc

eCommerce Events ecommerce, view_item, view_item_list, select_item, add_to_cart, remove_from_cart, view_cart, begin_checkout, add_shipping_info, add_payment_info, purchase, refund

Reserved name checking is case-insensitive. For example, PageView, PAGEVIEW, and pageview are all reserved.

Data Warehouse Output

When you call _ll.track(), the event is stored in the Data Warehouse:

// Input: SDK call
_ll.track('feature_used', {
  feature: 'export',
  format: 'csv',
  record_count: 150
});

// Output: Data Warehouse
{
  "event_type": "custom",
  "data": {
    "name": "feature_used",
    "source": "sdk",
    "params": {
      "feature": "export",
      "format": "csv",
      "record_count": 150
    }
  }
}

Auto-PII Detection

ListenLayer scans custom event parameters for identity information:

// Email detected and captured as identity
_ll.track('registration_complete', {
  email: '[email protected]',  // Auto-detected
  plan: 'pro',
  source: 'landing_page'
});

---

SDK API: eCommerce Events

Track eCommerce transactions using _ll.ecommerce.* methods. ListenLayer supports both GA4 format and ListenLayer enhanced format.

Purchase

GA4 Format:

_ll.ecommerce.purchase({
  transaction_id: 'ORD-12345',
  currency: 'USD',
  value: 150.80,
  tax: 10.80,
  shipping: 5.00,
  coupon: 'SPRING10',
  items: [
    {
      item_id: 'SKU-001',
      item_name: 'Widget Pro',
      price: 50.00,
      quantity: 2,
      item_variant: 'Red',
      item_brand: 'ACME',
      item_category: 'Electronics',
      item_category2: 'Widgets',
      discount: 5.00,
      coupon: 'WIDGET5'
    },
    {
      item_id: 'SKU-002',
      item_name: 'Widget Case',
      price: 25.00,
      quantity: 2,
      item_brand: 'ACME',
      item_category: 'Accessories'
    }
  ]
});

ListenLayer Enhanced Format:

_ll.ecommerce.purchase({
  order_id: 'ORD-12345',
  currency: 'USD',
  subtotal: 150.00,
  item_discounts_total: 10.00,
  cart_discount: 5.00,
  total_discount: 15.00,
  adjusted_subtotal: 135.00,
  tax: 10.80,
  shipping: 5.00,
  grand_total: 150.80,
  coupon: 'SPRING10',
  items: [
    {
      item_id: 'SKU-001',
      item_name: 'Widget Pro',
      unit_price: 50.00,
      quantity: 2,
      variant: 'Red',
      variant_id: 'SKU-001-RED',
      brand: 'ACME',
      category: 'Electronics',
      item_discount: 10.00,
      item_total: 100.00,
      item_adjusted_total: 90.00,
      coupon: 'WIDGET5'
    }
  ]
});

With Customer Identity:

_ll.ecommerce.purchase({
  order_id: 'ORD-12345',
  currency: 'USD',
  value: 150.80,
  // Identity fields (auto-detected)
  email: '[email protected]',
  // Or GA4 user_data (high confidence)
  user_data: {
    email: '[email protected]',
    first_name: 'Jane',
    last_name: 'Smith'
  },
  items: [...]
});

Add to Cart

View Item

View Item List

Begin Checkout

View Cart

All eCommerce Methods

Method	Description
_ll.ecommerce.viewItem()	Product detail page view
_ll.ecommerce.viewItemList()	Category or search results view
_ll.ecommerce.selectItem()	Product clicked in list
_ll.ecommerce.addToCart()	Item added to cart
_ll.ecommerce.removeFromCart()	Item removed from cart
_ll.ecommerce.viewCart()	Cart page viewed
_ll.ecommerce.beginCheckout()	Checkout started
_ll.ecommerce.addShippingInfo()	Shipping details entered
_ll.ecommerce.addPaymentInfo()	Payment details entered
_ll.ecommerce.purchase()	Order completed
_ll.ecommerce.refund()	Order refunded
_ll.ecommerce.viewPromotion()	Promotion banner viewed
_ll.ecommerce.selectPromotion()	Promotion clicked
_ll.ecommerce.addToWishlist()	Item added to wishlist

Field Reference

Order-Level Fields

GA4 Field	ListenLayer Field	Required	Description
transaction_id	order_id	Yes	Unique order identifier
currency	currency	Yes	ISO 4217 currency code
value	grand_total	Yes	Total order value
—	subtotal	No	Sum of item totals before discounts
tax	tax	No	Tax amount
shipping	shipping	No	Shipping cost
coupon	coupon	No	Order-level coupon code
—	cart_discount	No	Cart-level discount amount
—	item_discounts_total	No	Sum of item discounts
—	total_discount	No	Total discount (cart + items)
—	adjusted_subtotal	No	Subtotal minus discounts
affiliation	affiliation	No	Store or affiliate name

Item-Level Fields

GA4 Field	ListenLayer Field	Required	Description
item_id	item_id	Yes	Product SKU or ID
item_name	item_name	Yes	Product name
price	unit_price	Yes	Unit price
quantity	quantity	Yes	Quantity
item_variant	variant	No	Variant name (e.g., "Red")
—	variant_id	No	Variant SKU
item_brand	brand	No	Brand name
item_category	category	No	Primary category
item_category2	—	No	Category level 2
item_category3	—	No	Category level 3
discount	item_discount	No	Item discount amount
coupon	coupon	No	Item-level coupon
index	index	No	Position in list
item_list_id	list_id	No	List identifier
item_list_name	list_name	No	List name
—	item_total	No	unit_price × quantity
—	item_adjusted_total	No	item_total - item_discount

---

SDK API: Identity Events

Use _ll.identifyPerson() to explicitly identify a visitor.

Basic Usage

// Email only
_ll.identifyPerson({
  email: '[email protected]'
});

// Full details
_ll.identifyPerson({
  email: '[email protected]',
  phone: '[phone]',
  firstName: 'John',
  lastName: 'Doe',
  zipCode: '94102',
  externalId: 'cust_12345',
  company: {
    domain: 'acmecorp.com',
    name: 'ACME Corporation'
  },
  customFields: {
    plan: 'enterprise',
    lifetime_value: 5000,
    is_vip: true
  }
});

When to Call

Call _ll.identifyPerson() when you know who the visitor is:

• After login or signup

• When loading a page for an authenticated user

• After receiving identity from your backend

• When syncing with your CRM

Field Reference

Field	Type	Required	Description
email	string	Yes*	Email address
phone	string	Yes*	Phone number (E.164 format preferred)
firstName	string	No	First name
lastName	string	No	Last name
zipCode	string	No	Postal/ZIP code
externalId	string	No	Your system's user/customer ID
company.domain	string	Yes**	Company domain (required if company provided)
company.name	string	No	Company name
customFields	object	No	Custom properties (string, number, boolean)

* At least one of email or phone is required. ** Required only if company object is provided.

Identity set via _ll.identifyPerson() persists across sessions. Once identified, the visitor remains associated with their identity on future visits.

All identity data is encrypted client-side before transmission. ListenLayer never sends PII in cleartext.

---

DataLayer Events

ListenLayer intercepts window.dataLayer.push() calls and can capture them as events based on rules in your account.

Required Structure

Any object pushed with an event property can be captured and treated as a custom event if the event property is targeted with rules inside you ListenLayer account. This allows you to send custom events to ListenLayer based on existing tracking activity you already have in place.

// Basic dataLayer event
dataLayer.push({
  event: 'video_engagement',
  video_id: 'intro-123',
  action: 'play',
  duration: 120
});

// With nested data
dataLayer.push({
  event: 'form_interaction',
  form: {
    id: 'contact-form',
    step: 2,
    field: 'email'
  }
});

How Data is Translated to Data Warehouse

When a dataLayer push matches a rule, ListenLayer captures it as a custom event. The rule ID (defined inside your account) becomes the event name, and the full dataLayer payload is automatically collected.

Example: DataLayer Push with Matching Rule (Rule ID: Pricing Calculator Rule)

// Input: dataLayer.push()
dataLayer.push({
  event: 'pricing_calculator',
  plan: 'enterprise',
  seats: 50,
  annual: true,
  estimated_value: 2500
});

// Output: Data Warehouse
{
  "event_type": "custom",
  "data": {
    "name": "pricing_calculator_rule",
    "source": "dataLayer",
    "params": {
      "_dl_event": "pricing_calculator",
      "plan": "enterprise",
      "seats": 50,
      "annual": true,
      "estimated_value": 2500
    }
  }
}

Nested Properties are Preserved

Nested objects in the dataLayer are automatically captured:

// Input: dataLayer.push()
dataLayer.push({
  event: 'quiz_completed',
  quiz: {
    id: 'product-fit',
    score: 85,
    result: 'enterprise'
  },
  answers: {
    team_size: '50-100',
    industry: 'technology'
  }
});

// Output: Data Warehouse
{
  "event_type": "custom",
  "data": {
    "name": "quiz_completed_rule",
    "source": "dataLayer",
    "params": {
      "_dl_event": "quiz_completed",
      "quiz": {
        "id": "product-fit",
        "score": 85,
        "result": "enterprise"
      },
      "answers": {
        "team_size": "50-100",
        "industry": "technology"
      }
    }
  }
}

Field	Description
data.name	The rule ID configured in ListenLayer
data.source	Always dataLayer for dataLayer events
params._dl_event	Original event property value
params.*	All properties from the dataLayer push (flat and nested)

All properties from the dataLayer push are automatically captured—no configuration required. Nested objects are preserved in their original structure.

Identity Detection

PII is encrypted client-side. Only hashes are visible in raw events. When using the Preview tools, unencrypted values are shown for debuggin.

ListenLayer detects identity from dataLayer pushes using two tiers:

Tier 1: Explicit Identity (High Confidence)

Standard field names, included inside the user_data or person object, that indicate known identity. Use these when you want to explicitly emite the visitors identity as opposed to letting us infer a possible person.

// GA4 standard user_data object
dataLayer.push({
  event: 'login',
  user_data: {
    email: '[email protected]',
    phone_number: '[phone]',
    first_name: 'John',
    last_name: 'Doe'
  }
});

// ListenLayer person object
dataLayer.push({
  event: 'signup_complete',
  person: {
    email: '[email protected]',
    phone_number: '[phone]',
    first_name: 'John',
    company: 'Acme Corp'
  }
});

// Output: Data Warehouse
{
  "event_type": "identify",
  "data": {
    "source": "dataLayer",
    "confidence": "high",
    "identity": {
      "encrypted": "base64_encrypted_blob",
      "key_id": "key_123"
    },
    "email_hash": "sha256_hash",
    "phone_hash": "sha256_hash",
    "fields": ["email", "phone", "first_name", "last_name"]
  }
}

Tier 2: Flexible Detection (Medium Confidence)

Email patterns detected anywhere in the payload (outside of the explicit user_data or person objects):

// Email detected in custom fields
dataLayer.push({
  event: 'newsletter_signup',
  subscriber_email: '[email protected]',  // Detected
  preferences: ['weekly', 'promotions']
});

// Output: Data Warehouse
{
  "event_type": "possible_person",
  "data": {
    "source": "dataLayer",
    "confidence": 0.85,
    "emails": [
      {
        "confidence": 0.85,
        "tags": ["source:dataLayer", "field:subscriber_email"],
        "email_hash": "sha256_hash"
      }
    ],
    "identity": {
      "encrypted": "base64_blob",
      "key_id": "key_123"
    }
  }
}

Excluded Events

These events are not captured as generic dataLayer events:

Pattern	Reason
gtm.*	GTM internal events
ll.*, _ll.*	ListenLayer internal (prevents loops)
GA4 eCommerce (purchase, add_to_cart, etc.)	Handled by eCommerce listener

DataLayer Rules

Configure rules in ListenLayer settings to map dataLayer events to custom events:

// When this is pushed:
dataLayer.push({
  event: 'video_play',
  video_id: 'demo-video',
  title: 'Product Demo'
});

// With a rule matching 'video_play', ListenLayer emits a custom event
// extracting the configured parameters (video_id, title)

---

DataLayer Push Back

After processing events, ListenLayer pushes matched triggers back to the dataLayer for GTM and other tools to consume.

How It Works

1. SDK sends event to ListenLayer Edge

2. Edge processes event and matches against configured triggers

3. SDK polls for trigger responses

4. Matched triggers are pushed to window.dataLayer

Trigger Structure

When a trigger matches, ListenLayer pushes to the dataLayer:

// Pushed automatically by ListenLayer SDK
window.dataLayer.push({
  event: 'll_form_submission',        // ll_ + trigger_slug
  trigger_id: 't_abc123',             // Trigger ID
  trigger_name: 'form_submission',    // Human-readable name
  is_conversion: true,                // Is this a conversion event?
  source_event_id: 'evt_xyz789',      // Links to source event
  _ll_trigger_rtt: 145                // Round-trip time (ms)
});

Using Triggers in GTM

Create a Custom Event trigger in GTM:

1. Trigger Type: Custom Event

2. Event Name: ll_form_submission (or use regex ll_.* for all)

3. Use in Tags: Fire your conversion pixels, webhooks, etc.

Example: Fire Google Ads Conversion

Trigger: Custom Event = ll_purchase_complete
Tag: Google Ads Conversion
  - Conversion ID: AW-XXXXXXX
  - Conversion Label: XXXXXXX
  - Value: {{DLV - ecommerce.value}}

Polling Behavior

The SDK uses intelligent polling to retrieve triggers:

Phase	Timing	Purpose
Fast polling	0ms, 25ms, 37ms, 55ms...	Immediate trigger delivery
Backoff	Up to 500ms intervals	Reduce server load
Safety polls	500ms, 1.5s, 3s, 5s	Cross-page trigger recovery

Triggers survive page navigation—if you navigate before a trigger is delivered, it will be delivered on the next page.

---

Event Structure (Data Warehouse)

This section documents the structure of events as stored in your data warehouse.

Events use short field codes on the wire for efficiency. They are expanded to full names in the Data Warehouse.

The examples below show raw event formats as received by the Data Warehouse. The Data Warehouse processes these events and transforms them into optimized, enriched structures for analysis and reporting.

Base Event Envelope

Every event includes these fields. The data field contains event-specific payload.

{
  "account_id": "acc_abc123",
  "event_type": "click",
  "timestamp": 1709136000000,
  "tracking_mode": "id",
  "url": "https://example.com/products/widget",
  "page_title": "Widget Pro - Example Store",
  "pageview_id": "pv_xyz789",
  "consent_state": {
    "gpc": 0,
    "functional": "granted",
    "analytics": "granted",
    "advertising": "denied",
    "personalization": "pending"
  },
  "referrer": {
    "url": "https://google.com/search?q=widget",
    "host": "google.com",
    "type": "search",
    "same_site": false
  },
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "spring_sale"
  },
  "click_ids": {
    "gclid": "Cj0KCQiAm4KqBhDy..."
  },
  "viewport": {
    "width": 1920,
    "height": 1080,
    "pixel_ratio": 2
  },
  "client_info": {
    "country": "US",
    "region": "CA",
    "city": "San Francisco",
    "timezone": "America/Los_Angeles"
  },
  "device_id": "did_abc789",
  "session_id": "sid_123456",
  "is_new_session": false,
  "is_new_device": false,
  "data": {
    // Event-specific fields
  }
}

Core Fields

Wire	Field	Type	Description
a	account_id	string	Your ListenLayer account ID
t	event_type	string	Event type (pv, click, form_submit, etc.)
ts	timestamp	number	Client timestamp (Unix ms)
tm	tracking_mode	string	id (identified), anon (anonymous), dnt (do-not-track)
url	url	string	Current page URL
tt	page_title	string	Document title
pvid	pageview_id	string	Unique ID for this page load
d	data	object	Event-specific payload

Consent State Object

Wire	Field	Values	Description
gpc	gpc	0, 1	Global Privacy Control signal
fn	functional	g, d, p	Functional cookies (user preferences)
an	analytics	g, d, p	Analytics tracking
ad	advertising	g, d, p	Advertising/remarketing
ps	personalization	g, d, p	Content personalization
cmp	cmp_platform	string	CMP platform code (ot, cs, etc.)

Values: g = granted, d = denied, p = pending

Referrer Object

Wire	Field	Type	Description
url	referrer_url	string	Full referrer URL
host	referrer_host	string	Hostname only
path	referrer_path	string	Path portion
same	is_same_site	boolean	Same domain
type	referrer_type	string	internal, external, direct, search, social

UTM Parameters Object

Wire	Field	Description
s	utm_source	Traffic source (google, facebook, newsletter)
m	utm_medium	Marketing medium (cpc, email, social)
c	utm_campaign	Campaign name
t	utm_term	Keyword (paid search)
n	utm_content	Ad variation

Plus ValueTrack params: matchtype, network, device, adgroup, creative, etc.

Click IDs Object (19 Platforms)

Wire	Parameter	Platform
gc	gclid	Google Ads
gb	gbraid	Google iOS
wb	wbraid	Google web-to-app
fb	fbclid	Meta/Facebook
ms	msclkid	Microsoft/Bing
tt	ttclid	TikTok
li	li_fat_id	LinkedIn
pin	epik	Pinterest
snap	sclid	Snapchat
tw	twclid	Twitter/X
rd	rdt_cid	Reddit
qq	qclid	Quora
dc	dclid	DoubleClick/DV360
yh	vmcid	Yahoo DSP
vi	viant_clid	Viant/Adelphic
sa	sapid	StackAdapt
ad	ef_id	Adobe Advertising
tb	click_id	Taboola
ob	ob_click_id	Outbrain

Viewport & Device Object

Wire	Field	Type	Description
w	viewport_width	number	Visible width (px)
h	viewport_height	number	Visible height (px)
dpr	device_pixel_ratio	number	Retina ratio (1, 2, 3)
sw	scroll_width	number	Total scrollable width
sh	scroll_height	number	Total scrollable height

Client Info Object (Edge-Enriched)

Geo (Location)

Wire	Field	Description
co	country	ISO 3166-1 alpha-2
rg	region	State/province
rgc	region_code	ISO 3166-2
ct	city	City name
pc	postal_code	Postal/ZIP
lat	latitude	Decimal
lon	longitude	Decimal
tz	timezone	IANA format
cont	continent	NA, EU, AS, AF, OC, SA, AN
eu	is_eu_country	Boolean

Network

Wire	Field	Description
asn	asn	Network provider ID
aso	asn_organization	Network provider name
proto	http_protocol	HTTP/1.1, HTTP/2, HTTP/3

Bot Detection

Wire	Field	Description
bot	bot_score	1-99 (1=bot, 30+=human)
bv	verified_bot	Is known bot
bcat	verified_bot_category	search, preview, ai, etc.

Identity Fields (Edge-Added)

Wire	Field	Description
did	device_id	Persistent device identifier
pid	person_id	Cross-device person ID (when identified)
sid	session_id	Current session ID
nd	is_new_device	First event from this device
ns	is_new_session	First event of new session

Core Web Vitals Object

Wire	Field	Description
lcp	largest_contentful_paint	Time until largest element visible (ms)
fid	first_input_delay	Time from first interaction to response (ms)
cls	cumulative_layout_shift	Layout stability score (0-1)
inp	interaction_to_next_paint	Responsiveness metric (ms)
fcp	first_contentful_paint	Time until first content visible (ms)
ttfb	time_to_first_byte	Server response time (ms)

---

Core Events

Pageview

Event Type: pv → pageview

Fired on page load and SPA navigation.

{
  "event_type": "pageview",
  "data": {
    "navigation_type": "navigate",
    "previous_url": null,
    "performance": {
      "dns": 15,
      "tcp": 25,
      "ttfb": 180,
      "dom_interactive": 450,
      "load": 1200
    },
    "user_initiated": true,
    "was_hidden": false
  }
}

Field	Description
navigation_type	navigate, reload, back_forward, spa_push, spa_replace, spa_pop, spa_hash, bfcache, prerender, prerender_activate
previous_url	Previous page URL (SPA only)
performance.ttfb	Time to first byte (ms)
performance.dom_interactive	DOM interactive time (ms)
performance.load	Load event time (ms)

Session State

Consent

Platform Detection

Click Events

Event Type: clk → click

Event Naming: The short code clk is used in the wire format (SDK to Edge). The long name click is used in the data warehouse and appears as the event_type value in processed events.

{
  "event_type": "click",
  "data": {
    "click_type": "button",
    "element_text": "Add to Cart",
    "element_id": "add-cart-btn",
    "element_classes": ["btn", "btn-primary"],
    "element_tag": "button",
    "href": null,
    "is_outbound": false,
    "file_extension": null
  }
}

Click Type Values

The click_type field classifies what was clicked:

Type	Description
link	Standard link click
button	Button element click
download	File download link
tel	Phone number link
mailto	Email link
cta	Call-to-action element
rule	Click matched a tracking rule
other	Other clickable element

Scroll Events

Event Type: scr → scroll

{
  "event_type": "scroll",
  "data": {
    "depth": 50,
    "max_depth": 50,
    "page_height": 4500,
    "time_to_depth": 45000
  }
}

Milestones: 25%, 50%, 75%, 90%, 100%

Form Events

Form tracking captures the complete form lifecycle from load to submit or abandon.

Form Lifecycle Events

Form Load (fl → form_load)

Fired when a form is added to the DOM.

{
  "event_type": "form_load",
  "data": {
    "form_id": "contact-form",
    "form_platform": "hubspot",
    "field_count": 5,
    "has_required_fields": true
  }
}

---

Form Visible (fv → form_visible)

Fired when a form scrolls into the viewport.

{
  "event_type": "form_visible",
  "data": {
    "form_id": "contact-form",
    "time_to_visible": 1500,
    "viewport_percent": 80
  }
}

---

Form Start (fs → form_start)

Fired when user begins interacting with a form.

{
  "event_type": "form_start",
  "data": {
    "form_id": "contact-form",
    "first_field": "email",
    "time_to_start": 5000
  }
}

---

Form Submit (fsb → form_submit)

Fired when user submits a form.

{
  "event_type": "form_submit",
  "data": {
    "form_id": "contact-form",
    "form_platform": "hubspot",
    "fields_completed": 4,
    "fields_total": 5,
    "time_to_submit": 45000,
    "had_validation_errors": false,
    "submission_method": "ajax"
  }
}

---

Form Abandon (fab → form_abandon)

Fired when user leaves without submitting.

{
  "event_type": "form_abandon",
  "data": {
    "form_id": "contact-form",
    "fields_completed": 2,
    "fields_total": 5,
    "last_field": "phone",
    "time_in_form": 30000
  }
}

Field Interaction Events

Field Start (ffs → form_field_start)

Fired when user focuses on a field.

{
  "event_type": "form_field_start",
  "data": {
    "form_id": "contact-form",
    "field_name": "email",
    "field_type": "email",
    "field_position": 1
  }
}

---

Field Complete (ffc → form_field_complete)

Fired when user completes a field.

{
  "event_type": "form_field_complete",
  "data": {
    "form_id": "contact-form",
    "field_name": "email",
    "field_type": "email",
    "time_in_field": 3500
  }
}

---

Step Change (fsc → form_step_change)

Fired when multi-step form progresses.

{
  "event_type": "form_step_change",
  "data": {
    "form_id": "multi-step-form",
    "from_step": 1,
    "to_step": 2,
    "total_steps": 4
  }
}

---

Validation Fail (fvf → form_validation_fail)

Fired when form validation fails.

{
  "event_type": "form_validation_fail",
  "data": {
    "form_id": "contact-form",
    "field_name": "email",
    "error_type": "invalid_format"
  }
}

Identity Events

Identify

Event Type: id → identify

Explicit identification via _ll.identifyPerson().

{
  "event_type": "identify",
  "data": {
    "source": "sdk",
    "confidence": "high",
    "identity": {
      "encrypted": "base64_encrypted_blob",
      "key_id": "key_123"
    },
    "email_hash": "sha256_hash",
    "email_hash_md5": "md5_hash"
  }
}

PII is encrypted client-side. Only hashes are visible in raw events.

Possible Person

Custom

Chat Events

All Chat Events

Wire Code	Event Type	Description
chl	chat_loaded	Chat widget loaded
cho	chat_opened	Widget opened
chs	chat_started	Conversation began
cms	chat_message_sent	User sent message
cmr	chat_message_received	Bot/agent replied
cec	chat_email_captured	Email collected
cmb	chat_meeting_booked	Meeting scheduled
cof	chat_offline_form	Offline form submitted
che	chat_ended	Conversation ended

Example: Chat Started

{
  "event_type": "chat_started",
  "data": {
    "platform": "intercom",
    "conversation_id": "conv_12345",
    "initiated_by": "user",
    "trigger": "user_click"
  }
}

Video Events

All Video Events

Wire Code	Event Type	Description
vld	video_loaded	Player initialized
vpl	video_play	Play started/resumed
vpa	video_pause	Video paused
vpr	video_progress	Milestone reached
vsk	video_seek	User seeked
ven	video_end	Video completed
vfs	video_fullscreen	Fullscreen toggled
vmt	video_mute	Video muted
vum	video_unmute	Video unmuted

Example: Video Play

{
  "event_type": "video_play",
  "data": {
    "action": "play",
    "platform": "youtube",
    "video_id": "abc123xyz",
    "title": "Product Demo",
    "duration": 180,
    "position": 0,
    "percent": 0,
    "is_muted": false,
    "is_fullscreen": false
  }
}

Scheduling Events

All Scheduling Events

Wire Code	Event Type	Description
sld	scheduling_loaded	Widget loaded
sop	scheduling_opened	Widget opened
sds	scheduling_date_selected	Date picked
sts	scheduling_time_selected	Time picked
sfs	scheduling_form_started	Details form started
sch	scheduling_scheduled	Booking confirmed
sca	scheduling_cancelled	Booking cancelled
srs	scheduling_rescheduled	Booking rescheduled
sbc	scheduling_confirmed	Confirmation received

Example: Scheduled

{
  "event_type": "scheduling_scheduled",
  "data": {
    "platform": "calendly",
    "event_type": "Sales Demo",
    "duration": 30,
    "scheduled_date": "2026-03-05",
    "scheduled_time": "14:00",
    "timezone": "America/New_York"
  }
}

eCommerce Events

All eCommerce Events

Wire Code	Event Type	Description
evi	view_item	Product viewed
eil	view_item_list	Category/list viewed
esi	select_item	Product selected
atc	add_to_cart	Added to cart
rfc	remove_from_cart	Removed from cart
eca	view_cart	Cart viewed
eco	begin_checkout	Checkout started
esh	add_shipping_info	Shipping entered
epi	add_payment_info	Payment entered
epu	purchase	Purchase completed
erf	refund	Order refunded
epr	view_promotion	Promotion viewed
eps	select_promotion	Promotion selected
ewl	add_to_wishlist	Added to wishlist

Example: Purchase

{
  "event_type": "purchase",
  "data": {
    "transaction_id": "ORD-12345",
    "currency": "USD",
    "value": 150.80,
    "tax": 10.80,
    "shipping": 5.00,
    "coupon": "SPRING10",
    "items": [
      {
        "item_id": "SKU-001",
        "item_name": "Widget Pro",
        "price": 50.00,
        "quantity": 2,
        "variant": "Red",
        "brand": "ACME",
        "category": "Electronics"
      }
    ]
  }
}