# Perfume.js plugin for `analytics`
Send performance metrics to any analytics provider using [perfume.js](https://zizzamia.github.io/perfume/).
Perfume is a tiny, web performance monitoring library that reports field data back to your favorite analytics tool.
Using perfume.js with `analytics` makes wiring up your performances metrics to any third-party analytics tool nice & easy.
Click to expand
- [Installation](#installation)
- [How to use](#how-to-use)
- [Configuration options](#configuration-options)
- [Additional examples](#additional-examples)
- [Zero config](#zero-config)
- [Demo Video](#demo-video)
## Installation
```bash
npm install analytics
npm install @analytics/perfumejs
npm install perfume.js
```
## How to use
The `@analytics/perfumejs` package works in the browser to collect and send performance data to any third party analytics tool.
To use, install the package, include in your project and initialize the plugin with analytics.
By default, the perfume.js plugin will send performance metrics to all analytics plugins attached to `analytics`. You can customize this & disable specific providers with the optional `destinations` config setting.
Below is an example of how to use the browser plugin.
```js
import Analytics from 'analytics'
import customerIOPlugin from '@analytics/customerio'
import googleAnalytics from '@analytics/google-analytics'
import hubSpotPlugin from '@analytics/hubspot'
// Include perfume.js analytics plugin
import perfumePlugin from '@analytics/perfumejs'
// Include perfume.js library
import Perfume from 'perfume.js'
const analytics = Analytics({
app: 'my-app',
plugins: [
// Attach Google analytics
googleAnalytics({
trackingId: 'UA-12341131-6',
instanceName: 'two'
})
// Attach Hubspot analytics
hubSpotPlugin({
portalId: '234576'
}),
// Attach Customer.io analytics
customerIOPlugin({
siteId: '123-xyz'
})
/* Include perfume.js plugin */
perfumePlugin({
// Perfume.js class. If empty, window.Perfume will be used.
perfume: Perfume,
// Analytics providers to send performance data.
destinations: {
// perf data will sent to Google Analytics
'google-analytics': true,
// perf data will sent to Customer.io
'customerio': true,
// perf will NOT be sent to HubSpot
'hubspot': false
},
}),
]
})
/* Perfume.js will now automatically sent performance data
to Google Analytics and Customer.io 🎉 */
```
See [additional implementation examples](#additional-examples) for more details on using in your project.
## Configuration options
| Option | description |
|:---------------------------|:-----------|
| `perfume` _optional_ - object| perfume.js class. If not provided, a global window reference to Perfume will be used |
| `destinations` _optional_ - object| Where perfume.js will send performance data |
| `category` _optional_ - string| Name of event category. Default 'perfume.js' |
| `perfumeOptions` _optional_ - object| Options to pass to perfume.js instance. See https://github.com/Zizzamia/perfume.js#perfume-custom-options |
For more in how `destinations` option works, see [sending provider-specific events docs
](https://getanalytics.io/tutorials/sending-provider-specific-events/).
```js
perfumePlugin({
perfume: Perfume,
destinations: { all: true } // <-- default value to send to all plugins
})
```
Disable all and only send to specific plugins
```js
perfumePlugin({
perfume: Perfume,
destinations: {
all: false,
'hubspot': true, // <--- these are the plugin 'name' properties
'google-analytics': true // <--- these are the plugin 'name' properties
}
})
```
## Additional examples
Below are additional implementation examples.
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/perfumejs in HTML
....
```
Using in HTML via ES Modules
Using `@analytics/perfumejs` in ESM modules.
```html
Using @analytics/perfumejs in HTML via ESModules
....
```
## Zero config
For ease of use, there is a "zero-config" option where you only need to pass in the `Perfume` class to the analytics plugin. This will automatically send all performance metrics to all attached [analytic plugins](https://getanalytics.io/plugins).
```js
import Analytics from 'analytics'
import googleAnalytics from '@analytics/google-analytics'
import hubSpotPlugin from '@analytics/hubspot'
import perfumePlugin from '@analytics/perfumejs'
import Perfume from 'perfume.js'
const analytics = Analytics({
app: 'my-app',
plugins: [
// Attach Google analytics
googleAnalytics({
trackingId: 'UA-12341131-6',
instanceName: 'two'
})
// Attach Hubspot analytics
hubSpotPlugin({
portalId: '234576'
}),
// Include perfume.js plugin with no options set.
// This will send data to all analytics providers by default
perfumePlugin(Perfume),
]
})
```
## Demo Video