Guides.md

location Prop

A location prop is a subset of history's Location.

pathname      The pathname portion of the URL, without query string
search        The query string portion of the URL, including the ?
state         An object of data tied to this location
query         A parsed object from query string

params

params is an object of key/value pairs that were parsed out of the route's dynamic segment definition when available. For example, when your routing library allows you to define one of the routes as /user/:id, and the actual pathname for the URL is /user/123, the params will be {user: 123}.

routeState

routeState is an object which represents the current route state. It's essentially location + [params] and expected to change every time the URL changes.

react-metrics will try to expose params to routeState only when it's passed as props to metrics wrapper.

vendor

A vendor option is an object member of vendors option array in configuration object and supports 2 properties:

name

A name of the vendor service to be returned as part of tracking response if defined. This will override the name property defined in api.

api

An object, a class instance or a function which returns an object which exposes tracking APIs. You don't have to define pageView or track api, but keep in mind that react-metrics will assume those methods to exist for auto page view and declarative tracking and throws when not available. You can define name property in your api, which will be returned as part of tracking response.

Custom api methods can take 3 arguments:

someMethod(eventType?: string, eventData?: Object, shouldMergeWithDefaultObject?: boolean)

Example:

{
    vendors: [{
        name: "Your Service Name Override",
        api: {
            name: "Your Service Name",
            pageView() {
                // your logic here
            },
            track() {
                // your logic here
            },
            someMethod() {
                // your logic here
            }
        }
    }]
}

Route Change Detection

react-metrics assumes that metrics wrapper receives location props which is updated when the URL route changes to trigger page view call.

Here are the implementation guides per use cases:

Routing Solution	Action required	Example
React Router	Nothing!	Here
Using history	Pass its Location object to prop to metrics wrapper, optionally construct and pass params prop	Here
Other solutions	Construct location compliant prop and optionally params prop to pass to metrics wrapper	Here

You can override this logic by supplying getRouteState function as a configuration option.

How react-metrics detects your component as route handler?

When you wrap your component with exposeMetrics to make willTrackPageView available, react-metrics will register your component in its registry.

When the route changes, it assumes the last registered component as the route handler component. A route handler component is the one which takes care of rendering the view for the corresponding route URL.

For this assumption to work correctly, it's important to make sure your component gets mounted/unmounted as expected when a route changes.

You can override this logic by supplying findRouteComponent function as a configuration option.