# rudderstack plugin for `analytics`
Integration with [rudderstack](https://rudderstack.com/)
for [analytics](https://www.npmjs.com/package/analytics)
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)
- [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 begrowth-analytics-rudderstack
```
## How to use
The `begrowth-analytics-rudderstack` 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 rudderstackPlugin from "begrowth-analytics-rudderstack";
const analytics = Analytics({
app: "awesome-app",
plugins: [
rudderstackPlugin({
writeKey: "123-xyz",
dataPlaneURL: "dataplane.com"
})
]
});
/* 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 `rudderstackPlugin` plugin, data will be sent into
rudderstack 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 `begrowth-analytics-rudderstack` package works in [the browser](#browser-usage)
and [server-side in Node.js](#server-side-usage)
## Browser usage
The rudderstack client side browser plugin works with these analytic api methods:
- **[analytics.page](https://getanalytics.io/api/#analyticspage)** - Sends page views into
rudderstack
- **[analytics.track](https://getanalytics.io/api/#analyticstrack)** - Track custom events and send
to rudderstack
- **[analytics.identify](https://getanalytics.io/api/#analyticsidentify)** - Identify visitors and
send details to rudderstack
- **[analytics.reset](https://getanalytics.io/api/#analyticsreset)** - Reset browser storage cookies
& localstorage for rudderstack values
### Browser API
```js
import Analytics from "analytics";
import rudderstackPlugin from "begrowth-analytics-rudderstack";
const analytics = Analytics({
app: "awesome-app",
plugins: [
rudderstackPlugin({
writeKey: "123-xyz",
dataPlaneURL: "dataplane.com"
})
]
});
```
### Configuration options for browser
| Option | description |
| :------------------------------------ | :------------------------ |
| `writeKey`
**required** - string | Your rudderstack writeKey |
| `disableAnonymousTraffic`
_
optional_ - boolean| Disable loading rudderstack for anonymous visitors | | `customScriptSrc`
_
optional_ - boolean| Override the rudderstack snippet url, for loading via custom CDN proxy |
| `integrations`
_
optional_ - object| Enable/disable rudderstack destinations https://bit.ly/38nRBj3 |
## Server-side usage
The rudderstack server-side node.js plugin works with these analytic api methods:
- **[analytics.page](https://getanalytics.io/api/#analyticspage)** - Sends page views into
rudderstack
- **[analytics.track](https://getanalytics.io/api/#analyticstrack)** - Track custom events and send
to rudderstack
- **[analytics.identify](https://getanalytics.io/api/#analyticsidentify)** - Identify visitors and
send details to rudderstack
### Server-side API
```js
import Analytics from "analytics";
import rudderstackPlugin from "begrowth-analytics-rudderstack";
const analytics = Analytics({
app: "awesome-app",
plugins: [
rudderstackPlugin({
writeKey: "123-xyz",
dataPlaneURL: "dataplane.com"
})
]
});
```
### Configuration options for server-side
| Option | description |
| :------------------------------------ | :------------------------ |
| `writeKey`
**required** - string | Your rudderstack writeKey |
| `flushInterval`
_
optional_ - boolean| rudderstack sdk flushInterval. Docs https://bit.ly/2H2jJMb |
| `disableAnonymousTraffic`
_
optional_ - boolean| Disable loading rudderstack for anonymous visitors |
## Additional examples
Below are additional implementation examples.
Server-side ES6
```js
import Analytics from "analytics";
import rudderstackPlugin from "begrowth-analytics-rudderstack";
const analytics = Analytics({
app: "awesome-app",
plugins: [
rudderstackPlugin({
writeKey: "123-xyz",
dataPlaneURL: "dataplane.com"
})
// ...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 rudderstackPlugin = require("begrowth-analytics-rudderstack").default;
const analytics = analyticsLib({
app: "my-app-name",
plugins: [
rudderstackPlugin({
writeKey: "123-xyz",
dataPlaneURL: "dataplane.com"
})
]
});
/* 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 begrowth-analytics-rudderstack in HTML
....
```
Using in HTML via ES Modules
Using `begrowth-analytics-rudderstack` in ESM modules.
```html
Using begrowth-analytics-rudderstack in HTML via ESModules
....
```
## Loading script from custom proxy
In specific scenarios, you might want to load your own version of rudderstack's analytics from a
different URL.
To do this, you can add the `customScriptSrc` option pointing to your custom rudderstack script.
```js
import Analytics from "analytics";
import rudderstackPlugin from "begrowth-analytics-rudderstack";
const analytics = Analytics({
app: "awesome-app",
plugins: [
rudderstackPlugin({
writeKey: "123-xyz",
dataPlaneURL: "dataplane.com",
// Load rudderstack's analytics.js from somewhere else
customScriptSrc: "https://yoursite.com/my-custom-loader.js"
})
]
});
```
## Making group calls
The `.group` call is specific to rudderstack 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 rudderstack run the `analytics.plugins.rudderstack.group()` custom method.
The `analytics.plugins.rudderstack.group` function has the following signature:
```js
analytics.group(groupId, [traits], [options], [callback]);
```
### Browser Example
```js
import Analytics from "analytics";
import rudderstackPlugin from "begrowth-analytics-rudderstack";
// Initialize analytics instance with plugins
const analytics = Analytics({
app: "your-app-name",
plugins: [
rudderstackPlugin({
writeKey: "123-xyz",
dataPlaneURL: "dataplane.com"
})
]
});
// Usage:
// Now you can call rudderstack.group in your app like so
analytics.plugins.rudderstack.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 rudderstackPlugin = require("begrowth-analytics-rudderstack");
// Initialize analytics instance with plugins
const analytics = Analytics({
app: "your-app-name",
plugins: [
rudderstackPlugin({
writeKey: "123-xyz",
dataPlaneURL: "dataplane.com"
})
]
});
analytics.plugins.rudderstack.group("Group ID XYZ", {
principles: ["Bill", "Bob"],
site: "Apple co",
statedGoals: "Do awesome stuff",
industry: "Technology"
});
```