@episerver/telemetry

A telemetry API for consistent anonymous product feature tracking used in Episerver.

Currently wraps Application Insights JS SDK but this can change to another service or multiple services in the future.

Installation

yarn

yarn add @episerver/telemetry

npm

npm install @episerver/telemetry

Importing

import { Owner, TrackerFactory, ITracker } from "@episerver/telemetry";

Usage

The @episerver/telemetry package exports several classes to make telemetry usage consistent across Episerver's products. The main class being TrackerFactory that creates a factory object that can be used once in an application, to create multiple ITracker - one for each owning team.

When only one owner exists in the product the TrackerFactory can be used as a temporary object to create the ITracker, i.e.:

import { Owner, TrackerFactory, ITracker } from "@episerver/telemetry";
const tracker: ITracker = (new TrackerFactory({
    config: {
        instrumentationKey: "[Application Insights key]"
    },
    authenticatedUserId: "[Hashed (SHA512) derived from the user email without salt. If the user email is not available, the username can be used instead.]",
    accountId: "[Hashed (SHA512) derived from a unique customer account identifier without salt. The license key should be used if it's available.]",
    customProperties: {
        // Any additional data that should be sent on each event.
    }
})).getTracker("['Owner' enum value or short lowercase alias for who owns the data]);

Then use that tracker object to send analytics where and when needed. Do not track more than you need to analyze a feature's worth to the user.

ITracker has two main methods:

trackPageView: Send a page view tracking event. If the product uses Platform Navigation this method is not needed.
trackEvent: Send a custom tracking event.

Read more about event naming under "Event naming convention" before publishing any events.

Example from CMS UI task creation trackers:

tracker.trackEvent("edit_contentCreated", {
    contentType: isPage ? "page" : "block",
    entryPoint: entry.entryPoint,
    isLocalAsset: this.createAsLocalAsset
});

Event naming convention

In order to keep the events tidy and clean across all our products we want to adhere to a naming convention.

Pattern / Format

Owner => Context(optional) => Action

Owner: Which team does the event belong. Owner is required to be set before using the tracker. Use the Owner enum or if your team is not listed use an appropriate lowercase acronym similar to the enum.
Context: Which feature is the event from.
Action: What was the action taken.

All events are formatted like this with words camelCased.

ownerName_actionName
ownerName_contextName_actionName

Some examples:

cms_publish
cms_click
cms_projectView_batchApprove

Property Name

Words are camelCased. Underline (_) is used as separator. Context is optional.

propertyName
contextName_propertyName

Do

cms_sign_in
cms_sign_out

Its good to be consistent.

Don't

cms_Sign_IN
cms_Sign_out

The name should follow the naming convention and be consistent.

What is the correct context?

The context is mainly good for sorting and grouping similar events to each other but that have distinct actions.

Do

cms_project_create
cms_project_delete

We have the context of project but with two distinct actions.

Don't

cms_edit_createProject
cms_edit_time
cms_edit_buttonClick

The shared context "edit" is too broad to be applied to all three events and some actions contain their own context.

When should I use properties or not?

Always consider what you want to compare and what the question is that you want to answer.

Do

cms_publish
    commandType => "smart" | "inline" | "default"

Comparing "commandType" from the same action "publish" makes sense.

Do

cms_edit_time
    editMode => "formedit" | "onpageedit"

cms_edit_contentSaved
    editMode => "formedit" | "onpageedit"

Comparing "editMode" with identical values from two different edit events makes sense.

Do

cms_create_page
    type => "My Special Page"

Adding user input into a property is totally fine.

Don't

cms_edit
    commandType => "time" | "contentSaved"
    editMode => "formedit" | "onpageedit"

The "commandType" values "time" (minutes) and "contentSaved" (nr of edits) doesn't make sense to compare.

Don't

cms_page_createSpecialFoobar

The action "createSpecialFoobar" is too specific and the page type should be a property instead.