useSpTrackingStore

import { useSpTrackingStore } from '@bbc/front-end-kit/vue/showpad'

The useSpTrackingStore manages all Showpad analytics tracking within the application. It provides a unified, session-aware interface for logging user interactions and page navigation events, making it easy to add consistent tracking across all components and routes in the kit and in projects.

Overview

The store initializes a tracking session on first call to init(), generating a unique sessionId and capturing session metadata (user, app, client). It then exposes methods to track click events and page navigation in a format compatible with Showpad's analytics pipeline.

Tracking calls are blocked before the store is initialized, so it is safe to place them in components even if init() has not yet been called — they will simply no-op with a console warning.

Getting started

import { useSpTrackingStore } from '@bbc/front-end-kit/vue/showpad'

const trackingStore = useSpTrackingStore()

// Set session metadata before initializing
trackingStore.experienceType = 'product-catalog'
trackingStore.clientName = 'Acme Corp'
trackingStore.appName = 'Sales App'

// Initialize the tracking session
trackingStore.init()

// Track a click / user-interaction event
trackingStore.trackClickEvent({
    label: 'Get Started',
    category: 'button'
})

// Track a page navigation event
trackingStore.trackPageviewEvent({
    from: currentRoute,
    to: nextRoute,
    type: 'page'
})

API

State & Properties

`initialized`

Reactive boolean indicating if the tracking session has been initialized. Tracking calls are silently blocked while this is false.

Values: ComputedRef<Boolean>

`experienceType`

The type of Showpad experience (e.g. 'product-catalog'). Populated before calling init() and included in every tracked event's session metadata.

Values: Ref<String | null>

`clientName`

The client or organization name. Populated before calling init() and included in session metadata.

Values: Ref<String | null>

`appName`

The application name. Populated before calling init() and included in session metadata.

Values: Ref<String | null>

Methods

`init ()`

Sets up the tracking session. It:

Generates a unique sessionId.
Records the appStartTime.
Populates user-specific metadata from useSpStore.

Calling init() more than once is a no-op — the session is only created once per store lifetime.

Call after userInfo is available

init() reads session metadata from useSpStore. Call it after useSpStore.init() has resolved so that user and device info is populated. Tracking calls before init() are silently blocked with a console warning.

args parameter is currently unused

init() accepts an args object parameter but does not currently use it. It exists as a placeholder for future configuration options.

`trackClickEvent ({ label, category })`

Tracks a custom interaction event.

label (String, Required): Descriptive name for the action.
category (String, Default: 'button'): Type of UI element interacted with.

Returns: Promise<void>

Throws: If label is missing, or if the underlying SDK trackEvent call fails.

`trackPageviewEvent ({ from, to, type })`

Tracks navigation between views. Automatically calculates pageDuration since the last call and normalizes route information into readable tracking IDs using nameToId.

from (Object): The Vue Router route object for the previous page.
to (Object): The Vue Router route object for the destination page. If the route has a meta.getName function, it will be used to derive the display name.
type (String, Default: 'page'): The type of pageview event.

After each call, session.sourceId and session.sourceName are updated to the destination route — these become the from values for the next pageview. The event is dispatched after a 50ms delay to ensure the DOM has settled on fast navigations. Vue reactive properties are stripped from the event object via an internal cleanVueProperties pass before being sent to the SDK.

Returns: Promise<void>

Throws: If the underlying SDK trackEvent call fails.

Utility Functions

The store also exports several utility functions for URL and string manipulation:

`urlToSlug (url)`

Converts a file path or URL into a clean, lowercase tracking ID (e.g. '/page_webapp/home.html' → 'home').

`nameToId (name)`

Normalizes a display name into a consistent tracking ID (e.g. 'Product Detail' → 'product-detail').

Usage Note

Registration of page views is typically handled once in the main application router guard:

router.afterEach((to, from) => {
    trackingStore.trackPageviewEvent({ from, to })
})

Click tracking should be added to interactive components like buttons and cards. Set experienceType, clientName, and appName on the store before calling init() so that all subsequent events carry the correct session metadata.