Installing Yofi Telemetry Web SDK

Prerequisites:

Please contact Yofi team to get your own tokens:

1. NPM access token: Used for installing npm packages
2. Telemetry public token: Used for using the telemetry SDK

Install

1. Setup your .npmrc .

.npmrc sample:

@yofi-ai:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=YOUR-NPM-ACCESS-TOKEN-HERE

2. Install the package via npm cli

npm install @yofi-ai/telemetry-web-sdk@TARGET_VESION

or install via package.json

"@yofi-ai/telemetry-web-sdk": "TARGET_VESION"

Quick Start:

import { YofiTelemetry, LogLevel, AvailableSensors} from '@yofi-ai/telemetry-web-sdk'

const publicToken = 'YOUR-PUBLIC-TOKEN';

YofiTelemetry.initialize({
    publicToken: publicToken, 
    // journeyIdSalt used to generate journey id. If you have different websites, you can use different Salts.
    journeyIdSalt: 'yofiscakes.myshopify.com'
});

// Initial labels if any
const initLabels = {
    'some-label': 'some-value'
};

const session = YofiTelemetry.startSession({
    duration: 900 * 1000, // 15mins
    labels: initLabels,   // Optional
    networkTelemetryConfig: {
        ip: true
    }
});

To terminate all existing sessions and initiate a new one, set the stopAllSessions parameter of startSession to true .

const session = YofiTelemetry.startSession(yourSessionConfig, true);

Starting a New Journey:

To start a new journey, follow the steps below. You can set labels and other configuration options via yourSessionConfig .

Note: Before calling startNewJourney , make sure you have already called YofiTelemetry.initialize .

const session = await YofiTelemetry.startNewJourney(yourSessionConfig);

Session Labels:

You can add labels to a session, the value of each label must be string.

const existingLabels = session.getLabels();

const newLabels = {
    'new-label': 'new-value'
};
// Note: Starting from v0.0.41, addLabels returns a Promise object.
// If an exception occurs, it will throw an Error object.
await session.addLabels(newLabels);

You can wait for the result of addLabels using the following approaches.

// Async/await approach
async function asyncApproach(newLabels) {
    try {
        await session.addLabels(newLabels);
        // Label addition completed successfully
    } catch(error) {
        // Handle error thrown during label addition
    }
}

// Promise approach
function promiseApproach(newLabels) {
    session.addLabels(newLabels)
    .then(() => {
        // Label addition success
    })
    .catch((error) => {
        // Handle error from label addition
    });
}

Advanced Configuration:

1. Configure Sensors

To specify which sensors should cease data collection, utilize the sensorTypes parameter.

import { YofiTelemetry, AvailableSensors} from '@yofi-ai/telemetry-web-sdk'

// Default sensors
const webBrowserSensors = [
    AvailableSensors.FOCUS_CHANGE,
    AvailableSensors.KEY_PRESS,
    AvailableSensors.CLICK,
    AvailableSensors.MOUSE_WHEEL,
    AvailableSensors.POINTER,
    AvailableSensors.VIEW_SCROLL,
    AvailableSensors.INPUT_CHANGE,
    AvailableSensors.FORM_SUBMIT,
    AvailableSensors.CLIPBOARD,
    AvailableSensors.BOTD,
    AvailableSensors.SELECTION,
]

YofiTelemetry.startSession({
    /* Other settings */
    sensorTypes: webBrowserSensors,
});

2. Setup SDK Callbacks

Allows the YofiTelemetry SDK to report events back to the calling application.

import { YofiTelemetry, YofiTelemetryCallback } from '@yofi-ai/telemetry-web-sdk';

const sessionCallbacks: YofiTelemetryCallback = {
    onSessionStarted: (session) => {
        // Your logic here
        // session is session instance
        // You will need this object to add new labels and events
    },
    onSessionStopped: (session) => {
        // Your logic here
    },
    onSessionError: (msg) => {
        // Your logic here
    },
    onJourneyIdCreated(journeyId) {
        // Your logic here
    },
}

YofiTelemetry.initialize({
    yofiTelemetryCallback: sessionCallbacks,
    // other SDK configs
});

3. How to Get Journey Id

There are 2 ways to get journey Id, the simplest way is get it after SDK initialization.

// Get journey id after initialization
const journeyId = YofiTelemetry.getJourneyId() 

The other way is get it via onJourneyIdCreated callback above.

4. How to report page url to Telemetry

To capture the page URL in JavaScript and report it to Telemetry, follow these steps:

Use the window.location.href property to access the full URL of the current page. This property returns the entire URL including the protocol, host, and path. Note that this is just an example; depending on your needs, you might only need part of the URL.

const page_url = window.location.href;

You can include the URL in the session initialization by adding it to the initLabels within the Quick Start section, or refer to the Session Labels section to learn how to use the addLabels method.

Notes

1. What is .npmrc
2. Default bundleGenerationInterval is 2s
3. client_id , journey_id and __page_url are labels reserved by the SDK, please do not use them.