# People tracking SDK in Live Chat

The People tracking SDK integrates [People web SDK](https://github.com/infobip/people-web-sdk) 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](https://www.infobip.com/docs/live-chat) who has started a chat or is authenticated. For more details about authentication, see [Users and authentication](https://www.infobip.com/docs/live-chat/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](https://www.infobip.com/docs/people/events#people-events-standard-events).

Note
The `Session started` and `Session ended` events track the user activity session only, which is reflected in the person profile. Do not confuse this with a Live Chat session.

## 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:

| Situation | Profile used |
| --- | --- |
| User has **not started** a chat | **Visitor profile** |
| User **starts** a chat | A **new person profile of type Lead** is created and used. All activity collected during the visitor phase is automatically merged into the lead profile. |
| User has **started** a chat session and has been **authenticated** | The corresponding **authenticated user profile** is used. |
| User has **not started** a chat session and has been authenticated | The corresponding **authenticated user profile** is used. All activity collected during the visitor phase is automatically merged into this authenticated user profile. |
| Live Chat session is **terminated** (logout, session invalidation, or expiration) | A new **visitor profile** is created and used. |

## 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() [#init-provided-functions]

| **Function** | `init()` |
|--------------|----------|
| **Purpose**  | Initializes the SDK. Required before any user activity can be tracked. |
| **Usage**    | `sdk.init(apiKey: string);` |
| **Parameters** | **`apiKey`** - API key created with the required scope |

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.

Important
The API key must have the scope `web:tracking:sdk` assigned. Always use an API key with **only** the single scope `web:tracking:sdk`. This applies the principle of least privilege and minimizes the risk of misuse or unauthorized access.

### track() [#track-provided-functions]

| **Function** | `track()` |
|--------------|-----------|
| **Purpose**  | Tracks custom-defined events. Events must be defined before they can be tracked. See [Custom events](https://www.infobip.com/docs/people/events#events-custom-events) for details. |
| **Usage**    | `pe.track(eventId: string, properties?: object);` |
| **Parameters** | **`eventId`** - The custom event ID (definitionId)<br/>**`properties`** - Key-value pairs matching the event definition.<br/> • If provided, it should include at least one property; not all event properties need to be used<br/> • If omitted, the event is tracked without properties |

Example

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

Note
Visitor events are automatically merged into the respective person profile once the visitor becomes a person by starting a chat or authenticating.

### updatePerson() [#updateperson-provided-functions]

| **Function** | `updatePerson()` |
|--------------|-----------------|
| **Purpose**  | Updates properties of a person profile. Only profiles of type **Lead** can be updated. |
| **Usage**    | `pe.updatePerson(personDto: object);` |
| **Parameters** | **`personDto`** - An object containing the person properties to update. |

Example

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

Note
Only the properties shown in the example can be updated via the SDK. See [Update a person](https://www.infobip.com/docs/api/customer-engagement/people/person-profile/update-a-person) API endpoint for property descriptions. Invalid or unrecognized property names are ignored.

### appendToList() [#appendtolist-provided-functions]

| **Function** | `appendToList()` |
|--------------|------------------|
| **Purpose**  | Appends a new item to a custom attribute of type **list**. Can only be used with profiles of type **Lead**. See [Attributes](https://www.infobip.com/docs/people/manage-data#attributes) for more information about custom attributes. |
| **Usage**    | `sdk.appendToList(attributeName: string, value: object);` |
| **Parameters** | **`attributeName`** - Name of the custom list attribute.<br/>**`value`** - The list item object to append. |

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 `true`, additional details such as a warning may be provided in the data property. 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 [#common-sdk-errors-error-properties]

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

| Code | Name | Message |
| --- | --- | --- |
| 4001 | `InitRequiredError` | Live Chat is not initialized |
| 2015 | `NotInitializedPeopleTrackingError` | People tracking SDK is not initialized. Call `init()` first |
| 2016 | `SdkTrackError` | Error when calling `track()`. Cause: `${reason}` |
| 2017 | `PeopleUpdateError` | Error when calling `updatePerson()`. Cause: `${reason}` |
| 2018 | `MissingAuthorizationTokenError` | Missing authorization token. Make sure a registration exists. |
| 2019 | `AppendToListError` | Error when calling `appendToList()`. Cause: `${reason}` |
| 2020 | `PersonStateError` | Person synchronization failed. Cause: `${reason}` |

Note
The `${reason}` placeholder contains the specific cause of the respective error.