# Segment plugin for `analytics`
Integration with [segment](https://segment.com/) for [analytics](https://www.npmjs.com/package/analytics)
For more information [see the docs](https://getanalytics.io/plugins/segment/).
Click to expand
- [Installation](#installation)
- [How to use](#how-to-use)
- [Platforms Supported](#platforms-supported)
- [Browser usage](#browser-usage)
- [Browser API](#browser-api)
- [Configuration options for browser](#configuration-options-for-browser)
- [Server-side usage](#server-side-usage)
- [Server-side API](#server-side-api)
- [Configuration options for server-side](#configuration-options-for-server-side)
- [Additional examples](#additional-examples)
- [Customing the page name field](#customing-the-page-name-field)
- [Loading script from custom proxy](#loading-script-from-custom-proxy)
- [Making group calls](#making-group-calls)
- [Browser Example](#browser-example)
- [Server side Example](#server-side-example)
## Installation
```bash
npm install analytics
npm install @analytics/segment
```
## How to use
The `@analytics/segment` package works in [the browser](#browser-usage) and [server-side in Node.js](#server-side-usage). To use, install the package, include in your project and initialize the plugin with [analytics](https://www.npmjs.com/package/analytics).
Below is an example of how to use the browser plugin.
```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
segmentPlugin({
writeKey: '123-xyz'
})
]
})
/* Track a page view */
analytics.page()
/* Track a custom event */
analytics.track('cartCheckout', {
item: 'pink socks',
price: 20
})
/* Identify a visitor */
analytics.identify('user-id-xyz', {
firstName: 'bill',
lastName: 'murray'
})
```
After initializing `analytics` with the `segmentPlugin` plugin, data will be sent into Segment whenever [analytics.page](https://getanalytics.io/api/#analyticspage), [analytics.track](https://getanalytics.io/api/#analyticstrack), or [analytics.identify](https://getanalytics.io/api/#analyticsidentify) are called.
See [additional implementation examples](#additional-examples) for more details on using in your project.
## Platforms Supported
The `@analytics/segment` package works in [the browser](#browser-usage) and [server-side in Node.js](#server-side-usage)
## Browser usage
The Segment client side browser plugin works with these analytic api methods:
- **[analytics.page](https://getanalytics.io/api/#analyticspage)** - Sends page views into Segment
- **[analytics.track](https://getanalytics.io/api/#analyticstrack)** - Track custom events and send to Segment
- **[analytics.identify](https://getanalytics.io/api/#analyticsidentify)** - Identify visitors and send details to Segment
- **[analytics.reset](https://getanalytics.io/api/#analyticsreset)** - Reset browser storage cookies & localstorage for Segment values
### Browser API
```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
segmentPlugin({
writeKey: '123-xyz'
})
]
})
```
### Configuration options for browser
| Option | description |
|:---------------------------|:-----------|
| `writeKey`
**required** - string| Your segment writeKey |
| `disableAnonymousTraffic`
_optional_ - boolean| Disable loading segment for anonymous visitors |
| `customScriptSrc`
_optional_ - boolean| Override the Segment snippet url, for loading via custom CDN proxy |
| `integrations`
_optional_ - object| Enable/disable segment destinations https://bit.ly/38nRBj3 |
## Server-side usage
The Segment server-side node.js plugin works with these analytic api methods:
- **[analytics.page](https://getanalytics.io/api/#analyticspage)** - Sends page views into Segment
- **[analytics.track](https://getanalytics.io/api/#analyticstrack)** - Track custom events and send to Segment
- **[analytics.identify](https://getanalytics.io/api/#analyticsidentify)** - Identify visitors and send details to Segment
### Server-side API
```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
segmentPlugin({
writeKey: '123-xyz'
})
]
})
```
### Configuration options for server-side
| Option | description |
|:---------------------------|:-----------|
| `writeKey`
**required** - string| Key that corresponds to your Segment.io project |
| `disableAnonymousTraffic`
_optional_ - boolean| Disable loading segment for anonymous visitors |
| `host`
_optional_ - string| The base URL of the API. Default: "https://api.segment.io" |
| `path`
_optional_ - string| The API path route. Default: "/v1/batch" |
| `maxRetries`
_optional_ - number| The number of times to retry flushing a batch. Default: 3 |
| `maxEventsInBatch`
_optional_ - number| The number of messages to enqueue before flushing. Default: 15 |
| `flushInterval`
_optional_ - number| The number of milliseconds to wait before flushing the queue automatically. Default: 10000 |
| `httpRequestTimeout`
_optional_ - number| The maximum number of milliseconds to wait for an http request. Default: 10000 |
| `disable`
_optional_ - boolean| Disable the analytics library. All calls will be a noop. Default: false. |
| `httpClient`
_optional_ - HTTPFetchFn| Supply a default http client implementation |
## Additional examples
Below are additional implementation examples.
Server-side ES6
```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
segmentPlugin({
writeKey: '123-xyz'
})
// ...other plugins
]
})
/* Track a page view */
analytics.page()
/* Track a custom event */
analytics.track('cartCheckout', {
item: 'pink socks',
price: 20
})
/* Identify a visitor */
analytics.identify('user-id-xyz', {
firstName: 'bill',
lastName: 'murray'
})
```
Server-side Node.js with common JS
If using node, you will want to import the `.default`
```js
const analyticsLib = require('analytics').default
const segmentPlugin = require('@analytics/segment').default
const analytics = analyticsLib({
app: 'my-app-name',
plugins: [
segmentPlugin({
writeKey: '123-xyz'
})
]
})
/* Track a page view */
analytics.page()
/* Track a custom event */
analytics.track('cartCheckout', {
item: 'pink socks',
price: 20
})
/* Identify a visitor */
analytics.identify('user-id-xyz', {
firstName: 'bill',
lastName: 'murray'
})
```
Using in HTML
Below is an example of importing via the unpkg CDN. Please note this will pull in the latest version of the package.
```html
Using @analytics/segment in HTML
....
```
Using in HTML via ES Modules
Using `@analytics/segment` in ESM modules.
```html
Using @analytics/segment in HTML via ESModules
....
```
## Customing the page name field
By default the page name is the `document.title` value.
To have shorter names call page like so:
```js
analytics.page({
name: 'HomePage'
})
```
This can quickly become tricky to manage and we'd advise against this approach.
## Loading script from custom proxy
In specific scenarios, you might want to load your own version of segment's analytics from a different URL.
To do this, you can add the `customScriptSrc` option pointing to your custom segment script.
```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'
const analytics = Analytics({
app: 'awesome-app',
plugins: [
segmentPlugin({
writeKey: '123-xyz',
// Load segment's analytics.js from somewhere else
customScriptSrc: 'https://yoursite.com/my-custom-loader.js'
})
]
})
```
## Making group calls
The `.group` call is specific to Segment and the analytics lib doesn't expose this by default. But you are in luck 😃 thanks to [custom methods](https://getanalytics.io/plugins/writing-plugins/#adding-custom-methods) on plugins!
To send a group call to Segment run the `analytics.plugins.segment.group()` custom method.
The `analytics.plugins.segment.group` function has the following signature:
```js
analytics.group(groupId, [traits], [options], [callback]);
```
### Browser Example
```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'
// Initialize analytics instance with plugins
const analytics = Analytics({
app: 'your-app-name',
plugins: [
segmentPlugin({
writeKey: '123-xyz'
}),
]
})
// Usage:
// Now you can call segment.group in your app like so
analytics.plugins.segment.group('Group ID XYZ', {
principles: ['Bill', 'Bob'],
site: 'Apple co',
statedGoals: 'Do awesome stuff',
industry: 'Technology'
})
```
### Server side Example
```js
const analyticsLib = require('analytics').default
const segmentPlugin = require('@analytics/segment')
// Initialize analytics instance with plugins
const analytics = Analytics({
app: 'your-app-name',
plugins: [
segmentPlugin({
writeKey: '123-xyz'
}),
]
})
analytics.plugins.segment.group('Group ID XYZ', {
principles: ['Bill', 'Bob'],
site: 'Apple co',
statedGoals: 'Do awesome stuff',
industry: 'Technology'
})
```