RFC - Custom Events

[stordahl]

Summary

This RFC proposes adding custom event tracking capabilities to Counterscale while maintaining full backward compatibility with existing pageview tracking. The implementation leverages unused Cloudflare Analytics Engine columns to store custom event data without affecting existing functionality.

Motivation

Currently, Counterscale only supports pageview tracking. Many analytics use cases require tracking custom events like button clicks, form submissions, downloads, and other user interactions. This enhancement would enable comprehensive user behavior analytics while preserving the simplicity and performance of the existing system.

Related Issues:

• Support for custom event tracking #200

Design

Schema Extensions

New column mappings will be added to packages/server/app/analytics/schema.ts:

export const ColumnMappings = {
  // ... existing mappings (blob1-blob10, double1-double3)
  
  // New custom event columns
  eventName: "blob11",      // Custom event name (e.g., "button_click", "form_submit")
  eventCategory: "blob12",  // Event category (e.g., "engagement", "conversion")
  eventData: "blob13",      // JSON string of event data
} as const;

API Interface

The /collect endpoint will accept new optional query parameters:

• en - Event name (string)
• ec - Event category (string)
• ed - Event data (URL-encoded JSON string)

Data Structure

The DataPoint interface will be extended with optional custom event fields:

interface DataPoint {
  // ... existing fields
  
  // Custom event fields (optional)
  eventName?: string;
  eventCategory?: string;
  eventData?: string; // JSON string
}

Implementation Strategy

1. Backward Compatibility: All existing pageview tracking continues unchanged
2. Additive Approach: New columns (blob11+, double4+) are only populated when custom events are tracked
3. Flexible Event Model: Support various event types through eventName and eventCategory
4. Extensible Data: JSON-based eventData field for arbitrary event information

Tracker Package Integration

Standard Schema Support

The tracker package will integrate with the Standard Schema specification to provide type-safe event registration and validation. Standard Schema is a common interface implemented by popular validation libraries like Zod, Valibot, ArkType, and Effect Schema.

The motivation for this integration is to provide a flexible mechanism to ensure user defined data structures are always sent to the server with the same structure. Since the current iteration of Counterscale relies on all users deploying the same server, it's difficult to add server-side validation for custom events/data structures. While all of that is true, I do think making schemas optional should be considered as to not hand-hold users of the tracker npm package. Having first-class support for all Standard Schemas should enable those that need to validate can do so easily, but we shouldn't force someone to adopt a schema validation library to define custom events.

Event Registration API

Following the existing Counterscale API patterns, custom events will be registered and tracked through module-level functions similar to trackPageview:

// Event registration interface
interface EventRegistration<TInput = any, TOutput = TInput> {
  name: string;
  category?: string;
  schema?: StandardSchemaV1<TInput, TOutput>;
}

// Track event options interface
interface TrackEventOpts<TData = any> {
  name: string;
  category?: string;
  data?: TData;
}

// Module-level functions (similar to existing API)
export function registerEvent<TInput, TOutput = TInput>(
  registration: EventRegistration<TInput, TOutput>
): void;

export function trackEvent<TData = any>(
  opts: TrackEventOpts<TData>
): void;

// Alternative: register and get a typed tracking function
export function createEventTracker<TInput, TOutput = TInput>(
  registration: EventRegistration<TInput, TOutput>
): (data: TInput) => void;

Usage Example

import { z } from 'zod';
import * as Counterscale from '@counterscale/tracker';

// Initialize as usual
Counterscale.init({
  siteId: 'your-unique-site-id',
  reporterUrl: 'https://your-subdomain.workers.dev/collect',
});

// Register events with schemas for validation
Counterscale.registerEvent({
  name: 'form_submit',
  category: 'conversion',
  schema: z.object({
    formType: z.enum(['contact', 'newsletter', 'feedback']),
    userId: z.string().optional(),
    conversionValue: z.number().positive().optional()
  })
});

// Now track with validation - TypeScript will enforce the schema type
Counterscale.trackEvent({
  name: 'form_submit',
  category: 'conversion',
  data: {
    formType: 'contact',
    userId: 'user123',
    conversionValue: 100
  }
});

// Alternative - return function to call
const trackFormSubmit = Counterscale.createEventTracker({
  name: 'form_submit',
  category: 'conversion',
  schema: z.object({
    formType: z.enum(['contact', 'newsletter', 'feedback']),
    userId: z.string().optional(),
    conversionValue: z.number().positive().optional()
  })
})

trackFormSubmit({
  formType: 'contact',
  userId: 'user123',
  conversionValue: 100
})

API Method Summary

Method	Use Case	Type Safety	Validation	Example
registerEvent() + trackEvent()	Consistent events with validation	Full	Runtime	Register once, track many times
createEventTracker()	Complex events, reusable	Full	Runtime	Returns typed function

Dashboard Integration

The dashboard will be extended with new routes and components to provide visualization and analysis of custom events while maintaining the existing user experience for pageview analytics.

Key features:

• Events overview page with summary statistics and time series charts
• Event detail pages with property distribution and filtering
• Dynamic components for event property filtering and visualization
• Integration with existing navigation and site selectors

Considerations

Performance

• Additional columns increase storage usage but leverage existing infrastructure
• Monitor query performance with additional columns
• Consider rate limiting for custom events to prevent abuse

Data Validation

• Validate event names and categories for consistency
• Sanitize JSON properties to prevent injection attacks
• Implement reasonable limits on property payload size
• Leverage Standard Schema for robust runtime validation

Developer Experience

• Support popular validation libraries (Zod, Valibot, ArkType, Effect Schema)
• Automatic TypeScript type inference from schemas
• Runtime validation prevents invalid data from being tracked
• Clear error messages for validation failures

Future Extensions

• Event funnel analysis
• Custom event-based conversion tracking
• Real-time event streaming
• Advanced event property querying
• Schema versioning and migration
• Event batching for improved performance

Dependencies

The tracker package will depend on the Standard Schema specification for type-safe validation, which is compatible with major validation libraries including Zod, Valibot, ArkType, and Effect Schema.

[congdv]

Appreciate you putting this RFC together, @stordahl. I’m a big fan of the concept—excited to see where it goes!

[bgervan]

Is it WIP somewhere?

[stordahl]

Currently, no - I'm hoping to get some more input from the community before we move forward with this design