Client-Side Events

Vendo streams client-side Shopify storefront events directly to BigQuery in real-time via the Web Pixel extension.

Events Captured

Event Name	Description
`page_viewed`	Page view
`product_viewed`	Product page view
`collection_viewed`	Collection page view
`search_submitted`	Search performed
`product_added_to_cart`	Add to cart
`product_removed_from_cart`	Remove from cart
`cart_viewed`	Cart page view
`checkout_started`	Checkout initiated
`checkout_contact_info_submitted`	Contact info entered
`checkout_address_info_submitted`	Address entered
`checkout_shipping_info_submitted`	Shipping selected
`payment_info_submitted`	Payment info entered
`checkout_completed`	Purchase completed

Event Schema

All client-side events are inserted into the events table with this schema:

Column	Type	Description
`event_name`	STRING	Lowercase event name (e.g., “page_viewed”)
`event_timestamp`	TIMESTAMP	When the event occurred
`user_id`	STRING	Shopify Customer ID (null for anonymous)
`anonymous_id`	STRING	Shopify device/client ID
`session_id`	STRING	Browser session ID
`page_url`	STRING	Full page URL
`page_title`	STRING	Document title
`page_path`	STRING	URL pathname
`referrer`	STRING	Referring URL
`device_type`	STRING	Device type (Desktop, Mobile, Tablet)
`browser`	STRING	Browser name
`os`	STRING	Operating system
`screen_width`	INTEGER	Screen width in pixels
`screen_height`	INTEGER	Screen height in pixels
`language`	STRING	Browser language
`currency`	STRING	Currency code
`value`	FLOAT	Event value (cart total, product price, etc.)
`utm_source`	STRING	UTM source parameter
`utm_medium`	STRING	UTM medium parameter
`utm_campaign`	STRING	UTM campaign parameter
`utm_content`	STRING	UTM content parameter
`utm_term`	STRING	UTM term parameter
`gclid`	STRING	Google Click ID
`fbclid`	STRING	Facebook Click ID
`msclkid`	STRING	Microsoft Click ID
`ttclid`	STRING	TikTok Click ID
`properties`	STRING	Event-specific properties (JSON)
`products`	STRING	Product array (JSON)
`source`	STRING	Source identifier
`version`	STRING	Tracking version
`insert_id`	STRING	Unique event ID for deduplication

Example Payloads

Page Viewed


{
  "event_name": "page_viewed",
  "event_timestamp": "2024-01-15T10:30:00.000Z",
  "user_id": null,
  "anonymous_id": "shop_client_abc123",
  "session_id": "sess_xyz789",
  "page_url": "https://mystore.com/collections/summer",
  "page_title": "Summer Collection – My Store",
  "page_path": "/collections/summer",
  "referrer": "https://google.com",
  "device_type": "Desktop",
  "browser": "Chrome",
  "os": "Mac OS X",
  "screen_width": 1440,
  "screen_height": 900,
  "language": "en-US",
  "currency": "USD",
  "value": 0,
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "summer-sale",
  "gclid": "CjwKCAjw...",
  "properties": "{}",
  "products": null,
  "source": "vendo_web_pixel",
  "version": "1.0.0",
  "insert_id": "49b71cd2-295b-476a-a345-0eb50bd13b57"
}

Product Viewed


{
  "event_name": "product_viewed",
  "event_timestamp": "2024-01-15T10:32:00.000Z",
  "user_id": null,
  "anonymous_id": "shop_client_abc123",
  "session_id": "sess_xyz789",
  "page_url": "https://mystore.com/products/classic-tshirt",
  "page_title": "Classic T-Shirt – My Store",
  "page_path": "/products/classic-tshirt",
  "referrer": "https://mystore.com/collections/all",
  "device_type": "Desktop",
  "currency": "USD",
  "value": 29.99,
  "utm_source": "google",
  "utm_medium": "cpc",
  "properties": "{\"product_id\":\"gid://shopify/Product/7894561230\",\"product_title\":\"Classic T-Shirt\"}",
  "products": "[{\"product_id\":\"gid://shopify/Product/7894561230\",\"sku\":\"TSHIRT-BLK-M\",\"name\":\"Classic T-Shirt\",\"price\":29.99,\"quantity\":1,\"variant_id\":\"gid://shopify/ProductVariant/42345678901\",\"variant_title\":\"Black / Medium\",\"brand\":\"My Brand\",\"category\":\"Apparel\"}]",
  "source": "vendo_web_pixel",
  "version": "1.0.0",
  "insert_id": "prod-view-event-id-123"
}

Product Added to Cart


{
  "event_name": "product_added_to_cart",
  "event_timestamp": "2024-01-15T10:35:00.000Z",
  "user_id": null,
  "anonymous_id": "shop_client_abc123",
  "session_id": "sess_xyz789",
  "page_url": "https://mystore.com/products/classic-tshirt",
  "device_type": "Desktop",
  "currency": "USD",
  "value": 59.98,
  "utm_source": "google",
  "utm_medium": "cpc",
  "properties": "{\"quantity\":2}",
  "products": "[{\"product_id\":\"gid://shopify/Product/7894561230\",\"sku\":\"TSHIRT-BLK-M\",\"name\":\"Classic T-Shirt\",\"price\":29.99,\"quantity\":2,\"variant_id\":\"gid://shopify/ProductVariant/42345678901\",\"variant_title\":\"Black / Medium\",\"brand\":\"My Brand\",\"category\":\"Apparel\"}]",
  "source": "vendo_web_pixel",
  "version": "1.0.0",
  "insert_id": "add-cart-event-id-456"
}

Cart Viewed


{
  "event_name": "cart_viewed",
  "event_timestamp": "2024-01-15T10:38:00.000Z",
  "user_id": null,
  "anonymous_id": "shop_client_abc123",
  "session_id": "sess_xyz789",
  "page_url": "https://mystore.com/cart",
  "device_type": "Desktop",
  "currency": "USD",
  "value": 149.97,
  "properties": "{\"quantity\":3}",
  "products": "[{\"product_id\":\"gid://shopify/Product/7894561230\",\"name\":\"Classic T-Shirt\",\"price\":29.99,\"quantity\":2},{\"product_id\":\"gid://shopify/Product/7894561231\",\"name\":\"Running Shorts\",\"price\":45.00,\"quantity\":1}]",
  "source": "vendo_web_pixel",
  "version": "1.0.0",
  "insert_id": "cart-view-event-id-789"
}

Checkout Started


{
  "event_name": "checkout_started",
  "event_timestamp": "2024-01-15T10:40:00.000Z",
  "user_id": null,
  "anonymous_id": "shop_client_abc123",
  "session_id": "sess_xyz789",
  "page_url": "https://mystore.com/checkouts/abc123",
  "device_type": "Desktop",
  "currency": "USD",
  "value": 162.49,
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "summer-sale",
  "properties": "{\"checkout_token\":\"abc123def456\",\"order_id\":\"gid://shopify/Order/5363269534010\",\"cart_subtotal_amount\":149.97,\"tax_amount\":12.52,\"shipping_amount\":0}",
  "products": "[{\"product_id\":\"gid://shopify/Product/7894561230\",\"name\":\"Classic T-Shirt\",\"price\":29.99,\"quantity\":2}]",
  "source": "vendo_web_pixel",
  "version": "1.0.0",
  "insert_id": "checkout-started-id-101"
}

Checkout Completed


{
  "event_name": "checkout_completed",
  "event_timestamp": "2024-01-15T10:45:00.000Z",
  "user_id": "6359703453860",
  "anonymous_id": "shop_client_abc123",
  "session_id": "sess_xyz789",
  "page_url": "https://mystore.com/checkouts/abc123/thank_you",
  "device_type": "Desktop",
  "currency": "USD",
  "value": 162.49,
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "summer-sale",
  "gclid": "CjwKCAjw...",
  "properties": "{\"checkout_token\":\"abc123def456\",\"order_id\":\"gid://shopify/Order/5363269534010\",\"cart_subtotal_amount\":149.97,\"tax_amount\":12.52,\"shipping_amount\":10.00,\"email\":\"customer@email.com\",\"phone\":\"+14155551234\"}",
  "products": "[{\"product_id\":\"gid://shopify/Product/7894561230\",\"name\":\"Classic T-Shirt\",\"price\":29.99,\"quantity\":2}]",
  "source": "vendo_web_pixel",
  "version": "1.0.0",
  "insert_id": "checkout-completed-id-202"
}

Collection Viewed


{
  "event_name": "collection_viewed",
  "event_timestamp": "2024-01-15T10:28:00.000Z",
  "user_id": null,
  "anonymous_id": "shop_client_abc123",
  "session_id": "sess_xyz789",
  "page_url": "https://mystore.com/collections/summer",
  "device_type": "Desktop",
  "currency": "USD",
  "value": 0,
  "properties": "{\"collection_id\":\"gid://shopify/Collection/123456789\",\"collection_title\":\"Summer Collection\"}",
  "products": "[{\"product_id\":\"gid://shopify/Product/7894561230\",\"name\":\"Classic T-Shirt\",\"price\":29.99,\"quantity\":1},{\"product_id\":\"gid://shopify/Product/7894561231\",\"name\":\"Running Shorts\",\"price\":45.00,\"quantity\":1}]",
  "source": "vendo_web_pixel",
  "version": "1.0.0",
  "insert_id": "collection-viewed-id-303"
}

Search Submitted


{
  "event_name": "search_submitted",
  "event_timestamp": "2024-01-15T10:25:00.000Z",
  "user_id": null,
  "anonymous_id": "shop_client_abc123",
  "session_id": "sess_xyz789",
  "page_url": "https://mystore.com/search?q=t-shirt",
  "device_type": "Desktop",
  "currency": "USD",
  "value": 0,
  "properties": "{\"search_query\":\"t-shirt\"}",
  "products": "[{\"product_id\":\"gid://shopify/Product/7894561230\",\"name\":\"Classic T-Shirt\",\"price\":29.99,\"quantity\":1}]",
  "source": "vendo_web_pixel",
  "version": "1.0.0",
  "insert_id": "search-submitted-id-404"
}

Querying Client-Side Events

Page Views by Day


SELECT
  DATE(event_timestamp) as date,
  COUNT(*) as page_views,
  COUNT(DISTINCT anonymous_id) as unique_visitors
FROM `your_project.your_dataset.events`
WHERE event_name = 'page_viewed'
GROUP BY date
ORDER BY date DESC

Product View to Add-to-Cart Conversion


SELECT
  DATE(pv.event_timestamp) as date,
  COUNT(DISTINCT pv.insert_id) as product_views,
  COUNT(DISTINCT atc.insert_id) as add_to_carts,
  SAFE_DIVIDE(
    COUNT(DISTINCT atc.insert_id),
    COUNT(DISTINCT pv.insert_id)
  ) * 100 as conversion_rate
FROM `your_project.your_dataset.events` pv
LEFT JOIN `your_project.your_dataset.events` atc
  ON pv.anonymous_id = atc.anonymous_id
  AND atc.event_name = 'product_added_to_cart'
  AND DATE(atc.event_timestamp) = DATE(pv.event_timestamp)
WHERE pv.event_name = 'product_viewed'
GROUP BY date
ORDER BY date DESC

UTM Attribution for Completed Checkouts


SELECT
  utm_source,
  utm_medium,
  utm_campaign,
  COUNT(*) as conversions,
  SUM(value) as revenue
FROM `your_project.your_dataset.events`
WHERE event_name = 'checkout_completed'
  AND event_timestamp >= DATE_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY utm_source, utm_medium, utm_campaign
ORDER BY revenue DESC