AnalyticsCollector

Subscribes to all GuideFlow tour lifecycle events and forwards normalised AnalyticsEvent objects to one or more registered transports.

Constructor

import { AnalyticsCollector } from '@guideflow/analytics'

new AnalyticsCollector(opts?: CollectorOptions)

CollectorOptions

Option	Type	Description
userId	string	User / session identifier injected into every event
globalProperties	Record<string, unknown>	Static properties merged into every event payload

Methods

addTransport(transport)

Register a transport to receive events. Returns this for chaining.

addTransport(transport: AnalyticsTransport): this

const collector = new AnalyticsCollector({ userId: 'user-123' })
  .addTransport(new PostHogTransport())
  .addTransport(new WebhookTransport({ url: '/api/analytics' }))

---

attach(instance)

Attach the collector to a GuideFlow instance. Begins listening to tour events immediately. Returns an unsubscribe function.

Calling attach() a second time before detach() is a no-op to prevent duplicate reporting.

attach(gf: GuideFlowInstance): () => void

const detach = collector.attach(gf)

// Later, to stop tracking:
detach()

---

detach()

Unsubscribes from all GuideFlow events.

detach(): void

---

flush()

Calls flush() on all registered transports that support it (e.g. for batched transports). Returns a promise that resolves when all transports have flushed.

async flush(): Promise<void>

Tracked Events

Event name	Fired when
guideflow.tour.started	A tour begins
guideflow.tour.completed	A tour reaches the final step
guideflow.tour.abandoned	A tour is dismissed mid-flow
guideflow.step.viewed	The user enters a step
guideflow.step.exited	The user exits a step (includes dwell_ms)
guideflow.step.skipped	A step is skipped

Full Example

import { createGuideFlow } from '@guideflow/core'
import { AnalyticsCollector, PostHogTransport, WebhookTransport } from '@guideflow/analytics'

const gf = createGuideFlow({ theme: 'bold' })

const collector = new AnalyticsCollector({
  userId: currentUser.id,
  globalProperties: { app_version: '2.0.0' },
})
  .addTransport(new PostHogTransport())
  .addTransport(new WebhookTransport({ url: 'https://myapp.com/api/tours/events' }))

collector.attach(gf)

See Also

• Transports — PostHog, Mixpanel, Amplitude, Segment, Webhook
• ExperimentEngine — A/B testing