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

  1. URL Override: ?exp=123&var=A (testing - always wins)
  2. UTM Campaign: ?utm_campaign=summer2024 (persisted)
  3. Audience: ?audience=vip_customers (persisted)
  4. 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/variation

Expected 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

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