`js
import { trackCustomEvent } from '@convivainc/conviva-js-appanalytics';

let customData = {
identifier1: 'test',
identifier2: 1,
identifier3: true,
};

trackCustomEvent({
name: 'Custom Event Name',
data: customData,
});
`



`js
import { setCustomTags } from '@convivainc/conviva-js-appanalytics';

let customTagsData = { tagKey1: 'tagValue1', tagKey2: 1, tagKey3: true };
setCustomTags(customTagsData);
`

Clear previously set custom tags:

`js
import { unsetCustomTags } from '@convivainc/conviva-js-appanalytics';

// Remove custom tags tagKey2 & tagKey3
let customTagsData = ['tagKey2', 'tagKey3'];
unsetCustomTags(customTagsData);
`



`js
import { trackError } from '@convivainc/conviva-js-appanalytics';

try {
//...
} catch (error) {
trackError({
message: 'Cannot get user object',
filename: 'shop.js',
error: error, // Passing the caught error object.
});
}
`

- getClientId() – Retrieves the current Client ID
- setClientId(clientId) – Sets a specific Client ID

Retrieve the Client ID

`js
import {
convivaAppTracker,
getClientId,
} from '@convivainc/conviva-js-appanalytics';

convivaAppTracker({
appId: 'YOUR_APP_NAME_AS_STRING',
convivaCustomerKey: 'CONVIVA_ACCOUNT_CUSTOMER_KEY',
appVersion: '1.1.0',
});

// Always call getClientId() after initializing convivaAppTracker()
clientId = getClientId();
`

Set the Client ID

`js
import {
convivaAppTracker,
getClientId,
} from '@convivainc/conviva-js-appanalytics';

// Always call setClientId() before initializing convivaAppTracker() to set a specific clientId
setClientId(clientId);

convivaAppTracker({
appId: 'YOUR_APP_NAME_AS_STRING',
convivaCustomerKey: 'CONVIVA_ACCOUNT_CUSTOMER_KEY',
appVersion: '1.1.0',
});
`

Auto sync Client ID using cookie

Syncs clientId within subdomains by storing it in cookie with key name Conviva_sdkConfig.

Configure sharing clientId using cookie

To share clientId using cookie, you need to set the enableClIdInCookies configuration as true during SDK initialization.

`js
import {
convivaAppTracker,
} from '@convivainc/conviva-js-appanalytics';

convivaAppTracker({
appId: 'YOUR_APP_NAME_AS_STRING',
convivaCustomerKey: 'CONVIVA_ACCOUNT_CUSTOMER_KEY',
appVersion: '1.1.0',
configs: {
enableClIdInCookies: true
},
});
`

This feature enables tracking of meta tags from the section of an HTML page based on the provided configuration.

Example meta tags in an HTML Page:

`js














`

Configure Meta Tags Tracking

To collect meta tag data, you need to define the metaTagsTracking configuration during SDK initialization.

Example Configuration:

`js
convivaAppTracker({
appId: 'YOUR_APP_NAME_AS_STRING',
convivaCustomerKey: 'CONVIVA_ACCOUNT_CUSTOMER_KEY',
appVersion: '1.1.0',
configs: {
metaTagsTracking: {
tags: [
{
key: 'name', // Target meta tags with "name" attributes
value: 'content', // Extract their "content" values
},
{
key: 'property', // Target meta tags with "property" attributes
value: 'content', // Extract their "content" values
condition: ['title', 'locale'], // Optional: Filter by specific property values
},
],
},
},
});
`

`bash
npm install @convivainc/conviva-js-replay
`

#### Simple Usage (Recommended)

`typescript
import { init } from '@convivainc/conviva-js-replay';

// Just provide your customer key - that's it!
init('CONVIVA_ACCOUNT_CUSTOMER_KEY');
//ADD THIS BEFORE APP TRACKER INITIALISATION
`

#### Important configurations

##### Content Security Policy (CSP): allow Web Workers (Blob)
Some environments enforce a strict Content Security Policy (CSP). The SDK uses a Web Worker created from a blob: URL, which requires explicitly allowing workers.
Add the following directive to your site’s Content-Security-Policy:
`typescript
Content-Security-Policy: worker-src 'self' blob:;
`
Notes
1. If your policy already includes worker-src, extend it to include blob:.
2. If worker-src is not defined, browsers may fall back to script-src, which can prevent worker creation.

##### CORS: allow loading required external assets (CSS/SVG)
On many websites, required assets (commonly CSS files or SVGs) may be hosted on a different origin (domain/subdomain). If those assets are blocked by cross-origin restrictions, configure the hosting server/CDN to allow cross-origin access.
Ensure the asset server returns appropriate CORS response headers, such as:
`typescript
Access-Control-Allow-Origin: https://pulse.conviva.com
// If the host changes or a new host is introduced in the future, it should be allowed as well.
`
Or, if your security policy allows it:
`typescript
Access-Control-Allow-Origin: *
`


deviceMetadata is an object containing key-value pairs for predefined values, such as DeviceType and DeviceCategory, as well as additional properties like DeviceBrand, DeviceManufacturer, and DeviceModel.

Conviva automatically collects deviceMetadata for Web apps and mobile browsers. However, for devices like set-top boxes, smart TVs, gaming consoles, and others, you will need to manually set the deviceMetadata.

Example of setting deviceMetadata:

`js
import {
convivaAppTracker,
ConvivaDeviceMetadata,
} from '@convivainc/conviva-js-appanalytics';

const deviceMetadata: ConvivaDeviceMetadata = {
DeviceBrand: 'Samsung',
DeviceManufacturer: 'Samsung',
DeviceModel: 'UTU7000',
DeviceType: 'SmartTV',
OperatingSystemName: 'Tizen',
OperatingSystemVersion: '8.0',
DeviceCategory: 'SAMSUNGTV',
FrameworkName: 'Angular',
FrameworkVersion: '8.0.0',
};

convivaAppTracker({
appId: 'YOUR_APP_NAME_AS_STRING',
convivaCustomerKey: 'CONVIVA_ACCOUNT_CUSTOMER_KEY',
appVersion: '1.1.0',
deviceMetadata: deviceMetadata,
});
`

`js
import { trackNetworkRequest } from '@convivainc/conviva-js-appanalytics'

const requestDetails = {
url: url, // url
method: method, // 'GET', 'POST', etc.
headers: requestHeaders, // e.g., { 'Content-Type': 'application/json' }
body: requestBody, // e.g., JSON.stringify({ key: 'value' })
requestTime: performance?.now() ?? Date.now(),
size: requestBodySize //size of the request body
};

// Make Actual network request
// consider res has the actual network request response details

const responseDetails = {
status: res.status, // e.g., 200, 404
statusText: res.statusText, // e.g., 'OK', 'Not Found'
responseTime: performance?.now() ?? Date.now(),
body: await res.clone().json(), // parsed JSON response
headers: Object.fromEntries(res.headers.entries()), // response headers
};

trackNetworkRequest({ requestDetails, responseDetails });

`



| Event | Occurrence |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| network_request | After receiving the network request response. Refer limitations. |
| application_error | When an error occurrs in the application. |
| button_click | On the button click callback. Refer limitations. |
| link_click | On the link click callback. Refer limitations. |
| application_background | When visibility state change to hidden. |
| application_foreground | When visibility state change to visible. |
| Largest Contentful Paint | Timing information about the largest image or text paint before user input on a web page. |
| First App Launch | First time launch in the browser. Custom Tag Context. |
| page_loaded | On "load" event listener.Used to compute Page Loads, Avg Document Load Time, Avg DNS Lookup Time, Avg Document Response Time metrics. |
| Server-Sent Events | Supports Server-Sent Event (SSE) via Fetch eventstream. |
| WebSocket message stream | When WebSocket events occur (open, close, send, receive, error) for real-time communication tracking. |
| Event source message stream | When Event source events occur (open, send, receive, error) for real-time communication tracking. |
| Core Web Vitals(LCP, INP, CLS) | On visibilitychange / first user interaction. Refer web-vitals |

To learn about the default metrics for analyzing the native and web applications performance, such as App Crashes, Avg Screen Load Time, and Page Loads, refer to the App Experience Metrics page in the Learning Center.

The collection of all types of clicks is automatically supported, including those from standard HTML elements as well as elements created using React, Angular, and Vue frameworks. We also offer an experimental remote configuration specifically for click events, aiming to dynamically add support for non-standard or unsupported frameworks. For further assistance, please contact the Conviva support team.
Note: preventDefault and stopPropagation will prevent the auto-collection of button and link click events.

Migration of Pulse dimensions for clicks

Starting with version v1.1.2 of the SDK, the attribute keys for click events have been updated.
If you are using v1.1.1 or earlier and currently mapping elementText, you must update your configuration when upgrading to v1.1.2 or later. Specifically, update the mapping in DPI Activation by mapping elementText to text, then redeploy to apply the changes.

To ensure metrics reflect the updates, please review and update your event/metric mappings in DPI Activation if you are using any of the following attributes:
| <=v1.1.1 | >=v1.1.2 |
|--------------------------------|--------------------------------|
| elementType | elementType |
| elementText | text |
| elementName | elementName |
| elementValue | value |
| elementId | id |
| elementClasses | class |

This feature supports tracking network requests triggered within the application using XMLHttpRequest and the Fetch API.

Request and Response Body Collection:

Collected only when:
- Size is < Size limit
- Default Size Limit is 10 KB.
- Configurable via Remote configuration.
- Response body is type JSON.
- Content-type contains "json" or equals any of "text/plain", "text/javascript", "application/javascript", "text/html"
- Response Type is not "opaque"

Request and Response Header Collection:

Collected only when:

- The server is provisioned with "Access-Control-Expose-Headers:"`.
- Response Type is not "opaque"