----++                                ----++                    ---+++     
  ---+++                                ---++                     ---++      
 ----+---     -----     ---------  --------++ ------     -----   ----++----- 
 ---------+ --------++----------++--------+++--------+ --------++---++---++++
 ---+++---++ ++++---++---+++---++---+++---++---+++---++---++---++------++++  
----++ ---++--------++---++----++---+++---++---++ ---+---++     -------++    
----+----+---+++---++---++----++---++----++---++---+++--++ --------+---++   
---------++--------+++--------+++--------++ -------+++ -------++---++----++  
 +++++++++   +++++++++- +++---++   ++++++++    ++++++    ++++++  ++++  ++++  
                     --------+++                                             
                       +++++++                                               

@bagdock/analytics

Track events, attribute conversions, and measure engagement across Bagdock-powered self-storage apps. The SDK batches events client-side, deduplicates within a configurable window, captures UTM attribution automatically, and flushes gracefully on page unload.

Install

npm install @bagdock/analytics
# or
bun add @bagdock/analytics

How tracking works

Your app calls track() methods. The SDK deduplicates, queues, and flushes events in batches to the Bagdock API over HTTPS.

sequenceDiagram
  participant App
  participant SDK as @bagdock/analytics
  participant API as Bagdock API

  App->>SDK: track({ eventType: 'lead' })
  SDK->>SDK: Dedup check
  SDK->>SDK: Attach UTM metadata
  SDK->>SDK: Queue event

  Note over SDK: Flush on timer (5 s) or batch full (25)

  SDK->>API: POST /api/loyalty/events
  API-->>SDK: 200 OK

On beforeunload and visibilitychange, the SDK flushes with navigator.sendBeacon so no events are lost during navigation.

Get started

import { BagdockAnalytics } from '@bagdock/analytics'

const analytics = new BagdockAnalytics({
  apiKey: 'YOUR_API_KEY',
  autoPageView: true,
})

analytics.trackLead({
  operatorId: 'opreg_acme',
  referralCode: 'REF123',
  metadata: { source: 'pricing_page' },
})

analytics.trackSale({
  operatorId: 'opreg_acme',
  valuePence: 14900,
  currency: 'GBP',
})

await analytics.flush()
analytics.destroy()

How to track UTM attribution

The SDK captures UTM parameters from the URL on init, persists them in sessionStorage for the tab's lifetime, and attaches them as metadata to every event.

// User lands on: https://example.com?utm_source=google&utm_medium=cpc&utm_campaign=spring

const analytics = new BagdockAnalytics({ apiKey: 'YOUR_API_KEY' })

analytics.getUTM()
// → { utm_source: 'google', utm_medium: 'cpc', utm_campaign: 'spring' }

analytics.trackLead({ operatorId: 'opreg_acme' })
// → event metadata includes utm_source, utm_medium, utm_campaign

Parse UTM parameters from any URL:

import { parseUTM } from '@bagdock/analytics'

parseUTM('https://example.com?utm_source=partner&utm_campaign=launch')
// → { utm_source: 'partner', utm_campaign: 'launch' }

How to use with Next.js App Router

Create a provider component that initializes the SDK once and tracks route changes:

'use client'

import { useEffect, useRef } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'
import { BagdockAnalytics } from '@bagdock/analytics'

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
  const pathname = usePathname()
  const searchParams = useSearchParams()
  const ref = useRef<BagdockAnalytics | null>(null)
  const prevPath = useRef('')

  useEffect(() => {
    if (!ref.current) {
      ref.current = new BagdockAnalytics({
        apiKey: process.env.NEXT_PUBLIC_ANALYTICS_API_KEY!,
        autoPageView: true,
      })
    }
    return () => { ref.current?.destroy(); ref.current = null }
  }, [])

  useEffect(() => {
    const path = pathname + (searchParams?.toString() ? `?${searchParams}` : '')
    if (path !== prevPath.current) {
      prevPath.current = path
      ref.current?.trackPageView()
    }
  }, [pathname, searchParams])

  return <>{children}</>
}

Wrap your root layout:

<AnalyticsProvider>
  {children}
</AnalyticsProvider>

How to track embed and widget events

Track renders and clicks from embedded widgets on partner sites:

const analytics = new BagdockAnalytics({ apiKey: 'YOUR_API_KEY' })

analytics.trackEmbedRender('opreg_acme')
analytics.trackClick('link_abc123', 'REF456')

How to track loyalty program events

Track points, rewards, and referrals:

analytics.track({
  eventType: 'points_earned',
  memberId: 'mem_abc',
  operatorId: 'opreg_acme',
  valuePence: 500,
})

analytics.track({
  eventType: 'reward_redeemed',
  memberId: 'mem_abc',
  metadata: { rewardId: 'rwd_xyz', tier: 'gold' },
})

analytics.track({
  eventType: 'referral_completed',
  referralCode: 'REF123',
  memberId: 'mem_abc',
})

Methods

| Method | Description | |--------|-------------| | track(event) | Track any event with full control over the payload | | trackClick(linkId, referralCode?) | Track a link click with optional referral attribution | | trackLead(params) | Track a lead conversion | | trackSale(params) | Track a completed sale | | trackPageView() | Track a page view (captures URL and referrer automatically) | | trackEmbedRender(operatorId?) | Track when an embedded widget renders | | getUTM() | Return the current UTM attribution context | | flush() | Flush the event queue immediately | | destroy() | Flush remaining events, clear timers, remove listeners |

Types

TrackableEvent

interface TrackableEvent {
  eventType: EventType
  linkId?: string
  memberId?: string
  operatorId?: string
  referralCode?: string
  valuePence?: number
  currency?: string
  landingPage?: string
  referrer?: string
  metadata?: Record<string, unknown>
}

EventType

type EventType =
  | 'click' | 'lead' | 'sale' | 'signup' | 'embed_render'
  | 'share' | 'qr_scan' | 'deep_link_open' | 'page_view'
  | 'reward_redeemed' | 'points_earned' | 'referral_completed'

Exports

| Export | Type | Description | |--------|------|-------------| | BagdockAnalytics | class | Main SDK class | | parseUTM | function | Parse UTM parameters from a URL | | BagdockAnalyticsConfig | interface | Constructor config shape | | TrackableEvent | interface | Event payload shape | | EventType | type | Union of supported event type strings | | UTMParams | interface | UTM parameter shape |

How to configure the SDK

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Required. Your Bagdock API key | | baseUrl | string | https://loyalty-api.bagdock.com | API base URL | | flushIntervalMs | number | 5000 | How often to flush queued events (ms) | | batchSize | number | 25 | Max events per flush batch | | dedupWindowMs | number | 500 | Window for dropping duplicate events (ms) | | autoPageView | boolean | false | Track a page view on init | | debug | boolean | false | Log SDK activity to the console |

How batching and deduplication work

Events queue in memory and flush on a timer or when the batch size fills. Duplicate events — defined as matching eventType, linkId, referralCode, and memberId — within the dedup window are dropped silently.

graph TD
  A["track() called"] --> B{"Duplicate?"}
  B -- Yes --> C["Drop"]
  B -- No --> D["Add to queue"]
  D --> E{"Queue full?"}
  E -- Yes --> F["Flush"]
  E -- No --> G["Wait for timer"]
  G --> F

Data privacy and security

• Outbound only. The SDK sends event data to the Bagdock API. It does not read cookies, fingerprint browsers, or collect PII.
• Scoped API keys. Use a key scoped to analytics write access. Never embed keys with broader permissions in client-side code.
• Session-scoped UTM storage. UTM data lives in sessionStorage, scoped to the current tab. It is cleared when the tab closes.
• HTTPS enforced. All API requests use Authorization: Bearer headers over TLS.
• Zero dependencies. No third-party runtime code. The SDK uses native fetch and navigator.sendBeacon.

License

MIT — see LICENSE.