Analytics Forwarding

The Foldspace SDK can automatically forward agent lifecycle and interaction events to third-party analytics providers already loaded on the page. Currently supported providers are Mixpanel and Amplitude.

Forwarding is opt-in — no events are sent until you explicitly call enableAnalyticsForwarding. All forwarding is wrapped in try/catch and will never block or fail the agent.

`enableAnalyticsForwarding(config?)`

Enables forwarding of agent events to analytics providers found on window.

Parameters:

Parameter	Type	Required	Description
`config`	`AnalyticsForwardingConfig \| null`	No	Provider and event selection. If omitted, all supported providers and all events are enabled by default.

AnalyticsForwardingConfig:

Field	Type	Default	Description
`providers`	`("mixpanel" \| "amplitude")[]`	`["mixpanel", "amplitude"]`	Which analytics providers to forward events to. The provider must be available on `window` (e.g. `window.mixpanel`).
`events`	`string[]`	All events	Which events to forward. If omitted, all supported events are forwarded. Invalid event names are silently skipped.

Returns: The agent instance, enabling method chaining.

Supported Events

All forwarded events are prefixed with foldspace. (e.g. foldspace.agent.ready).

Event	Description
`agent.ready`	Agent has initialized and is ready
`agent.removed`	Agent has been removed from the page
`agent.open`	Agent UI was opened
`agent.closed`	Agent UI was closed
`conversation.created`	A new conversation was started
`conversation.history`	An existing conversation was loaded
`action.called`	An action was executed
`action.response`	An action returned a response

Every event payload is automatically enriched with agentName.

Examples

Forward all events to all available providers:

const agent = foldspace.agent('API-KEY');

agent.enableAnalyticsForwarding();

Forward specific events to Mixpanel only:

agent.enableAnalyticsForwarding({
  providers: ["mixpanel"],
  events: ["agent.ready", "conversation.created", "action.called"]
});

Forward all events to Amplitude only:

agent.enableAnalyticsForwarding({
  providers: ["amplitude"]
});

Notes

The provider SDK (Mixpanel or Amplitude) must already be loaded on the page and accessible via window.mixpanel or window.amplitude. If a requested provider is not found, a warning is logged but no error is thrown.
If called before the agent is ready, the call is queued and replayed once the agent initializes.
Only the payload properties listed in the table above are forwarded per event — no sensitive or unrelated data is sent.
Calling enableAnalyticsForwarding(null) re-enables with default settings (all providers, all events).