Analytics API Service
This is a headless API service for analytics and experimentation.
A/B Testing & Campaign Parameters
URL Parameters for Testing
Campaign & Audience Parameters
?utm_campaign=summer2024
Triggers experiment with matching utm_campaign (persists in session)
?audience=vip_customers
Triggers experiment with matching audience (persists in session)
Testing Override Parameters
?exp=123&var=A
Forces specific experiment ID and variation (for testing)
?exp=123&var=CHAMPION
Forces specific experiment with champion variation
?utm_campaign=summer2024&var=A
Forces UTM campaign experiment to show specific variation
?utm_campaign=summer2024&var=CHAMPION
Forces UTM campaign experiment to show champion
Priority Order
- URL Override: ?exp=123&var=A (testing - always wins)
- UTM Campaign: ?utm_campaign=summer2024 (persisted)
- Audience: ?audience=vip_customers (persisted)
- Default Split: Normal A/B testing based on champion_percent
Example Testing URLs
/products/headphones?utm_campaign=summer2024Test UTM campaign/products/headphones?audience=vip_customersTest audience segment/products/headphones?exp=123&var=AForce specific experiment/variationExpected Experiment JSON Structure
{
"data": [
{
"shopify_id": "gid://shopify/Product/8575792906371",
"experiments": [
{
"experiment_id": 123,
"champion_percent": 75,
"utm_campaign": "summer2024",
"audience": "Everyone",
"content_variations": [
{
"variation_id": "A",
"variation_percent": 25,
"fields": [
{
"field_type": "{{product.description}}",
"content": "Challenger content..."
},
{
"field_type": "{{product.name}}",
"content": "Challenger title..."
}
]
}
]
}
]
}
]
}API Endpoints
/api/v1/content- Experiment API for getting content for a product. Either all content for the product or just a field, based upon inclusion of the field_type parameter./api/metrics- View system metrics/api/cache/clear- Clear the cache/api/analytics/cron- Manually trigger the analytics cron job
Event Processing
Auto-Flush Script
Analytics events are collected in Redis and periodically sent to ClickHouse using the auto-flush script:
node scripts/auto-flush.js
This script should be run in a separate terminal window from the main application.
Configuration
- FLUSH_INTERVAL_MS: Time between flush operations (default: 300000ms / 5 minutes)
- API_URL: Base URL of the analytics API (default: http://localhost:3001)
Set these variables in your .env.local file or when running the script:
FLUSH_INTERVAL_MS=60000 node scripts/auto-flush.js
Navigation
- API Metrics Dashboard - View cache and API performance metrics (hit rates, response times)
- Buffer Metrics Dashboard - Monitor analytics events buffer and batch processing
- Test Harness - Test the experiment API with a form interface
- Trigger Analytics Cron Job - Manually flush analytics events to ClickHouse