> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

# Insights plugin

> Track what entries and Experiences are being viewed to power Component Insights.

The Insights plugin sends data to an Insights API endpoint via the [Beacon API](https://developer.mozilla.org/en-US/docs/Web/API/Beacon_API) when an `<Experience>` component remains in the viewport for a specified amount of time. This view data powers Component Insights and Experience Insights.

Entries without a personalization or experiment can also be tracked this way if they are wrapped with the `<Experience>` component. This data can be analyzed on the [Content insights](https://www.contentful.com/help/analytics/content-insights/) page.

## Installation

> **Info**
>
> The Insights Plugin requires that you are using major version 6.x or above of one of the SDKs. Ensure that all of your other `@ninetailed` dependencies are also using the same version.

Add the dependency:

#### npm

```bash
npm install @ninetailed/experience.js-plugin-insights
```

#### yarn

```bash
yarn add @ninetailed/experience.js-plugin-insights
```

Then, add the plugin to the instance:

#### React, Next.js

```typescript
import { NinetailedInsightsPlugin } from '@ninetailed/experience.js-plugin-insights'
```

```typescript
<NinetailedProvider
  // ...
  plugins={[
    new NinetailedInsightsPlugin()
  ]}
  componentViewTrackingThreshold={2000} // (Optional prop) Number, default = 2000
>
  // ...
</NinetailedProvider>;
```

#### Gatsby

```javascript
plugins: [
    // ...
    {
        resolve: `@ninetailed/experience.js-plugin-gatsby`,
        options: {
            // ...
            componentViewTrackingThreshold: 2000 // (Optional prop) Number, default = 2000
            ninetailedPlugins: [
                // ...
                {
                    resolve: `@ninetailed/experience.js-plugin-insights`,
                    options: {}
                }
            ]
        }
    }
]
```

#### JavaScript

```javascript
import { Ninetailed } from '@ninetailed/experience.js';
import { NinetailedInsightsPlugin } from '@ninetailed/experience.js-plugin-insights'

export const ninetailed = new Ninetailed(
    {
        clientId: // Your client ID
        environment: // Your Ninetailed environment
    },
    {
        plugins: [
            new NinetailedInsightsPlugin();
        ],

        // Specify an amount of time (ms) that a component must be present in the viewport to register a component view
        componentViewTrackingThreshold: 2000,
    }
);
```

## Timing configuration

The Insights Plugin logs that a component has been seen only after the component has remained within the user's viewport for a specified amount of time (in milliseconds), determined by the value of the `componentViewTrackingThreshold` property on the instance (see code samples above). If the option is unspecified, the value defaults to `2000`.

> Track what entries and Experiences are being viewed to power Component Insights.