Skip to content
Foldspace Docs

Custom Events

Open in ChatGPT Open in Claude

Record custom events from your product with foldspace.track(). Each event is attributed to the current identified user and flows into Foldspace analytics — every event shows up in the Event Explorer, and the things people do in your app (not just their agent conversations) become available across the Audience, Segments, and Reports.

This is the inbound counterpart to analytics forwarding: forwarding pushes agent events out to Mixpanel or Amplitude, while track() brings your product events in to Foldspace.

track(eventName, properties?)

Section titled “track(eventName, properties?)”
foldspace.track("Report_Exported", {
  report_type: "quarterly_summary",
  format: "pdf",
  page_count: 12,
  workspace: "acme-inc",
});
ParameterTypeRequiredDescription
eventNamestringYesThe name of the event, e.g. Report_Exported. Use a consistent, stable name so events group correctly in analytics.
propertiesobjectNoA flat map of custom attributes describing the event. Values should be strings, numbers, or booleans.

Naming events and properties

Section titled “Naming events and properties”
  • Keep event names stable and human-readable — Report_Exported, Checkout_Completed, Plan_Upgraded. The same name should always represent the same action.
  • Use snake_case keys for properties and keep them flat (no nested objects or arrays). Flat string/number/boolean values are what segments and report filters can group and filter on.
  • Send the same property keys every time you fire a given event, so values line up across users.

Attributing events to a user

Section titled “Attributing events to a user”

Events are attached to the user Foldspace currently knows about. To make sure events land on the right person, identify your user first via User context:

// Identify the signed-in user once, early in the page lifecycle.
foldspace.agent("AGENT_NAME").setUser({
  id: "user_123",
  email: "ada@example.com",
});


// Later, anywhere in your app, record what they do.
foldspace.track("Plan_Upgraded", {
  from_plan: "free",
  to_plan: "pro",
  seats: 5,
});

If no user has been identified yet, the event is still recorded and associated with the current anonymous visitor.

Examples

Section titled “Examples”

Track a simple event with no properties:

foldspace.track("Pricing_Page_Viewed");

Track a conversion with structured attributes:

foldspace.track("Checkout_Completed", {
  order_id: "ord_8821",
  currency: "USD",
  amount: 129.0,
  items: 3,
  coupon_applied: true,
});

Notes

Section titled “Notes”
  • Call track() any time after the embed snippet has loaded on the page.
  • Only the properties you pass are sent — Foldspace does not collect additional page data with the event.
  • Custom events appear in the Event Explorer and alongside agent activity in a user’s profile, and can be used to build segments and reports.
Section titled “Related”