@humany/widget-tracking

Exposes API methods for tracking and listening to widget events and user interactions.

Using the plugin

This plugin exposes a method called action which is used for catching events in your widgets. To access the method inject it into the settings of your plugin.

This will allow you to access the data and handle them as needed.

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

humany.configure((config) => {
  config.plugin(TrackingPlugin, {
    action: ({ type, resolve })  => {
      // ...
    },
    analyzers: [],
  });
});

Exposed methods & Configuration

To listen to a API response add the action method to your plugin settings.

Action

The action method returns an object with two properties:

• type: The type of action (e.g. ReadGuide). You can find all types of API responses further down.
• resolve: A function which returns a promise that resolves to the data returned.

Analyzers

Under the hood the tracking plugin utilizes analyzers to capture events and dispatch the needed data. In order to listen to custom events you can write your own analyzers and add them to the analyzers array.

Example:

class CustomAnalyzer {
  constructor(container, emit) {
    const { events } = container.get('$widget');

    // Here you listening for the event "widget:move-outside-viewport" 
    // and dispatches a custom event (MoveOutsideViewport) that you can listen to in your plugin
    events.subscribe('widget:move-outside-viewport', (e, data) => {
      emit('MovedOutsideViewport', {
        message: 'moved outside viewport',
      });
      
      // OR you can use a function which returns a promise
      emit('MovedOutsideViewport', () => Promise.resolve({
        message: 'moved outside viewport',
      }));
    });
  }
}

humany.configure((config) => {
  config.plugin(TrackingPlugin, {
    action: ({ type, resolve })  => {
    
      if (type === 'MovedOutsideViewport') {
        resolve()
          .then(data => {
            /*
              Here you have access to the data dispatched from your custom analyzer.
              data === { message: 'moved outside viewport' }
            */
          });
      }
    },
    analyzers: [CustomAnalyzer], // add your custom analyzers here
  });
});

API Responses

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
}

Widget Specific Events

Bot Widget

Interact

Emitted upon any interaction with the bot.

{
  type: 'browseCategory' | 'browseCategories' | 'phrase' | 'help' | 'contact' | 'comment';
  phrase?: string;
  category?: string;
}

NoAnswer

Emitted when bot is unable to find an appropriate answer.

{
  type: 'no-answer',
}

DisplayContactMethodCategories

Emitted when viewing contact method categories in the contact method selector

{
  categories: {
    title: string;
  }[],
}

ContactMethodExpand

Emitted when a contact method that requires a click before view, is expanded/clicked.

{
  contactMethod: {
    id: string;
    title: string;
    type: string;
  };
}

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;
}

DialogAction

Emitted when a dialog action is executed.

{
  type: 'dialogAction';
  id: string;
  title: string;
}

EntityResponse

Emitted when a list of dialog options is displayed.

{
  items: {
    id: string;
    title: string;
  }[];
}

SuggestedGuides

Emitted when a list of suggested guides is displayed.

{
  items: {
    id: string;
    title: string;
  }[];
}

ProposedIntent

Emitted when an entry with an intent is displayed.

{
  intent: {
    id: string;
    name: string;
  };
  items: {
    title: string;
  }[];
}

RenderTriggerButton

Emitted when trigger button is rendered.

{}

Floating Widget

Navigate

Emitted on route change

{
  location: Location,
}

Legacy Support

It is possible to use this plugin with older versions. In order to use the plugin with legacy versions, configure the plugin as below:

humany.configure(config => {
  const analyticsPluginSettings = {
    action: ({ type, args, location })  => {
      // ...
    },
    navigate: ({ type, args }) => {
      // ...
    },
  };

  const legacyAnalyticsPlugin = new LegacyAnalyticsPlugin(analyticsPluginSettings);
  config.registerPlugin(legacyAnalyticsPlugin);
});

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;
}