Technical Overview

Custom events are collected via a secure API endpoint designed for multi-tenant SaaS environments. Here's how the process works and what is tracked:

Event Validation & Security

• Each custom event sent to the API must include a projectKey that identifies the project.
• The backend validates the projectKey against the database and ensures the event's URL matches the project's allowed origin.
• CORS headers are set to allow secure cross-origin requests.

What Gets Tracked

• Event Name: The type or name of the event being reported, e.g. "SignUp", "ButtonClick".
• Event Data: Any custom metadata you provide in the event payload.
• Category/Label/Value: These special fields are extracted for analytics display if present in your event data.
• Session ID: Unique identifier for the user session (generated if not provided).
• User ID: If available, the user's unique identifier.
• Project ID: The internal ID of the project.
• Page Info:
  • Full URL
  • Page title (optional)
  • Page path (optional)
• Referrer: The previous page or source that led to the current page.
• User Agent: Information about the browser, operating system, and device.
• IP Address: Used for basic analytics and geographic distribution (anonymized or masked as needed).
• Timestamp: When the event occurred.

Data Storage & Processing

• Events are logged using a stored procedure in the database for efficiency and consistency.
• Each event is associated with the correct project and user.
• Usage is tracked for billing and quota purposes.

Example Event Payload

{
  "projectKey": "your-project-key",
  "event_name": "ButtonClick",
  "event_data": {
    "category": "CTA",
    "label": "Homepage Hero",
    "value": 1,
    "custom_field": "custom value"
  },
  "url": "https://yourdomain.com/page",
  "page_title": "Home",
  "page_path": "/",
  "referrer": "https://referrer.com/",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "sessionId": "uuid-session-id",
  "userId": "uuid-user-id",
  "timestamp": "2025-08-02T14:19:12.000Z"
}

This approach ensures that only valid, authorized events are stored, and that your custom event data is accurate, secure, and associated with the correct project.