Defining, Tagging, and Querying Custom Events
Custom events allow you to track specific user interactions or business processes that are unique to your application. For e-commerce businesses, custom events can provide invaluable insights beyond standard events like purchases or add-to-cart actions.
Use Cases for Custom Events in E-commerce
Product Customization: Track how users interact with product customization tools.
A/B Test Segment Tracking: Monitor user behavior across different test variants.
Wishlist Interactions: Monitor wishlist creation, sharing, and conversion to purchases.
Advanced Search Usage: Analyze how customers use advanced search features.
Customer Support Interactions: Track customer service chatbot usage or support ticket creation.
Virtual Try-On: For fashion or cosmetics, track usage of virtual try-on features.
Scroll Depth: Measure how far users scroll on important pages.
Using Custom Events
Using the Custom Event Builder
Once you know which custom events you want to track, you can use the Custom Event Builder in Triple Whale to:
Define your events and receive sample code
Let Triple Whale know the structure of your events so that they can be flattened for easier querying from within Triple Whale
You can send custom events without defining them in the custom event builder, but if they are not defined in the custom event builder, Triple Whale will not automatically flatten the properties for easier querying.
To track your first custom event:
Navigate to the Custom Event Builder in Triple Whale by going to Settings > Pixel Settings > Custom Events
Click on the "Create Your First Event" button.
Enter a name for your custom event (e.g., "productCustomizationInteraction").
Add properties to your event:
Click "Add Property" to add a new property.
Enter the property name (e.g., "productId").
Select the property type (string, number, boolean, or date).
Repeat step 4 for all needed properties.
Once finished, click "Save Configuration".
Note - if you don't save your configuration, Triple Whale won't know to flatten the properties of your events in the SQL interface.
You can access the Custom Event Builder at any time by visiting the Custom Events section in your Triple Whale settings.
Example 1: Product Customization Event
Event Name: productCustomizationInteraction
Properties:
productId (string)
customizationType (string)
completedCustomization (boolean)
Sample code for tracking this event:
TriplePixel('custom', 'productCustomizationInteraction', {
productId: 'TSHIRT-101',
customizationType: 'color',
completedCustomization: true
});
Example 2: A/B Test Segment Event
Event Name: abTestSegmentAssignment
Properties:
testId (string)
variantId (string)
Sample code for tracking this event:
TriplePixel('custom', 'abTestSegmentAssignment', {
testId: 'HOMEPAGE-REDESIGN-001',
variantId: 'B'
});
Example 3: Scroll Depth Event
Event Name: scrollDepthReached
Properties:
pageUrl (string)
scrollPercentage (number)
Sample code for tracking this event:
// This code should be triggered when specific scroll depths are reached
TriplePixel('custom', 'scrollDepthReached', {
pageUrl: window.location.href,
scrollPercentage: 50 // This value would be dynamically set based on the actual scroll depth
});
To implement scroll depth tracking, you would typically use JavaScript to calculate the scroll percentage and trigger the event at specific thresholds (e.g., 25%, 50%, 75%, 100%). Here's a basic implementation example:
window.addEventListener('scroll', function() {
var scrollPercentage = Math.round((window.scrollY / (document.documentElement.scrollHeight - window.innerHeight)) * 100);
if (scrollPercentage >= 25 && !tracked25) {
TriplePixel('custom', 'scrollDepthReached', {
pageUrl: window.location.href,
scrollPercentage: 25
});
tracked25 = true;
}
// Repeat for 50%, 75%, and 100%
});
Implementing Custom Event Tracking
To track custom events on your website, you need to add the TriplePixel custom event snippet. Here are two methods to implement this:
Method 1: Direct Implementation
Add the following JavaScript code where you want to track the custom event:
TriplePixel('custom', 'eventName', {
event_name: 'eventName',
property1: value1,
property2: value2,
// ... additional properties
});
Replace 'eventName' with your actual custom event name, and add your specific properties.
Method 2: Using Google Tag Manager
Log in to your Google Tag Manager account.
Create a new tag:
Click "New Tag"
Choose "Custom HTML" as the tag type
Paste the following code into the HTML field (replacing the name 'MyCustomEvent' with your desired event name):
<script>
TriplePixel('custom', 'MyCustomEvent', {
{{Property1 Name}}: {{Property1 Value}},
{{Property2 Name}}: {{Property2 Value}},
// ... additional properties
});
</script>
Create variables in GTM for the properties.
Set up a trigger that fires when you want to track the custom event (e.g., a specific button click or page view).
Save and publish your changes in GTM.
Example GTM setup for the product customization event:
<script>
TriplePixel('custom', 'productCustomizationInteraction', {
productId: '{{Custom Event - Product ID}}',
customizationType: '{{Custom Event - Customization Type}}',
completedCustomization: {{Custom Event - Completed}}
});
</script>
Remember to create corresponding variables in GTM for each of these placeholders.
Best Practices for Implementation
Ensure that the TriplePixel base code is already installed on your site before adding custom event tracking.
Test your implementation in a staging environment before deploying to production.
Use consistent naming conventions for your custom events and properties.
Validate that the data is being sent correctly using browser developer tools or tag manager preview mode.
Querying Custom Events
Once you've defined and tagged custom events, the data will be stored in the custom_pixel_events_table in ClickHouse. This table includes both the full event data and flattened properties for efficient querying.
Table Schema
event_date: Date of the event
data: JSON object containing all event properties
event_name: Name of the custom event
event_timestamp: Timestamp of the event
triple_id: TW assigned user ID
Additional columns for flattened properties (if defined in the custom event mapping tool)
Basic Query Structure
SELECT *
FROM custom_pixel_events_table
WHERE event_name = 'yourEventName'
Example 1: Querying Product Customization Events
SELECT
event_date,
event_timestamp,
triple_id,
data.productId AS productId,
data.customizationType AS customizationType,
data.completedCustomization AS completedCustomization
FROM custom_pixel_events_table
WHERE event_name = 'productCustomizationInteraction'
AND event_date >= today() - 7
AND data.completedCustomization = 'true'
ORDER BY event_date DESC
LIMIT 100
Example 2: Querying A/B Test Segment Assignments
SELECT
event_date,
event_timestamp,
triple_id,
data.testId AS testId,
data.variantId AS variantId
FROM custom_pixel_events_table
WHERE event_name = 'abTestSegmentAssignment'
AND event_date >= today() - 30
ORDER BY event_date DESC
LIMIT 100
Example 3: Analyzing Scroll Depth
SELECT
data.pageUrl AS pageUrl,
data.scrollPercentage AS scrollPercentage,
count(*) AS occurrences
FROM custom_pixel_events_table
WHERE event_name = 'scrollDepthReached'
AND event_date >= today() - 7
GROUP BY pageUrl, scrollPercentage
ORDER BY pageUrl, scrollPercentage
Advanced Querying
You can use Triple Whale’s JSON functions and other features for more complex analysis.
Example: Conversion rates by A/B test variant
WITH ab_test_users AS (
SELECT DISTINCT
triple_id,
data.testId AS testId,
data.variantId AS variantId
FROM custom_pixel_events_table
WHERE event_name = 'abTestSegmentAssignment'
AND data.testId = 'HOMEPAGE-REDESIGN-001'
),
conversions AS (
SELECT
triple_id,
count(distinct order_id) AS conversion_count
FROM pixel_orders_table
WHERE event_date >= today() - 30
GROUP BY triple_id
)
SELECT
ab.variantId,
count(DISTINCT ab.triple_id) AS total_users,
count(c.triple_id) AS converted_users,
count(c.triple_id) / count(DISTINCT ab.triple_id) AS conversion_rate
FROM ab_test_users ab
LEFT JOIN conversions c ON ab.triple_id = c.triple_id
GROUP BY ab.variantId
ORDER BY conversion_rate DESC
Using Flattened Properties
If you've defined flattened properties using the custom event mapping tool, you can query them directly:
SELECT
event_date,
event_timestamp,
triple_id,
productId,
customizationType,
completedCustomization
FROM custom_pixel_events_table
WHERE event_name = 'productCustomizationInteraction'
AND event_date >= today() - 7
AND completedCustomization = true
ORDER BY event_timestamp DESC
LIMIT 100
Best Practices for Querying
Use date and event_name filters to improve query performance.
Leverage ClickHouse's powerful aggregate and window functions for complex analysis.
When possible, use flattened properties instead of accessing the JSON data for better performance.
Use appropriate data types when querying JSON fields (e.g., toFloat64OrNull for numeric values).
Conclusion
Custom events provide a powerful way to track and analyze specific interactions in your e-commerce application. Whether you're tracking product customization interactions, A/B test segments, scroll depth, or other unique events, you can gain valuable insights into user behavior and preferences.
By carefully defining your events, consistently implementing them in your code, and effectively querying the data, you can uncover insights that go beyond standard e-commerce events. This data-driven approach allows you to make informed decisions about product features, user interface designs, and overall business strategies.
Remember to regularly review your custom events and queries to ensure they're providing valuable insights and performing efficiently. As your business evolves and you run new tests or introduce new features, you may need to add new custom events or modify existing ones to capture the most relevant data for your decision-making processes.
The flexibility of custom events allows you to adapt your analytics strategy to your changing business needs, ensuring that you always have the data you need to drive growth and improve user experience.