@humany/widget-tracking

Tracking Platform for ACE Knowledge widgets

The Tracking Platform provides an API for tracking and listening to events and user interactions in Humany widgets. Version 2 of this package supports ACE One Widget available in version 5 of the ACE Knowledge widget framework.

Accessing the API

Inside a plugin, pass the current Container instance to the static getInstance() method to access the global instance of TrackingPlatform.

import { TrackingPlatform } from '@humany/widget-tracking';

const MyTrackingPlugin = async (container) => {
    const platform = await TrackingPlatform.getInstance(container);
};

Registering an analyzer

In order to actions events at least one analyzer must be registered on the TrackingPlatform instance. Import GridWidgetAnalyzer and register it with a custom key. Make sure the key is unique to avoid conflicts with existing analyzers.

import { TrackingPlatform, GridWidgetAnalyzer } from '@humany/widget-tracking';

platform.registerAnalyzer(
  'my-analyzer',
  [GridWidgetAnalyzer],
  ({ type, resolve }) => {
    resolve().then((data) => {
      console.log(`action emitted: ${type}`, data);
    });
  },
);

Note: Some actions may result in additional requests being made, which in turn could result in extra costs depending on your subscription level. For this reason it's recommended to check for the type and only resolve the data for relevant actions.

GridWidgetAnalyzer

The GridWidgetAnalyzer is the default analyzer for ACE One Widgets (GridWidget). It exposes the following actions:

WidgetOpen

Emitted when widget is opened. Provides the location object which contains the current route name and params.

Response:

{
    location: Location;
}

ReadGuide

Emitted when a guide is opened.

Provides the current guide.

Response:

{
  guide: GuideItem,
  categories: CategoryItem[],  // Only available for floating widgets
  location: Location,
}

FeedbackGiven

Emitted when a feedback is given to a guide.

Provides the following data:

• guide: Guide which feedback was given to
• categories: Categories which the guide belongs to (only avaible in floating widgets)
• feedbackType: Type of feedback which was given
• location: Current location

Response:

{
  guide: GuideItem,
  categories: CategoryItem[],  // Only available for floating widgets
  feedbackType: string,
  location: Location
}

ContactMethodEnter

Emitted when a contact method is opened, such as an email form.

Provides the contact method and the current location.

Response:

{
  contactMethod: any,
  location: Location,
}

ContactMethodComplete

Emitted when a contact method is submitted.

Provides the contact method and the current location.

Response:

{
  contactMethod: any,
  location: Location,
}

Search

Emitted when a search has been made.

Provides the following data:

• phrase: Search phrase
• hits: Number of hits displayed to user when search was made
• totalHits: Total number of hits search generated
• location: Current location

Response:

{
  phrase: string,
  hits: number,
  totalHits: number,
  location: Location
}

SearchResultClick

Emitted when a search result is clicked on.

Provides the following data:

• position: Position of the search result clicked on among the search result list.
• guide: Guide clicked on
• location: Current location

Response:

{
  position: number,
  guide: GuideItem,
  location: Location
}

ContactMethodOffered

Emitted when contact methods is offered but not yet entered,

{
    contactMethods: {
        id: string;
        title: string;
        type: string;
    }
    [];
}

ContactMethodValidate

Emitted when a contact method is validated but not yet completed,

{
  contactMethod: {
    id: string;
    title: string;
    type: string;
  },
  from: {
    type: string;
    data?: { [key: string]: any };
  };
  valid: boolean;
}

Navigate

Emitted on route change

{
  location: Location,
}

Types

GuideItem {
  id: number;
  title: String;
}

CategoryItem {
  id: number;
  name: String;
}

Location {
  name: string;
  params: { [key: string]: string };
}

WidgetOpenResponse {
  location: Location;
}

ReadGuideResponse {
  guide: GuideItem;
  categories: CategoryItem[]; // (for floating widgets only)
  location: Location;
}

FeedbackGivenResponse {
  guide: GuideItem;
  categories: CategoryItem[]; // (for floating widgets only)
  feedbackType: string;
  location: Location;
}

SearchResponse {
  phrase: string;
  hits: number;
  location: Location;
}

SearchResultClickResponse {
  position: number;
  guide: GuideItem;
  location: Location;
}

ContactMethodEnterResponse {
  contactMethod: any;
  location: Location;
}

ContactMethodCompleteResponse {
  contactMethod: any;
  location: Location;
}