@bagdock/analytics

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

@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.