AnalyticsService

Service for client-side analytics tracking via the Lynkow tracker.js script.

Accessible via lynkow.analytics. This is a browser-only service -- all methods are no-ops when called on the server (SSR/Node.js). The service lazily loads the tracker.js script from the API, which auto-initializes using the site ID. The tracker automatically captures pageviews; use trackPageview() for manual SPA navigation tracking and trackEvent() for custom events.

The service respects the site's consent mode: if consent mode is 'opt-in', tracking only starts after consent is granted. The consent state is read from localStorage (_lkw_consent_mode key).

Access via: lynkow.analytics

Methods

9 methods

destroy

destroy(): void

Removes the tracker.js script element from the DOM and resets the service state. After calling destroy(), you can re-initialize by calling init() again. No-op on server.

Returns: void

// Clean up analytics when unmounting (e.g. React useEffect cleanup)
useEffect(() => {
  lynkow.analytics.init()
  return () => lynkow.analytics.destroy()
}, [])

disable

disable(): void

Disables analytics tracking. While disabled, all trackEvent() and trackPageview() calls become no-ops. The tracker script remains loaded; call destroy() to fully remove it.

Returns: void

// Disable tracking when the user revokes analytics consent
lynkow.analytics.disable()

enable

enable(): void

Enables analytics tracking. Tracking is enabled by default when the service is created. Call this to re-enable after a previous disable() call.

Returns: void

// Re-enable tracking after the user grants analytics consent
lynkow.on('consent-changed', (categories) => {
  if (categories.analytics) {
    lynkow.analytics.enable()
  } else {
    lynkow.analytics.disable()
  }
})

getTracker

getTracker(): LynkowAnalyticsGlobal | undefined

Returns the underlying window.LynkowAnalytics global object for advanced usage when you need direct access to the tracker API beyond what this service wraps.

Returns: LynkowAnalyticsGlobal | undefined

init

init(): Promise<void>

Initializes analytics tracking by loading the tracker.js script into the page and waiting for it to auto-initialize. This is idempotent -- calling it multiple times has no effect after the first successful initialization. No-op on server.

The tracker script is loaded from {baseUrl}/analytics/tracker.js with data-site-id and data-api-url attributes. If a consent mode is stored in localStorage, it is passed via data-consent-mode.

Returns: Promise<void>

// Manually initialize analytics in an SPA after client-side routing is ready
const lynkow = createClient({ siteId: '...' })
await lynkow.analytics.init()

isEnabled

isEnabled(): boolean

Returns whether analytics tracking is currently enabled.

Returns: boolean

isInitialized

isInitialized(): boolean

Returns whether the tracker.js script has been loaded and the window.LynkowAnalytics global is available.

Returns: boolean

trackEvent

trackEvent(event: EventData): Promise<void>

Tracks a custom event via the Lynkow analytics tracker. Automatically initializes the tracker if not already loaded. No-op on server or when tracking is disabled.

Returns: Promise<void>

await lynkow.analytics.trackEvent({
  type: 'purchase',
  productId: 'abc123',
  amount: 99.99
})

trackPageview

trackPageview(data?: PageviewData): Promise<void>

Manually tracks a pageview event. The tracker automatically captures pageviews on initial page load, so this method is only needed for SPA client-side navigation (e.g. Next.js App Router route changes). Automatically initializes the tracker if not already loaded. No-op on server or when tracking is disabled.

Returns: Promise<void>

// After SPA client-side navigation
await lynkow.analytics.trackPageview({ path: '/new-page' })

// Or let it auto-detect from the current URL
await lynkow.analytics.trackPageview()