React Metrics
An analytics module for React.
Requirements
- React 0.14+
Browser Requirements
- IE10+
Features
- Unobtrusive feature injection through a root application component.
- Supports page view tracking.
- Supports both imperative and declarative custom link tracking.
- Provides a custom event tracking API.
- Supports multiple simultaneous analytics vendor tracking.
Installation
$ npm install --save react-metrics
React Metrics depends on Promise to be available in browser. If your application support the browser which doesn't support Promise, please include the polyfill.
Getting Started
1. Configure Metrics
Refer to the docs for more information on configuration.
// Application.js; const config = vendors: name: "Google Analytics" api: trackingId: "UA-********-*" pageViewEvent: "pageLoad" { return siteName: "My Web Site" ... ; }
2. Wrap Application Level Component
Compose your top level application component with metrics
in order to provide metrics
to all components and automatically enable page view tracking.
// Application.jsComponent { return thispropschildren ; }configApplication;
Alternatively, if your development environment supports ES7, use the @decorator syntax instead:
// Application.js@Component { return thispropschildren ; }
Your application will now automatically trigger page view tracking.
3. Add Custom Link Tracking
a. Use data-
attributes to enable custom link tracking on your DOM elements.
// PaginationComponent.jsComponent { const commentId totalPage currentPage = thisprops; return <ul> <li className=currentPage > 0 ? "active" : ""> <a href="#" data-metrics-event-name="commentPageClick" data-metrics-comment-id=commentId data-metrics-page-num=currentPage - 1> Back </a> </li> <li>...</li> <li className=currentPage < totalPage - 1 ? "active" : ""> <a href="#" data-metrics-event-name="commentPageClick" data-metrics-comment-id=commentId data-metrics-page-num=currentPage + 1> Next </a> </li> </ul> ; }
b. Use MetricsElement
for custom link tracking on a nested DOM element.
Please see MetricsElement
for more use cases.
;// PaginationComponent.jsComponent { const commentId totalPage currentPage = thisprops; return <ul> <li className=currentPage > 0 ? "active" : ""> <MetricsElement element="a" href="#" data-metrics-event-name="commentPageClick" data-metrics-comment-id=commentId data-metrics-page-num=currentPage - 1> <span className="button">Back</span> </MetricsElement> </li> <li>...</li> <li className=currentPage < totalPage - 1 ? "active" : ""> <MetricsElement element="a" href="#" data-metrics-event-name="commentPageClick" data-metrics-comment-id=commentId data-metrics-page-num=currentPage + 1> <span className="button">Next</span> </MetricsElement> </li> </ul> ; }
4. Analytics Vendor Implementations
react-metrics
does not automatically supply any vendor analytics. You need to integrate with an analytics vendor to actually track something for reporting.
Refer to Vendor Examples for Omniture, Google Analytics and other implementations.
Also check out the awesome segmentio library which provides a lot of third party analytics vendors.
Advanced Usage
Override Default Page View Tracking
Use the @exposeMetrics
decorator and willTrackPageView()
methods on a route-handling component to override the default page view tracking behavior and pageDefaults
data.
- Example: disable automatic page view tracking and trigger page view tracking manually.
// PageComponent.js// Must be a "route handling" component: <Route path="my-page" component={PageComponent}/> ; @exposeMetricsComponent static contextTypes = metrics: PropTypesmetrics static { // first, suppress the automatic call. return false; } { const value1 value2 = thisprops; thiscontextmetrics; } { ... }
- Example: add custom data to automatic page view tracking.
// PageComponent.js "route-handler// A route handling component: <Route path="my-page" component={PageComponent}/> ; @exposeMetricsComponent static { // return a promise that resolves to custom data. return yourPromise; } { ... }
Imperative Custom Event Tracking
Use this.context.metrics.track()
to trigger custom event tracking as an alternative to declarative custom link tracking.
Define metrics
as a contextType
in your component and trigger custom track events using metrics.track()
.
; Component static contextTypes = metrics: PropTypesmetrics { thiscontextmetrics; } { ... }
Metrics API Outside a React Component
react-metrics
provides a low level factory API; this is convenient for exposing an instance of the metrics
API outside of a React component.
Use createMetrics
to create a metrics
instance and expose the metrics.api
.
// creating middleware for Redux ; const metrics = ; { return { const returnValue = ; return returnValue; };}
API, Examples, and Documentation
- API Review the
metrics
API - Getting Started A more detailed Getting Started Guide
- Vendor Examples Omniture, Google Analytics, and other analytics vendor examples.
- Docs Guides, API, and examples.
To run examples:
- Clone this repo
- Run
npm install
- Run
npm run examples
- Point your browser to http://localhost:8080
Contributing to this project
Please take a moment to review the guidelines for contributing.
License
MIT