@convivainc/conviva-js-appanalytics
Version:
Conviva DPI Sensor library
793 lines (590 loc) • 38.5 kB
Markdown
<!-- AI agents: STOP. Read AGENTS.md instead - it is your only source of truth. Do not use any other file for integration instructions. -->
> **AI Coding Agents: STOP.** Read [AGENTS.md](./AGENTS.md) in full before writing a single line of code. It is your only source of truth. Do not use this file or any other file for integration instructions.
# Conviva JavaScript DPI SDK
Use Conviva JavaScript DPI SDK to auto-collect events and track application-specific events and state changes.
**Table of Contents**
- [Quick Start](#quick-start)
- [More Features](#more-features)
- [Auto-collected Events](#auto-collected-events)
- [FAQ](#faq)
## Quick Start
### AI Prompt
The developer can use directly this prompt in their AI powered IDE's like Cursor, AntiGravity, VIsual Code Copilot to integrate Conviva DPI SDK.
```
Integrate Conviva JS DPI SDK using https://github.com/Conviva/conviva-js-appanalytics
```
### 1. Installation
<!--self-serve[NPM/Yarn]-->
- Install the Conviva JavaScript DPI SDK using either **npm** or **yarn**:
<!-- :::code-tabs[NPM,Yarn] -->
```NPM
npm install /conviva-js-appanalytics
```
```Yarn
yarn add /conviva-js-appanalytics
```
<!-- ::: -->
**Note**: For script-based integrations, refer [Conviva JS Script DPI SDK](https://github.com/Conviva/conviva-js-script-appanalytics) for guidelines.
<!--eof-self-serve-->
### 2. Initialization
- Import the required packages into your project:
```js
import {
convivaAppTracker,
setUserId,
trackPageView,
} from '/conviva-js-appanalytics';
```
- Initialize the Conviva JavaScript DPI SDK:
**Note**: It is recommended to initialize the tracker as early **as possible** during the DOM load sequence, such as in `App.js`.
```js
convivaAppTracker({
appId: 'YOUR_APP_NAME',
convivaCustomerKey: 'YOUR_CUSTOMER_KEY',
appVersion: '1.1.0',
});
```
**YOUR_APP_NAME** - A string value that uniquely identifies your app across platforms. For example: `"WEB App"`, `"LGTV App"`.
**YOUR_CUSTOMER_KEY** - A string to identify a specific customer account. Use different keys for dev and prod. Find them in [Pulse](https://pulse.conviva.com/app/profile/applications) under My Profile (_Conviva login required_).
**appVersion** - Set app version in string format.
**Important configurations**
```typescript
Content-Security-Policy: connect-src 'self' https://rc.conviva.com/ http://appgw.conviva.com/ https://rcg.conviva.com/;
```
#### Calling APIs before initialization
API calls made before `convivaAppTracker()` is initialized (e.g., `trackCustomEvent`, `trackRevenueEvent`, `setUserId`) are automatically queued and replayed once the tracker is initialized. This allows you to instrument your app without waiting for the tracker to be ready.
```js
import {
convivaAppTracker,
setUserId,
trackCustomEvent,
} from '/conviva-js-appanalytics';
// Safe to call before convivaAppTracker() — will be replayed after init
setUserId('user-123');
trackCustomEvent({ name: 'app_start', data: {} });
// Initialize later
convivaAppTracker({
appId: 'YOUR_APP_NAME',
convivaCustomerKey: 'YOUR_CUSTOMER_KEY',
appVersion: '1.1.0',
});
```
**Note:** `getClientId` and `setClientId` are not queued — they execute independently of tracker initialization.
### 3. Cross Sub-domain Session Management
Conviva stores the Client ID in a first-party cookie scoped to the parent domain. Any subdomain that runs the sensor reads the same cookie and reuses the existing Client ID — no application code required.
**Auto sync Client ID using cookie**
Syncs clientId within subdomains by storing it in cookie with key name `Conviva_sdkConfig`.
**Native + WebView combined session (no JS code required):** For hybrid apps that embed Conviva-instrumented web pages in a native WebView, the SDK can share a single Conviva clientId between the native app and the WebView so events from both sides land in one combined Conviva session.
The recommended production flow is **native sets the cookie**:
1. The native app (Android / iOS) sets the `Conviva_sdkConfig` cookie carrying its current Conviva clientId on the WebView's cookie store, scoped to the WebView page's parent domain, before the WebView loads the page.
2. The JS SDK reads the cookie on initialization and reuses that clientId — no JS configuration change required.
If the cookie cannot be set in time, the SDK auto-detects a native bridge object on `window` as a fallback:
- **Android WebView** — expose `window.__ConvivaNativeWebInterface.getClientId(): string` (synchronous).
- **iOS WKWebView** — expose `window.webkit.messageHandlers.__ConvivaiOSGetClientIdInterface` so the SDK can call `postMessage(null)` and receive a `Promise<string>` reply (`WKScriptMessageHandlerWithReply`, iOS 14+).
When a bridge supplies a clientId that differs from the cached one, the SDK fires a `ConvivaClientIdChanged` CustomEvent on `window` so other in-tab consumers (e.g. session replay) can refresh their state. The `getClientId()` / `setClientId()` APIs below remain available for the multi-instance / cross-origin synchronization scenarios where no bridge is exposed.
**Other Use Cases (Hybrid apps)**:
When using multiple Conviva JavaScript DPI SDK instances across different environments (e.g., mobile apps embedding webviews), the Client ID may not be shared automatically. To ensure consistency, the SDK provides the following advanced APIs for manual synchronization. These APIs are intended for developers who require fine-grained control over Client ID management across multiple instances.
Eg: Synchronizing Client ID between a mobile app and WebView.
- `getClientId()` – Retrieves the current Client ID
- `setClientId(clientId)` – Sets a specific Client ID
**Retrieve the Client ID**
```js
import {
convivaAppTracker,
getClientId,
} from '/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 '/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',
});
```
***Disable sharing clientId using cookie***
To disable sharing clientId using cookie, you need to set the `enableClIdInCookies` configuration as false during SDK initialization.
```js
import {
convivaAppTracker,
} from '/conviva-js-appanalytics';
convivaAppTracker({
appId: 'YOUR_APP_NAME_AS_STRING',
convivaCustomerKey: 'CONVIVA_ACCOUNT_CUSTOMER_KEY',
appVersion: '1.1.0',
configs: {
enableClIdInCookies: false
},
});
```
**Note**: The Conviva JavaScript DPI SDK utilizes **local storage** to cache some data.
### 4. Set the User ID
User ID is a unique string identifier to distinguish individual viewers. If using [Conviva Video Sensor](https://github.com/Conviva/conviva-js-coresdk), match it with the **Viewer ID**.
Note: Set the User ID as soon as Conviva sensor is initialized so that none of the events are missed from User's timeline.
```js
setUserId('replace_me_by_the_userId');
```
### 5. Report Page View
trackPageView() should be called after the page is considered "loaded" by your application—that is, when content is rendered and ready for user interaction. Avoid calling it too early (e.g., before the main content or layout is visible), as this may result in incomplete timing data.
What defines a "page change"?
This depends on your app type:
For MPAs: Every full page reload is a new page.
For SPAs: A new page is usually identified by URL path or route changes.
Developers should trigger pageview() based on what they define as a meaningful navigation or view transition in their application.
By default, when `trackPageView()` is called, the _Page Title_ is set using `document.title`. However, you can override this by passing a custom title in the `trackPageView()` API:
```js
// Uses document.title as the Page Title
trackPageView();
// Pass a custom Page Title
trackPageView({ title: 'Custom Page Title' });
```
**Note**: The Web (JS/React) SDK does not collect page views if the trackPageView() API is not explicitly called during a navigation event. As a result, corresponding metrics (such as Page Views, Avg Perceived Page Load Time, Avg Largest Contentful Paint Time) will be missing from the Pulse dashboard. Conviva does not support auto-collection of missing page views.
## More Features
<details>
<!--self-serve-custom-event-->
<summary><b>Track Custom Event</b></summary>
Use the **trackCustomEvent()** API to track all kinds of events. This API provides 2 fields to describe the tracked events:
**name** - Name of the custom event
**data** - Any type of data in JSON format.
```js
import { trackCustomEvent } from '/conviva-js-appanalytics';
let customData = {
identifier1: 'test',
identifier2: 1,
identifier3: true,
};
trackCustomEvent({
name: 'Custom Event Name',
data: customData,
});
```
<!--eof-self-serve-custom-event-->
</details>
<details>
<!--self-serve-custom-event-->
<summary><b>Set Custom Tags</b></summary>
Custom Tags are global tags applied to all events and persist throughout the application lifespan, or until they are removed.
**Set the custom tags:**
```js
import { setCustomTags } from '/conviva-js-appanalytics';
let customTagsData = { tagKey1: 'tagValue1', tagKey2: 1, tagKey3: true };
setCustomTags(customTagsData);
```
**Clear previously set custom tags:**
```js
import { unsetCustomTags } from '/conviva-js-appanalytics';
// Remove custom tags tagKey2 & tagKey3
let customTagsData = ['tagKey2', 'tagKey3'];
unsetCustomTags(customTagsData);
```
<!--eof-self-serve-custom-event-->
</details>
<details>
<summary><b>Error Reporting</b></summary>
Uncaught exceptions and unhandled rejections are automatically collected and enabled by default. To report caught exceptions or other errors, use the following API:
```js
import { trackError } from '/conviva-js-appanalytics';
try {
//...
} catch (error) {
trackError({
message: 'Cannot get user object',
filename: 'shop.js',
error: error, // Passing the caught error object.
});
}
```
</details>
<details>
<summary><b>Meta Tags Collection </b></summary>
This feature enables tracking of meta tags from the `<head>` section of an HTML page based on the provided configuration.
Example meta tags in an HTML Page:
```js
<html>
<head>
<meta name="keywords" content="HTML, CSS, JavaScript">
<meta name="description" content="Free Web tutorials for HTML and CSS">
<meta name="author" content="John Doe">
<meta http-equiv="refresh" content="30">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta property="site_name" content="goole.com">
<meta property="title" content="Sample app">
<meta property="description" content="TV series content">
<meta property="locale" content="es_ES">
<meta property="type" content="video">
</head>
</html>
```
**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
},
],
},
},
});
```
</details>
<details>
<summary><b>Replay</b></summary>
From release 1.5.2 onwards to avail the replay feature follow the below instruction
> **Compatibility:** Cohort Replay **v1.0.4 or later** is required when using DPI SDK v2.2.0 or later ([release notes](https://github.com/Conviva/conviva-js-replay/releases/tag/v1.0.4)). Earlier replay versions are not compatible with DPI v2.2.0+ for session synchronization.
#### NPM
```bash
npm install /conviva-js-replay
```
#### Simple Usage (Recommended)
```typescript
import { init } from '/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.
##### For replay support till version 1.5.1 please add below CSP configuration.
```typescript
Content-Security-Policy: script-src 'self' cdnjs.cloudflare.com;
```
##### 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: *
```
</details>
<details>
<summary><b>Set Device Metadata</b></summary>
`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 '/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,
});
```
<details>
<summary><b>The table of predefined metadata keys for deviceMetadata</b></summary>
| **Key** | **Type** | **Description** | **Example Values** |
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| DeviceBrand | string | Brand of the device | `"Comcast"`, `"LG"`, `"Google"`, `"Vizio"` |
| DeviceManufacturer | string | Manufacturer of the device | `"Sony"`, `"Comcast"`, `"Google"`, `"Microsoft"` |
| DeviceModel | string | Model of the device | `"Comcast Flex"`, `"UTU7000_KA"`, `"Xbox One"` |
| DeviceType | Prescribed values of DeviceType | Type of the device. Only allows the DeviceType values and discards any other string values | DESKTOP, Console, Mobile (see [table below](#devicecategory-pre-defined-string-values)) |
| DeviceVersion | string | Device firmware version | `"10"`, `"9"` |
| OperatingSystemName | string | Name of the operating system used by the device, in uppercase | `"Tizen"`, `"webOS"`, `"Vizio`", `"Linux`", `"Xbox OS"`, `"Chrome OS"` |
| OperatingSystemVersion | string | Version of the operating system used by the device | `"10.10.1"`, `"8.1"`, `"T-INFOLINK2012-1012"`, `"1.56.500000"` |
| DeviceCategory | Prescribed values of DeviceCategory | Device category to which the used device belongs. Only allows DeviceCategory values and discards any other string values | WEB, AND, PS (see [table below](#devicetype-pre-defined-string-values)) |
| FrameworkName | string | Application framework name | `"React TV"`, `"LightningJS"`, `"Angular"` |
| FrameworkVersion | string | Application framework version | `"1.2.3"` | |
#### DeviceCategory Pre-defined String Values:
| Value | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AND | The device is an Android device like Samsung Galaxy, Amazon Fire TV, Android TV, or Android Tablet. |
| APL | The device is an Apple device like iPhone or Apple TV. |
| CHR | The device is a Google Chromecast STB or Android TV with built-in Chromecast. |
| DSKAPP | The device is a desktop computer (including notebooks) where video is played in an installed app, as opposed to a browser. |
| SIMULATOR | The device is a simulated video session used for testing. |
| KAIOS | The device is a phone or other device based on KaiOS OS, such as the Lyf Jio F30C. |
| LGTV | The device is an LG smart TV, including NetCast and webOS. |
| LNX | This mostly covers various Set-Top Boxes and Smart TVs that use custom Linux-based SDKs. |
| NINTENDO | The device is a Nintendo games console, including Wii and Switch. |
| PS | The device is a PlayStation console, including PS3 and PS4. |
| RK | The device is a Roku device. |
| SAMSUNGTV | The device is a Samsung Smart TV, including Orsay and Tizen. |
| VIDAA | Vidaa-based devices, using an operating system developed by Hisense. |
| VIZIOTV | Category for native app integrations on Vizio TVs using the SmartCast platform (from 2016 onwards). |
| WEB | The device can be any device with an in-browser HTML5-based player. Video is played in the browser using HTML5 technology, in browsers like Chrome, Edge, Firefox, Internet Explorer, Opera, or Safari. |
| WIN | The device is a Windows OS-based handheld device, like a Windows Phone or Windows Tablet. |
| XB | The device is an Xbox console, including Xbox 360 and Xbox One. |
#### DeviceType Pre-defined String Values:
| Value | Description |
| ------- | -------------------------------------------- |
| DESKTOP | The device is a desktop or laptop computer. |
| Console | The device is a gaming console. |
| Settop | The device is a set-top box. |
| Mobile | The device is a mobile phone. |
| Tablet | The device is a tablet. |
| SmartTV | The device is a smart TV. |
| Vehicle | The device is a vehicle infotainment system. |
| Other | Other device types. |
</details>
</details>
<details>
<!--self-serve-custom-event-->
<summary><b>Track Network Request Event</b></summary>
Use the **trackNetworkRequest()** API to track all kinds of network events. This API provides 2 Objects to describe the tracked events:
**requestDetails** - Information about the outgoing request.
**responseDetails** - Information about the response.
```js
import { trackNetworkRequest } from '/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 });
```
<!--eof-self-serve-custom-event-->
</details>
<details>
<!--self-serve-custom-event-->
<summary><b>Form Tracking</b></summary>
The SDK can automatically track form interactions on a page when this feature is enabled for your account via Conviva remote configuration.
**Manual form APIs**
Use the following manual APIs to report form lifecycle events that the SDK cannot infer from the DOM — typically server-side outcomes that occur after the network request completes, or custom client-side validation that does not use the browser's constraint validation API.
```js
import {
trackFormView,
trackFormSubmitSuccess,
trackFormSubmitError,
trackFormValidationError,
} from '/conviva-js-appanalytics';
// Reports that a form was rendered / became visible to the user.
trackFormView('signup-form');
// Reports that the form submission was accepted by the server.
trackFormSubmitSuccess('signup-form');
// Reports that the form submission failed (e.g. server-side rejection).
trackFormSubmitError('signup-form', 'email_already_registered');
// Reports a field-level validation error that the SDK cannot detect
// automatically (e.g. custom client-side validation logic).
trackFormValidationError('signup-form', 'email', 'invalid_format');
```
**API Reference**
| API | Arguments |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trackFormView(formId)` | `formId: string` — must match the form's `id` or `data-form-id` so manual and auto-collected events correlate. |
| `trackFormSubmitSuccess(formId)` | `formId: string`. |
| `trackFormSubmitError(formId, errorType)` | `formId: string`, `errorType: string` — short, stable, non-PII description of the failure (truncated to 256 chars). |
| `trackFormValidationError(formId, fieldName, errorType)` | `formId: string`, `fieldName: string`, `errorType: string` — stable, non-PII strings. The SDK redacts `fieldName` if it matches the configured denylist. |
**Notes:**
- Manual form APIs are no-ops when form tracking is disabled in remote configuration.
- Pass the same `formId` used by your DOM (`id` or `data-form-id`) so manual events correlate with the auto-collected `conviva_form_`* events.
- Do not include sensitive or personally identifiable values in `fieldName` or `errorType`.
<!--eof-self-serve-custom-event-->
</details>
<details>
<!--self-serve-custom-event-->
<summary><b>Track Revenue Event</b></summary>
Use `trackRevenueEvent()` to track purchase and revenue events. The event is sent as `conviva_revenue_event` and can be used for Business/Revenue Metrics in Pulse.
**Required Fields:**
| Field | Type | Description |
|---|---|---|
| `totalOrderAmount` | `number` | Total order amount (must be a finite number) |
| `transactionId` | `string` | Unique order/transaction identifier (non-empty string) |
| `currency` | `string` | Currency code e.g. `'USD'`, `'EUR'` (non-empty string) |
**Optional Fields:**
| Field | Type | Description |
|---|---|---|
| `taxAmount` | `number` | Tax amount |
| `shippingCost` | `number` | Shipping cost |
| `discount` | `number` | Discount / coupon value |
| `cartSize` | `number` | Count of items in the order |
| `paymentMethod` | `string` | e.g. `'card'`, `'ApplePay'`, `'payPal'` |
| `paymentProvider` | `string` | e.g. `'Stripe'`, `'Adyen'` |
| `orderStatus` | `string` | e.g. `'completed'`, `'pending'` |
| `items` | `RevenueEventItem[]` | Array of purchased line items |
| `extraMetadata` | `object` | Custom key/value pairs for fields not covered above |
**Notes:**
- If validation fails on required fields (e.g. missing `transactionId` or non-finite `totalOrderAmount`) or the event argument is not a plain object, the SDK logs a warning and skips the event without throwing.
- Optional fields with unexpected types are stripped with a warning; the event is still sent.
**Example — minimal:**
```js
import { trackRevenueEvent } from '/conviva-js-appanalytics';
trackRevenueEvent({
totalOrderAmount: 49.99,
transactionId: 'ORD-12345',
currency: 'USD',
});
```
**Example — full (TypeScript):**
```typescript
import {
trackRevenueEvent,
RevenueEvent,
RevenueEventItem,
} from '/conviva-js-appanalytics';
const items: RevenueEventItem[] = [
{ productId: 'p1', name: 'Widget', unitPrice: 19.99, quantity: 2 },
{ productId: 'p2', name: 'Gadget', unitPrice: 19.99, quantity: 1 },
];
const revenueEvent: RevenueEvent = {
totalOrderAmount: 59.97,
transactionId: 'ORD-12345',
currency: 'USD',
taxAmount: 5.00,
shippingCost: 4.99,
discount: 10.00,
cartSize: 3,
paymentMethod: 'card',
paymentProvider: 'Stripe',
orderStatus: 'completed',
items,
extraMetadata: { promoCode: 'SAVE10', campaignId: 'summer-sale' },
};
trackRevenueEvent(revenueEvent);
```
<!--eof-self-serve-custom-event-->
</details>
<details>
<summary><b>Tracker Cleanup</b></summary>
Use `cleanup()` to release all resources held by the tracker — removes event listeners, clears timers, and resets internal state. This is useful when you need to re-initialize the tracker (e.g., after user logout or SPA route teardown).
```js
import { cleanup } from '/conviva-js-appanalytics';
cleanup();
```
After calling `cleanup()`, you can re-initialize the tracker by calling `convivaAppTracker()` again.
**Note:** `cleanup()` is not supported on older browsers (Chrome < 66, Firefox < 57, Safari < 12.1).
</details>
## Auto-collected Events
Conviva automatically collects rich set of app performance metrics through app events after completing the [Quick Start](#quick-start).
<details>
<summary><b>Auto-collected events table</b></summary>
| Event | Occurrence |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| network_request | After receiving the network request response. [Refer limitations](#limitations). |
| application_error | When an error occurrs in the application. |
| button_click | On the button click callback. [Refer limitations](#limitations). |
| link_click | On the link click callback. [Refer limitations](#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) | At pagehide/visibilitychange. LCP: Chromium, Firefox. INP, CLS: Chromium. [Refer web-vitals](https://www.npmjs.com/package/web-vitals/v/5.1.0) |
| Supplementary Web Vitals (FCP, TTFB) | Early in page load, once after navigation. Chromium, Firefox, Safari. Enabled when both `webVitals.enabled: true` and `webVitals.enabledAdditionalMetrics: true` in remote config. |
| form_tracking | When form: start, field-blur, submit, validation(only Html5 Validation) events occur. Automatically collects form life cycle events. Enabled when `formcc.en: true`. See [Form Tracking](#more-features) for more details
| scroll_tracking | When the user crosses a configured scroll-depth threshold or when a viewport resize / orientation change resets milestone state this event get triggered. Automatically captures scroll milestones, scroll resets, and scroll depth. Reports viewport width, page height, page width, scroll position (scrollY), and related metrics.Disabled by default; can be enabled via remote configuration. |
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](https://pulse.conviva.com/learning-center/content/eco/eco_metrics.html) page in the Learning Center.
</details>
### Limitations
<details>
<summary><b>Clicks</b></summary>
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](https://github.com/Conviva/conviva-js-appanalytics/releases/tag/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](https://pulse.conviva.com/app/activation/home) 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](https://pulse.conviva.com/app/activation/home) 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 |
</details>
<details>
<summary><b>network_request</b></summary>
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"
</details>
<details>
<summary><b>Cleanup API browser support</b></summary>
The <code>cleanup()</code> API is not supported on older browsers (Chrome < 66, Firefox < 57, Safari < 12.1). See the <b>Tracker Cleanup</b> section above for usage details.
</details>
<details>
<summary><b>SSE, Websocket and Event source</summary>
Only supports json payload for SSE and Event source.
Supports json and Array Buffer for websocket.
</details>
<details>
<summary><b>Replay availability after tab close</summary>
If a user closes the browser tab after performing an activity, the last up to 1 minute of user activity per origin may not be available immediately.
This duration represents the maximum possible gap; in most cases, the unavailable replay segment will be less than 1 minute.
Replay data for that origin will resume only after the application is relaunched and the user returns to the same origin.
**Notes**
1. This limitation applies on a per-origin basis.
2. Once the user revisits the same origin, replay capture and availability continue as expected.
</details>
### Validation
After steps 1–4, verify [auto-collected events](#auto-collected-events) in the [validation dashboard](https://pulse.conviva.com/app/appmanager/ecoIntegration/validation) . (_Conviva login required_)
## FAQ
[DPI Integration FAQ](https://pulse.conviva.com/learning-center/content/sensor_developer_center/tools/eco_integration/eco_integration_faq.htm)