Events

This page lists all the events available in the module-data-analyticstracker. For information on how to contribute new events, please see our Contributing Guide. General recommendations, roles, and FAQs can be found on our Notion page.

Index

Core Events

Identify

Purpose: Identify the user.

When to use:

type Identify = {
  id: string;
  type?: 'administrator' | 'assessor' | 'author' | 'editor' | 'instructor' | 'learner' | 'manager' | 'support' | 'user';
  organisationId?: string;
  cultureInfo?: string; // e.g. 'en-US'
  isInternal?: boolean;
  content?: {
    packageId?: string;
    packageTitle?: string;
    method?: string;
    methodId?: string;
    edition?: string;
    targetYear?: string;
    businessUnit?: string;
    productType?: string;
    grade?: string;
    schoolType?: string;
    discipline?: string;
    semanticVersion?: string;
  };
};

tracker.identify({
  id: 'my-user-id',
  type: 'instructor',
  organisationId: 'my-guid',
  cultureInfo: 'en-US',
  isInternal: true,
  content: {
    packageId: 'pkg123',
    packageTitle: 'Math 101',
    method: 'online',
    methodId: 'method123',
    edition: '2nd',
    targetYear: '2024',
    businessUnit: 'education',
    productType: 'course',
    grade: '10',
    schoolType: 'high-school',
    discipline: 'mathematics',
    semanticVersion: '1.0.0',
  },
});

Page

Purpose: Track when a user has loaded or navigated to a specific page.

IMPORTANT:

type Page = {
  category: string;
  subCategory?: string;
  type: string;
  id?: string;
  brand?: { name?: string };
  pageName?: string;
  metadata?: any;
};

type Referrer = {
  module?: string;
  label?: string;
  itemId?: string;
  elementId?: string;
};

tracker.page({
  category: 'content',
  subCategory: 'learning-content',
  type: 'quiz',
  id: 'my-quiz-id',
  brand: { name: 'nectar' },
  pageName: 'my-page-name'
});

If a referrer event is tracked right before the page event, referrer data will be added to the event.

tracker.referrer({
  module: 'main-menu',
  label: 'Do a quiz',
  itemId: 'quiz',
});

For the referrer event, it is recommended to use attribute-based tracking.

<button title="Take me to the quiz" data-mdat="referrer" data-mdat-module="my-amazing-button"></button>

Custom Events

All custom events have the following base fields to specify where they occurred in the DOM:

type BaseFields = {
  module?: string; // kebab-case, identifies the section of the page where the event occurred
  itemId?: string; // kebab-case, identifies the item on which the event occurred
  elementId?: string; // kebab-case, identifies the (HTML) element on which the event occurred
  frameCorrelationId?: string; // kebab-case, identifies the frame in which the event occurred
};

When to use: When a user clicks on a link that leads outside of the current website.

Available actions: clicked

type ExitLink = {
  url: string;
  label?: string;
};

tracker.exitLinkClicked({
  url: 'https://www.infinitaslearning.com',
  label: 'Go to Infinitas',
  module: 'main-menu',
  itemId: 'infinitas-link',
});

File

When to use: When a user downloads, previews, or uploads a file.

Available actions: downloaded, previewed, uploaded

type FileDownloaded = {
  name?: string;
  id?: string;
  source?: string;
  extension?: string;
  url?: string;
};

type FilePreviewed = {
  name?: string;
  id?: string;
  source?: string;
};

type FileUploaded = {
  name?: string;
  id?: string;
  source?: string;
  extension?: string;
  url?: string;
  sizeMb?: number;
};

tracker.fileDownloaded({
  url: 'https://www.infinitaslearning.com/report.pdf',
  name: 'Answerbook',
  id: '123abc',
  source: 'edify',
  extension: 'pdf',
});

Form

When to use: When a user interacts with a form.

Available actions: submitted, clicked

The ProductEntity is defined in the e-commerce events documentation.

type FormSubmitted = {
  name: string; // Name of the form
  id: string; // The ID of the form.
  product?: ProductEntity;
};

type FormClicked = {
  name: string; // Name of the form
  id: string; // The ID of the form.
  clickText: string; // The label or text of the clickable element.
  product?: ProductEntity;
};

tracker.formSubmitted({
  id: 'form-66',
  name: 'Zichtzending Getal & Ruimte JR',
});

Frame

When to use: Track interactions with frames on top of the page like pop-ups or widgets. Events that occur within the frame can be related to the frame by providing the frame-correlation-id.

Available actions: opened, closed, moved

type Frame = {
  type: string;
  id?: string;
  frameType: 'widget' | 'confirmation' | 'pop-up';
};

const frame = await tracker.frameOpened({
  type: 'calculator',
  id: 'home-page-calulator-widget',
  frameType: 'widget',
});

type ClosedFrame = Frame & {
  result: 'confirmed' | 'rejected' | 'cancelled';
  frameCorrelationId: string; // Required for this event
};

const closedFrame: ClosedFrame = {
  ...frame!, // Includes the frame-correlation-id
  result: 'cancelled',
};
tracker.frameClosed(closedFrame);

type MovedFrame = Frame & {
  locationX?: number;
  locationY?: number;
  frameCorrelationId: string; // Required for this event
};

const movedFrame: MovedFrame = {
  ...frame!, // Includes the frame-correlation-id
  locationX: 400,
  locationY: 500,
};
tracker.frameMoved(movedFrame);

Item List

When to use: To track a list of items, often used for display or filtering/searching.

Available actions: displayed, filtered, ordered

type ItemList = {
  type: string;
  count?: number;
  pageSize?: number;
  pageNumber?: number;
  displayMode?: string;
  order?: {
    field?: string;
    direction?: 'asc' | 'desc';
  };
};

tracker.itemListDisplayed({
  type: 'books',
  count: 58,
  pageSize: 20,
  pageNumber: 3,
  displayMode: 'grid-view',
});

type FilteredItemList = ItemList & {
  searchTerm?: string;
  facets?: Record<string, (string | number | boolean | Date)[]>;
};

tracker.itemListFiltered({
  type: 'books',
  // ... other properties
  facets: {
    subject: ['english', 'biology'],
    'target-year': ['1', '2'],
  },
});

type ItemListOrdered = ItemList & {
  parentId?: string;
  parentDescription?: string;
  items: {
    id: string;
    description?: string;
    sequence?: number;
  }[];
};

tracker.itemListOrdered({
  type: 'content-manage',
  // ... other properties
});

Element

When to use: Whenever there is no better semantic event available.

Available actions: clicked, loaded, blurred

tracker.elementClicked({
  elementId: 'example-checkbox',
  type: 'checkbox',
  value: 'true',
  module: 'task-planner',
});

tracker.elementLoaded({
  elementId: 'main-image',
  type: 'image',
  url: '/images/main.png',
});

tracker.elementBlur({
  elementId: 'search-input',
  type: 'text-input',
  value: 'search term',
});

Experiment

When to use: For A/B tests or other experiments.

Available actions: started

type Experiment = {
  experimentName: string;
  experimentGroup: 'control' | 'variant';
};

tracker.experimentStarted({
  experimentName: 'my-experiment',
  experimentGroup: 'control',
});

Caveat

When you track events with data-mdat attributes (e.g., data-mdat="element-clicked") and the action also causes a navigation, you might want to submit the current URL to track the right page context. You can do that by setting the data-mdat-url attribute. In a JSX/TSX context, this would look like data-mdat-url={window.location.href}. This is not needed if the URL does not change.

Metadata Property

The Data Team has introduced a flexible metadata property. If you need to send additional context that is not part of the core schema, the metadata property can be used.

tracker.elementClicked({
  elementId: 'example-checkbox',
  type: 'checkbox',
  value: 'true',
  module: 'task-planner',
  itemId: 'add-content-unit',
  metadata: JSON.stringify({ source: 'testbed', flag: 'alpha build', features: ['a', 'b', 'c'] }),
});