Custom Events & API

Dispatch structured telemetry payloads and conversion milestones using the non-blocking window.telemetry.trackEvent() client API.

JSON-Schema v7Max Payload: 32 KBNon-blocking Dispatch

trackEvent() API Reference

The Tracium client beacon mounts a global telemetry controller on the window object. Custom events are dispatched asynchronously using the following signature:

TypeScript Interface & Call Signature

declare global {
  interface Window {
    telemetry?: {
      trackEvent: (
        eventName: string,
        properties?: Record<string, string | number | boolean | null>
      ) => void;
    };
  }
}

// Invocation
window.telemetry?.trackEvent("subscription_upgraded", {
  tier: "enterprise_annual",
  mrr_delta: 4800,
  seats: 50,
  is_trial_conversion: true
});

Frontend Implementation Patterns

In Next.js React Server Components (RSC), instrument client component event handlers:

src/components/CheckoutAction.tsx

"use client";

import React, { useTransition } from "react";

export function CheckoutAction({ planCode, priceUsd }: { planCode: string; priceUsd: number }) {
  const [isPending, startTransition] = useTransition();

  const handleCheckout = () => {
    // Non-blocking telemetry emission
    if (typeof window !== "undefined" && window.telemetry) {
      window.telemetry.trackEvent("checkout_initiated", {
        plan: planCode,
        amount: priceUsd,
        currency: "USD",
        client_ts: Date.now()
      });
    }

    startTransition(async () => {
      window.location.assign(`/api/checkout/stripe?plan=${planCode}`);
    });
  };

  return (
    <button
      onClick={handleCheckout}
      disabled={isPending}
      className="rounded-md bg-foreground text-background px-4 py-2 font-mono text-xs font-semibold"
    >
      {isPending ? "Routing..." : "Confirm Provisioning"}
    </button>
  );
}

JSON Wire Schema & Validation Rules

Inbound event payloads are validated against the following schema rules at the ingestion edge:

Field / Attribute	Wire Type	Constraint	Technical Description
name	string	REQUIRED	Event identifier. Must match ^[a-z0-9_-]{1,64}$. Max 64 characters.
properties	object	OPTIONAL	Flat JSON key-value map. Max 50 top-level keys. Max payload size: 32 KB.
timestamp	integer (epoch ms)	OPTIONAL	Client timestamp in milliseconds. Clock skew tolerated up to +/- 10 minutes.

Payload Constraints & Ingestion Throughput

Max Payload Size

32 KB

Per HTTP wire request

Key Cardinality

50 Keys

Per event dictionary

Ingestion Throughput

10,000 / sec

Auto-scaled edge cluster