Single-Page Application Relay for Google Analytics
npm install --save sparga
// for ES6 clients
import Sparga from 'sparga'
// for non-ES6 clients
const Sparga = require('sparga').default
const sparga = new Sparga()
sparga.init('UA-123456-7')
//
// Now all page views in your SPA will
// automatically be tracked in GA.
//
// Additionally, all unhandled JavaScript
// exceptions will also be tracked.
//
// NOTE: Automatic tracking of page views
// and JavaScript exceptions can be turned
// off by setting respective flags to false
// on the options object. See the API docs
// for specifics.
//
const sparga = new Sparga()
sparga.init({
gaSettings: 'UA-123456-7',
autoCaptureClickEvents: true
})
//
// Now all mouse clicks in your SPA will
// automatically be tracked in GA.
//
For more info, refer to the GA Field Reference
const sparga = new Sparga()
sparga.init({
gaSettings: 'UA-123456-7',
//
// your dimension map will likely be governed
// by a central team as GA only allows a limited
// number of custom dimensions, depending on your
// account type...as such, this map is usually
// defined once and used many times for an organization
//
dimensionMap: {
variantTestName: 'dimension1',
variantTestSampling: 'dimension9',
userRole: 'dimension17'
}
})
sparga.setDimension('variantTestName', 'Variant Testing for Our Exciting New Feature')
sparga.setDimension('variantTestSampling', 'Customers in US having more than 100 users.')
sparga.setDimension('userRole', 'non-admin')
For more info, refer to the GA Field Reference
const sparga = new Sparga()
sparga.init({
gaSettings: 'UA-123456-7',
//
// your metric map will likely be governed
// by a central team as GA only allows a limited
// number of custom metrics, depending on your
// account type...as such, this map is usually
// defined once and used many times for an organization
//
metricMap: {
isNewUser: 'metric6',
isUserAdmin: 'metric8',
isViewSetAsPersistent: 'metric14'
}
})
sparga.setMetric('isNewUser', 1)
sparga.setMetric('isUserAdmin', 0)
sparga.setMetric('isViewSetAsPersistent', 1)
Sometimes a site/page needs to report to multiple tracking IDs, which is only possible if named trackers are used.
const sparga = new Sparga()
// NOTE: If a trackerMap is provided, then the
// gaSetting.trackingId will be ignored.
sparga.init({
gaSettings: {
trackingId: 'THIS WILL NOW BE IGNORED!'
},
trackerMap: {
myTracker1: 'UA-123456-7',
myTracker2: 'UA-123456-8',
myTracker3: 'UA-123456-9'
}
})
//
// Now all of the above tracking IDs will be sent pageview
// and exception events.
//
// Additionally, all of the Sparga helper methods will also
// use the above tracking IDs--or a subset of them, if specified
//
// send a custom event to ALL trackers (i.e. all tracking IDs)
sparga.sendEvent(
'MyCategory-1', 'MyAction-1', 'MyLabel-1', 'MyValue-1'
)
// send a custom event to only TWO of the three trackers
sparga.sendEvent(
'MyCategory-2', 'MyAction-2', 'MyLabel-2', 'MyValue-2',
[ 'myTracker1', 'myTracker3']
)
All native options for creating a GA tracking session are exposed via the gaSettings property on Sparga's intitialization object. The following example shows how to create a custom tracker by initializing with a gaSettings object.
const sparga = new Sparga()
sparga.init({
gaSettings: {
trackingId: 'UA-123456-7',
userId: 'user123',
sessionControl: 'start',
cookieExpires: 86400
}
})
Sparga sets the following GA settings by default, which are different than the defaults that GA applies. As with all settings, these are overridable by passing in the respective key-value pairs on the gaSettings property of the options object.
- allowAnchor: false
- alwaysSendReferrer: true
- forceSSL: true
- cookieDomain: 'auto'
- siteSpeedSampleRate: 100
- storeGac: false
- sendEvent
- sendPageView
- sendException
- sendSocial
- sendTiming
Refer to the API.doc for more details.