Custom tracking

Tracker interface

In your app, you can add custom Trackers corresponding to this interface:

Copy
Copied
export interface BaseTrackingEvents {
  trackProduct: (
    props: TrackProductProps,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
  trackCartCheckout: (
    props: TrackCartProps,
    context: TrackingFunctionContext,
    eventId?: string,
    callback?: (response: Response) => void
  ) => void;
  trackCart: (
    props: TrackCartProps,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
  trackList: (
    props: TrackListProps,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
  trackPageView: (
    props: TrackPageProps,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
  trackExperiment: (
    props: TrackExperimentProps,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
  trackUser: (
    props: TrackUserProps,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
  trackLogin: (
    props: any,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
  trackRegister: (
    props: any,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
  trackAddToWishList: (
    props: TrackAddToWishListProps,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
  consent: (
    props: BaseConsentEvents,
    context: TrackingFunctionContext,
    eventId?: string
  ) => void;
}

type Consent = "granted" | "denied";

interface BaseConsentEvents {
  ad_storage: Consent;
  analytics_storage: Consent;
  personalization_storage: Consent;
  security_storage: Consent;
  // Also possible to have custom consents
  [key: string]?: Consent;
}

export interface Tracker extends Partial<BaseTrackingEvents> {
  name: string;
  initBrowser?: (opts: InitOptions) => void;
}

Listening to events

Below we define a custom tracker called myTracker.

Built-in events

There are four built-in events:

  • trackProduct
  • trackCartCheckout
  • trackList
  • trackPageView

These are bound automatically to corresponding methods in the Tracker.

Custom tracker

Using built-in events

Copy
Copied
boot(
  <Theme>
    <Shop />
  </Theme>,
  {
    ...config,
    trackers: [
      {
        name: "myTracker",
        trackPageView(props) {
          console.log("Viewed page:", props);
        },
      },
    ],
  }
);

Using custom events + built-in events

Copy
Copied
boot(
  <Theme>
    <Shop />
  </Theme>,
  {
    ...config,
    trackers: [
      {
        name: "myTracker",
        initBrowser({ trackerRegistry }) {
          trackerRegistry.on("MY_CUSTOM_EVENT", (args, context) => {
            console.log("MY_CUSTOM_EVENT", { args, context });
          });
        },
        /**
         * Note that we don't need to call `trackerRegistry.on('..')` for built-in methods
         */
        trackPageView(props) {
          console.log("Viewed page:", props);
        },
      },
    ],
  }
);

Triggering events

When triggering events, you need to use either the useTracker-hook or the <Analytics />-component. The hook is useful for user actions like clicks and the component is useful for views.

You call the track()-method with the data about the event you're tracking.

<Analytics />

Copy
Copied
import Analytics from '@jetshop/core/analytics/Analytics';

// [..]

const ProductPage = () => (
  <>
    {/* [..] */}
    <Analytics
      event={{ name: 'MY_TRACKER_EVENT', payload: { foo: 'bar' }}}
    />
  </>
)
>

useTracker()

Copy
Copied
import { useTracker } from '@jetshop/core/analytics/Analytics';

// [..]

const CartItem = () => {
  const track = useTracker();

  return (
    // [...]
    <button
      onClick={() => {
        incrementQuantity(item.id);
        track({
          name: 'USER_INCREMENTED_PRODUCT',
          payload: { foo: 'bar' }
        });
      }}
      />
  )
}
>

Event listeners

Event listeners receives two arguments

  • props : Whatever date what was emitted when calling emit() .
  • context : Contextual data about the current view.

Walkthrough: Add custom tracker

1. Add a Tracker in boot sequence

In order to add a custom tracker you need to hook into the tracking registry.

Start by adding a tracker listener in client.js:

Copy
Copied
boot(
  <Theme>
    <Shop />
  </Theme>,
  {
    ...config,
    trackers: [
      {
        name: "myTracker",
        initBrowser({ trackerRegistry }) {
          // [..] Add any `<script>`-tags or anything that might be needed

          trackerRegistry.on("MY_TRACKER_EVENT", (args, context) => {
            console.log("MY_TRACKER_EVENT", { args, context });
          });
          trackerRegistry.on("USER_INCREMENTED_PRODUCT", (args, context) => {
            console.log("USER_INCREMENTED_PRODUCT", { args, context });
          });
        },
      },
    ],
  }
);

2. Trigger event

Example: Trigger event on user action

Below we trigger USER_INCREMENTED_PRODUCT when user clicks correlated button.

Copy
Copied
import { useTracker } from '@jetshop/core/analytics/Analytics';

// [..]

const CartItem = () => {
  const track = useTracker();

  return (
    // [...]
    <button
      onClick={() => {
        incrementQuantity(item.id);
        track({
          name: 'USER_INCREMENTED_PRODUCT',
          payload: { foo: 'bar' }
        });
      }}
      />
  )
}
>

Example: component viewed

This will only trigger emit when component gets mounted.

Copy
Copied
import Analytics from '@jetshop/core/analytics/Analytics';

// [..]

const ProductPage = () => (
  <>
    {/* [..] */}
    <Analytics
      event={{
        name: 'MY_TRACKER_EVENT',
        payload: { foo: 'bar' }
      }}
    />
  </>
)
>

3. Check console

Control that your event is visible in the console when performing the action.

Copyright © Norce 2023. All right reserved.