@vtex/raccoon-analytics

Send events to track your frontend apps.

This is based on the work done on the following document: Analytics for frontend apps: setup

Usage

Add the dependency to your package file:

yarn add @vtex/raccoon-analytics

Import the sendAnalyticEvent function where you want to create an event:

import { sendAnalyticEvent } from '@vtex/raccoon-analytics'

Trigger the function:

sendAnalyticEvent(APP_NAME, {
  eventCategory: 'view',
  eventName: 'index-page-test',
})

The function accepts two parameters:

1. APP_NAME, a string

[!IMPORTANT] It should have the same value for all events in a same app

2. An object with the type DataIngestionApiFields:

type DataIngestionApiFields = {
  /**
   * The name of the event. It has to be unique throughout the app.
   */
  eventName: string
  /**
   * The type of the event, generally click for a user action and view for a page view.
   *
   * @default 'click'
   */
  eventCategory?: 'click' | 'view' | 'apiAnswer' | 'webVitals'
  /**
   * Additional informations for webVitals
   */
  metric?: WebVitalsMetric
} & Record<string, string>

Here are the fields of the WebVitalsMetric type:

type WebVitalsMetric = {
  id: string
  name: 'FCP' | 'LCP' | 'CLS' | 'FID' | 'TTFB' | 'INP'
  delta: number
  entries: []
  navigationType: 'navigate' | 'reload' | 'back_forward' | 'prerender'
  rating: 'good' | 'needs-improvement' | 'poor'
  value: number
}

The following fields are also sent automatically:

const commonFields: Record<AdminContextFields, string> = {
  account: adminContext.account,
  locale: adminContext.locale ?? 'undefined',
  production: adminContext.production ? 'true' : 'false',
  workspace: adminContext.workspace,
  device: deviceType,
  basePath: adminContext.basePath,
  path: adminContext.path ?? 'undefined',
}

adminContext comes from the adminStore of the @vtex/raccoon-next package.

Click events

The most common event. Track user interactions on links, buttons, drawers, etc. The eventCategory property has the default value click so you do not need to include it for this event.

sendAnalyticEvent(APP_NAME, {
  eventCategory: 'click',
  eventName: 'index-page-back-button',
})

View events

Events for page views:

sendAnalyticEvent(APP_NAME, {
  eventCategory: 'view',
  eventName: 'index-page',
})

Extra possibilities

As stated by the Record<string, string> part of the type DataIngestionApiFields, you can add extra informations thanks to the fact that we use the schemaless approach.

Web Vitals

You can send Web Vitals events to track the performance of your app. Here is an exmaple with the next/web-vitals package for NextJS:

import { useReportWebVitals } from 'next/web-vitals'

useReportWebVitals((metric) => {
  sendAnalyticEvent(APP_NAME, {
    eventCategory: 'webVitals',
    eventName: `webvitals_${route}`,
    webVitalMetric: metric,
  })
})

Here we use a dynamic page with {route} so that we can filter the events by page.

Fields of the WebVitalsMetric type:

type WebVitalsMetric = {
  id: string
  name: 'FCP' | 'LCP' | 'CLS' | 'FID' | 'TTFB' | 'INP'
  delta: number
  entries: []
  navigationType: 'navigate' | 'reload' | 'back_forward' | 'prerender'
  rating: 'good' | 'needs-improvement' | 'poor'
  value: number
}

Time on page

Track how much time a user spends on a page before performing an action:

sendAnalyticEvent({
  eventName: 'index-page-back-button',
  timer: a_number_in_ms,
})

Example with React:

export const usePageTimeTracker = () => {
  const startTimeRef = useRef<number | null>(null)

  useEffect(() => {
    startTimeRef.current = Date.now()

    // Cleanup on unmount
    return () => {
      startTimeRef.current = null
    }
  }, [])

  const getTimeSpent = () => {
    if (startTimeRef.current !== null) {
      const timeSpent = Date.now() - startTimeRef.current

      return timeSpent
    }

    return 0
  }

  return { getTimeSpent }
}

const { getTimeSpent } = usePageTimeTracker()

sendAnalyticEvent({
  eventName: 'index-page-back-button',
  time_on_page: getTimeSpent(),
})

More infos

Send your question on the #admin-platform or #frontend-chapter Slack channels.