Technical Overview

NanoInsights 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 insights 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

• Metric Type/Name/Value: The type, name, and value of the performance metric reported (e.g., LCP, FCP, CLS, TTFB).
• Session ID: A unique identifier for the user session (generated if not provided, must be a valid UUID).
• User ID: If available, the user's unique identifier.
• Project ID: The internal ID of the project.
• Page Info:
  • Full URL
• 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 insight event occurred.
• Navigation Timing: Optional detailed data (dns_lookup, tcp_connection, server_response, dom_interactive, dom_complete, page_load, total_page_load).
• Context: Any additional fields sent in the event payload.

Data Storage & Processing

• Performance insights 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",
  "metric_type": "web-vitals",
  "metric_name": "LCP",
  "metric_value": 2121,
  "metric_unit": "ms",
  "url": "https://yourdomain.com/page",
  "referrer": "https://referrer.com/",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "sessionId": "uuid-session-id",
  "timestamp": "2025-08-02T14:19:12.000Z",
  "dns_lookup": 22,
  "tcp_connection": 11,
  "server_response": 101,
  "dom_interactive": 570,
  "dom_complete": 700,
  "page_load": 800,
  "total_page_load": 850,
  "context": {
    "custom_field": "value"
  }
}

This approach ensures that only valid, authorized insights are stored, and that performance data is accurate, secure, and associated with the correct project.