People tracking SDK in Live Chat

The People tracking SDK integrates People web SDK (opens in a new tab) functionality into Live Chat. It enables you to build unified person profiles by tracking user activity on websites with Live Chat and maintaining the same profile during Live Chat sessions.

By using this SDK, you gain deeper insights into your customers and better understand their needs.

Key terms

Throughout this documentation, the following terms are used:

• Live Chat page: A website where Live Chat is integrated.
• Live Chat user: A user who visits a Live Chat page.
• Visitor: An anonymous visitor of a Live Chat page who has not started a chat or authenticated.
• Person: A lead or authenticated user who has started a chat or is authenticated. For more details about authentication, see Users and authentication.
• User activity: Any event tracked for a user, which is saved and listed in their profile.
• Person profile: A profile created for a person, which can be viewed.
• Visitor profile: A profile created for a visitor. It cannot be viewed until the visitor becomes a person.

People tracking SDK capabilities

The People tracking SDK allows you to:

• Track person activity events such as Session started, Session ended, or Page view.
• Track custom events that you define.
• Update a person's properties and attributes.

Session started is triggered when the first user activity is recorded (such as a page view or a custom event). A session expires 30 minutes after the last recorded user activity, at which point a Session ended event is triggered. A new session starts with the next recorded user activity.

The Page view event is triggered when the SDK initializes as the user opens a Live Chat page. For more details, see People events.

Profile selection

The profile used for tracking user activity is determined based on the Live Chat session. A Live Chat session is established when a user starts a chat or authenticates.

The following table summarizes which profile is selected in various situations:

Visitor lifecycle

When a user visits a Live Chat page for the first time, a new visitor profile is created. This profile remains active for 45 days after the last visitor activity. The profile is reused whenever the visitor returns to the page, until they start a chat or authenticate.

If no activity occurs within 45 days, the visitor profile is deleted. A new profile is created upon the next tracked activity.

People tracking SDK usage

To begin, create an instance of the SDK (obtain SDK object) that provides access to all SDK functions:

const sdk = new PeopleTrackingSDK();

Provided functions

The SDK includes the following functions for building and maintaining Live Chat user profiles.

init()

Example

sdk.init('725f7...55b9');

After initialization, a visitor profile is created for new Live Chat users (if none exists), and a page view event is tracked. If there is an existing Live Chat session, the corresponding person profile is selected automatically for activity tracking.

track()

Example

pe.track('action', { name: 'Button clicked', label: 'add-to-favorites' });

updatePerson()

Example

sdk.updatePerson({ 
  address: 'Kirchmayer street 97', 
  birthDate: '1993-01-01',
  city: 'Prague',
  contactInformation: {
    email: [{ address: '[email protected]' }],
    phone: [{ number: '421905123450' }]
  },
  country: 'Czech Republic',
  customAttributes: { car: 'Mercedes' },
  externalId: 'number123456',
  firstName: 'Semi',
  gender: 'male',
  integrations: { salesforce: { contactId: '123', leadId: '456' }},
  lastName: 'Holsen',
  middleName: 'Gabcik',
  preferredLanguage: 'it-it',
  profilePicture: 'https://profile.com',
  tags: ['reading', 'technology']
});

appendToList()

Example

pe.appendToList('category', { name: 'special' });

Responses

Each function returns a Promise that resolves to an object. The key property is success, which indicates the outcome of the operation. If success is false, additional details are provided in the error property.

Successful resolved Promise example

{
  "success": true,
  "data": null
}

Failed resolved Promise example

{
  "success": false,
  "error": {
    "code": 2015,
    "name": "NotInitializedPeopleTrackingError",
    "message": "People tracking SDK is not initialized. Call init() first",
    "origin": "fe-snippet",
    "platform": "fe-snippet"
  }
}

Error properties

The origin property specifies where the error originated within the system, while the platform property indicates where the error surfaced or was reported.

To help you interpret errors, the most important properties are code, name, and especially message, which provides detailed information about the error’s cause.

Common SDK errors

The following table lists errors you may encounter while using the SDK: