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);
        },
      },
    ],
  }
);

Disabling default tracking

The DynamicRoute component triggers automated tracking for the different page types. If you want to disable this behavior for the PDP (for example if you want to include selected variant tracking always), you can add tracking: { disableDefaultProductTracking: true } in shop.config (introduced in Flight v6.3.5).

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.