Wraps your root level component and returns wrapped component which exposes metrics
context where your child component can access APIs defined in your configuration.
ES6
class Application extends React.Component {
...
}
export default metrics(config, options)(Application);
ES7 decorator
@metrics(config, options)
class Application extends React.Component {
...
}
A configuration object to create metrics instance.
Example:
{
enabled: true,
vendors: [
{
name: "Google Analytics",
api: new GoogleAnalytics({
trackingId: "UA-********-*"
})
},
{
name: "Adobe Tag Manager"
api: new AdobeTagManager({
seedFile: "****"
})
}
],
pageViewEvent: "pageLoad",
pageDefaults: () => {
return {
siteName: "My Web Site",
...
};
},
customParams: {
...
},
debug: true
}
vendors
(required) - An array of tracking api configuration object for each vendor.enabled
(optional) - A flag to enable or disable metrics functionality. Default value istrue
.pageViewEvent
(optional) - A default page view event name. You can optionally override this value by sending other event name from page view call. Default value ispageLoad
.pageDefaults
(optional) - A function to return common page view tracking metrics that's sent for all page view call. This will receiverouteState
argument where you can use to send route specific information. Default value is a function which returns an empty object.customParams
(optional) - An optional object which gets merged intopageDefaults
if specified.requestTimeout
(optional) - An optional time out value for the tracking request if specified. Default value is15000
ms.cancelOnNext
(optional) - An optional flag to indicate whether the pending request should be canceled when the route changes if specified. Default value istrue
.getRouteState
(optional) - A function which returns the newrouteState
upon route change, returnsnull
otherwise. This takes old and new props as arguments. Pass your own function to override default logic.findRouteComponent
(optional) - A function which returns the route handler component. Pass your own function to override default logic.
Example:
{
autoTrackPageView: false,
useTrackBinding: true,
attributePrefix: "custom",
suppressTrackBindingWarning: true
}
autoTrackPageView
(optional) - A flag to indicate whether a page view is triggered automatically by a route change detection or not. Default value istrue
.useTrackBinding
(optional) - A flag to indicate whether metrics should use track binding. Default value istrue
.attributePrefix
(optional) - An element attribute prefix to use for tracking bining. Default value isdata-metrics
.suppressTrackBindingWarning
(optional) - A flag to indicate whether the warning which is presented when both the default track binding andMetricsElement
are used should be suppressed or not. Default value isfalse
.
Wraps your component and returns wrapped component which is aware of willTrackPageView
static method in your component. willTrackPageView
gets called when react-metrics detects your component as route handler component.
willTrackPageView
will receive routeState
.
ES6
class MyComponent extends React.Component {
...
}
MyComponent.willTrackPageView = (routeState) => {
return myTrackingData;
}
export default exposeMetrics(MyComponent);
ES7 decorator
@exposeMetrics
class MyComponent extends React.Component {
static willTrackPageView(routeState) {
return myTrackingData;
}
}
type | description |
---|---|
metrics | A type which exposes all API methods |
location | A type which contains route information |
Low level factory API which creates metrics instance. This can be used for non-React project or for decoupling metrics from React component by using it from Flux store or Redux middleware.
Example:
// creating middleware for Redux
import {createMetrics} from "react-metrics";
const metrics = createMetrics(config);
export default function metricsMiddleware() {
return next => action => {
const returnValue = next(action);
switch (action.type) {
case ActionTypes.ROUTE_CHANGE:
const {location} = action;
const paths = location.pathname.substr(1).split("/");
const routeState = location;
metrics.setRouteState(routeState);
metrics.api.pageView({
category: !paths[0] ? "landing" : paths[0]
});
}
return returnValue;
};
}
MetricsElement
is a react component which detects click event on tracking elements within its children including itself and sends tracking data.
To minimize the child element traversing, it is recommended that you add MetricsElement
as the closest common parent against the children you are tracking.
Also, when you use MetricsElement
in your application, you should stick with MetricsElement
for all the declarative tracking and turn off the default track binding by passing useTrackBinding=false
to the metrics
options to avoid double tracking accidentally.
element
(optional) - Either a string to indicate a html element, a component class or a component instance to render.- any arbitrary tracking attributes.
Sends tracking data defined as its own props. You can pass the element
prop with html tag string, component class or component instance.
If a component instance is passed as element
props, it will be cloned with new props merged into the original props of the component instance.
Example:
import React from "react";
import {MetricsElement} from "react-metrics";
const MyComponent = () => (
<div>
<MetricsElement element="a" data-metrics-event-name="SomeEvent" data-metrics-value="SomeValue">
<img src="..."/>
</MetricsElement>
</div>
);
If element
is not set, it renders its children only.
Example:
import React from "react";
import {MetricsElement} from "react-metrics";
const MyComponent = () => (
<div>
<MetricsElement>
<a data-tracking-event-name="SomeEvent" data-tracking-value="SomeValue">
<img src="..." />
</a>
</MetricsElement>
</div>
);
Sends tracking data defined as child component's props.
Example:
import React from "react";
import {MetricsElement} from "react-metrics";
const MyComponent = (props) => {
const listItem = props.items.map(item => (
<li
key={item.id}
data-metrics-event-name="SomeEvent"
data-metrics-key={item.id}
data-metrics-value={item.value}
>
<img src={item.imageUrl} alt={item.title} />
</li>
));
return (
<div>
<MetricsElement element="ul">
{listItem}
</MetricsElement>
</div>
);
};
Metrics data defined in MetricsElement
and its children will get merged.
Example:
<MetricsElement
element="div"
data-metrics-page="page A"
>
<div
data-metrics-section="section 1"
data-metrics-event-name="imageClick"
>
<a data-metrics-value="Image 1">
<img src="http://placehold.it/200x150?text=Image+1" />
</a>
</div>
<div
data-metrics-section="section 2"
data-metrics-event-name="listItemClick"
>
<ul>
<li data-metrics-value="list item 1"><span>Item 1</span></li>
<li data-metrics-value="list item 2"><span>Item 2</span></li>
<li data-metrics-value="list item 3"><span>Item 3</span></li>
</ul>
</div>
</MetricsElement>
Clicking Image 1
will send the following data to react-metrics
:
{
eventName: "imageClick",
params: {
page: "page A",
section: "section 1",
value: "Image 1"
}
}
Clicking Item 1
in the list will send the following data to react-metrics
:
{
eventName: "listItemClick",
params: {
page: "page A",
section: "section 2",
value: "list item 1"
}
}