> 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.

# Contentsquare plugin

> Send relevant events downstream to your customer data platforms or analytics tools.

The Contentsquare plugin sends experience impression events to a web instance of Contentsquare by pushing those events to Contentsquare's data layer.

## Installation

Install the dependency:

#### npm

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

#### yarn

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

Then, add the plugin to the Ninetailed instance:

#### React, Next.js

```jsx
import { NinetailedContentsquarePlugin } from '@ninetailed/experience.js-plugin-contentsquare';
```

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

#### Gatsby

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

#### JavaScript

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

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

        // 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 Contentsquare Plugin logs that an element has been seen only after the element 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 Ninetailed instance (see code samples above). If the option is unspecified, the value defaults to `2000`.

## Default data layer properties

Events sent from this plugin are named `nt_experience`. They are sent with the following default properties:

| Parameter  | Value Type | Value Description                      |
| ---------- | ---------- | -------------------------------------- |
| experience | String     | Experience ID of the experience        |
| variant    | String     | "control", "variant 1", "variant 2", … |
| audience   | String     | CMS entry ID of the audience           |
| component  | String     | CMS entry ID of the shown variant      |

## Custom event properties

You can also define your own variables to push to Contentsquare's data layer on each event by passing in a configuration object when instantiating the plugin. To do so, define a config object with a `template` property whose value is an object consisting of key-value pairs, where the key is the name of the property you want to add to the Contentsquare data layer and the value is a string of the desired variable value surrounded by double curly braces (`&#123;&#123; &#125;&#125;`).

### Available properties

| Property                   | Notes                                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| experience.id              |                                                                                                   |
| experience.type            | `nt_experiment` or `nt_personalization`                                                           |
| experience.name            |                                                                                                   |
| experience.description     |                                                                                                   |
| audience.id                | `ALL_VISITORS` if not set                                                                         |
| audience.name              | `All Visitors` if not set                                                                         |
| audience.description       |                                                                                                   |
| selectedVariant            |                                                                                                   |
| selectedVariant.YOUR\_PROP | Specify any property key from the selected experience variant                                     |
| selectedVariantIndex       | 0, 1, 2, etc.                                                                                     |
| selectedVariantSelector    | "control", "variant 1", "variant 2", etc. This is a mapping of `selectedVariantIndex` from above. |

### Example custom use

This example shows passing the human-readable name of an audience to a custom data layer property titled `ninetailed_audience_name`. The default data layer properties are also pushed.

#### React, Next.js

```jsx
<NinetailedProvider
   // ...
    plugins={[
      new NinetailedContentsquarePlugin({
        template: {
          ninetailed_audience_name: '&#123;&#123; audience.name &#125;&#125;',
        },
      })
     ]}
     componentViewTrackingThreshold={2000}
  >
   //...
 </NinetailedProvider>
```

#### Gatsby

```javascript
plugins: [
    // ...
    {
        resolve: `@ninetailed/experience.js-gatsby`,
        options: {
            // ...
            componentViewTrackingThreshold: 2000,
            ninetailedPlugins: [
                {
                    resolve: `@ninetailed/experience.js-plugin-contentsquare`,
                    options: {
                        template: {
                            ninetailed_audience_name: '&#123;&#123; audience.name &#125;&#125;',
                        }
                    }
                }
            ]
        }
    }
]
```

#### JavaScript

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

export const ninetailed = new Ninetailed(
    {
        clientId: // Your client ID
        environment: // Your Ninetailed environment
    },
    {
        plugins: [
            new NinetailedContentsquarePlugin({
            template: {
              ninetailed_audience_name: '&#123;&#123; audience.name &#125;&#125;',
            },
          });
        ],

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

> Send relevant events downstream to your customer data platforms or analytics tools.