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

# Segment plugin

> Send Ninetailed Experience views as Twilio Segment `track` events.

Segment is a powerful customer data orchestration tool. This plugin allows you to send experience views to a Segment as [track](https://segment.com/docs/connections/spec/track/#properties) events via a connected [Analytics.js source](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/).

## Installation

Install the dependency:

#### npm

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

#### yarn

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

Then, add the plugin to the instance:

#### React, Next.js

```jsx
import { NinetailedSegmentPlugin } from '@ninetailed/experience.js-plugin-segment'
```

```jsx
<NinetailedProvider
  // ...
  plugins={[
    new NinetailedSegmentPlugin()
  ]}
  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-segment`,
                    options: {}
                }
            ]
        }
    }
]
```

#### JavaScript

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

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

        // 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 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 five default parameters:

| Parameters                   | Value Type | Value Description                          |
| ---------------------------- | ---------- | ------------------------------------------ |
| ninetailed\_experience       | String     | Experience ID of the experience            |
| ninetailed\_experience\_name | String     | Title of the experience entry from the CMS |
| ninetailed\_variant          | String     | "control", "variant 1", "variant 2", …     |
| ninetailed\_audience         | String     | CMS entry ID of the audience               |
| ninetailed\_component        | String     | CMS entry ID of the shown variant          |

## Custom event properties

You can also define your own variables to push to Segment 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 Segment track event 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 event property titled `ninetailed_audience_name`. The default event properties are also pushed.

#### React, Next.js

```jsx
<NinetailedProvider
   // ...
    plugins={[
      new NinetailedSegmentPlugin({
        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-segment`,
                    options: {
                        template: {
                            ninetailed_audience_name: '&#123;&#123; audience.name &#125;&#125;',
                        }
                    }
                }
            ]
        }
    }
]
```

#### JavaScript

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

export const ninetailed = new Ninetailed(
    {
        clientId: // Your client ID
        environment: // Your Ninetailed environment
    },
    {
        plugins: [
            new NinetailedSegmentPlugin({
              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 Ninetailed Experience views as Twilio Segment `track` events.