Arctrack
Analytics layer for Arc partner sites built with PageBuilder.
Description
Arctrack is an analytics utility library aimed at simplifying client-side analytics build-outs. It works by seeding an application with different types of action listeners that can respond to general or fine-tuned user actions.
API Overview
trackDom
Takes an options
object containing DOM target information and developer-defined (that's you) callbacks that will execute whenever a user action is tracked. trackDom
is set up to execute specified callbacks on DOM element click and on scroll.
options
Key | Data type | required? | default |
---|---|---|---|
dataAttr |
string |
false |
'data-arctrack' |
click |
function |
false |
undefined |
scroll |
array or object |
false |
undefined |
click
If you've seeded a page with data attributes that match dataAttr
, whenever these elements are clicked, your click
callback will fire with an object containing the following:
target
: DOM target element from click eventtype
: a camelcase string derived from the value of the data attribute that observed the click event on thetarget
element.
Example
some serverside page template:
<!-- other HTML or rendering tags --> <!-- markup... -->
the application's JS:
import { trackDom } from '@arc-publishing/arctrack'; const options = { dataAttr: 'data-sitetrack', click: function({ target, type }) { console.log('CLICKED!', target, type); // use your click data however you need to // pass it along to your analytics network call... }, // ...}; trackDom(options);
in the browser console after a user clicks the 'social share' div:
CLICKED!
div#foo...
socialShare
scroll
An array of scroll entries (objects), or a single scroll entry. Each entry corresponds to a DOM element that should trigger a tracking event when it's scrolled over.
Scroll Entry API .
Key | Data type | Required |
---|---|---|
load |
function |
true |
buffer |
object |
false |
selector |
string |
true |
type |
string |
true |
trackOnceOnly |
bool |
false |
load
Developer-defined callback that fires whenever the user scrolls over a page element of this scroll entry type. load
is passed an object containing:
target
: in this case,target
is an object containing two properties:node
, which is the DOM element that was scrolled over, anddata
, which is the value assigned to the scroll element's data attribute.type
: specified in this entry'stype
property.
buffer
An object containing properties top
and bottom
(both JavaScript number
), that tells the scroll listener if it should observe a scroll once a buffer (some amount of vertical pixel distance) has been breached either above or below a target element. This can be useful if a tracking event needs to be dispatched when a page element is almost in the viewport.
selector
Should correspond to a data-attribute name on types of elements you would like to have scroll-tracking for. For example, if selector: 'foo'
, the scroll entry API will search the DOM for elements with a data-foo
attribute.
trackOnceOnly
By default, the scroll entry API will continue to fire the load
callback every time a registered element is scrolled over. For example, if you've scrolled down over a registered element, it will fire, but if you then scroll back up over it, it will fire again. You can turn this off by setting trackOnceOnly
to true
.
In the example markup below, your selector
would be mysite-leaderboard-ad
:
<!-- markup... -->
type
A name you assign to a particular order of elements on a page. type
allows you to track scrolling for a number of different types of elements on a single page. type
can often just be the same value as selector
, but if you'd like the selector
and the element type
to be named differently, you have that flexibility.
Complete scrolling example
; const scrollEntries = ;scrollEntries;scrollEntries;const options = scroll: scrollEntries;;
In the example above, elements of type ad
have a buffer of 50px
, meaning load
will fire when the ad
element is within 50px
of the viewport. media-module
entries do not have a buffer.
trackJs
Decorator function used within ES6 classes (including React component classes) that takes a developer-defined callback and executes it whenever a decorated method is fired. This is an efficient way to track user interaction with React or ES6 service-based UIs because tracking transactions take place in memory and require zero interfacing with the DOM. This approach is inspired by New York Times react-tracking library.
trackJs
accepts two arguments, a callback (fn
) and an event name (string
). The callback will be called with an object containing the following data:
TrackJs API .
Key | Data type |
---|---|
methodName |
string |
instance |
object |
eventName |
string |
args |
JavaScript arguments object |
methodName
The name of the method that trackJs
is decorating.
Example:
; @ { console; }
When baz
is called, the trackJs
callback function above would print:
The method name is baz.
instance
The instance is the this
value of the class instance in which you are decorating. This is very useful in cases where you're tracking React component behavior, because you'll have access to state
and props
by way of instance
.
Example:
;; { superprops; thisstate = active: false } @ { this; } { return <div onClick=thishandleClick> /* ... */ </div> ; }
eventName
A string passed as the second argument to trackJs
, to be used by the callback to further categorize the type of behavior being tracked.
Example:
;;; { superprops; thisstate = active: false } @ { this; } { return <div onClick=thishandleClick> /* ... */ </div> ; }
analytics/index.js
const trackClicks = { if eventName === 'OPEN_MENU' if instancestate && !instancestateactive s; // ... }
In the example above, active
would be false
if the component were clicked to be opened, since the trackJs
callback fires before the method code itself runs, setting state to {active: true}
. Using eventName
allows you as the developer to combine multiple event types into a single callback, such as trackClicks
, which could track different types of click events differently depending on the eventName
value, but reuse a lot of code as well.
args
These are the arguments passed to the method you are decorating. For React onClick
handlers, this parameter could give you access to the click target, for very refined observation and tracking.
Example:
;; { superprops; thisstate = showComments: propsloggedIn ? false : true ; // ... } // ... @ { this; } { return <div> <button onClick=thistoggleShowComments> /* ... */ </button> thisstateshowComments && <Fragment> /* ... */ </Fragment> </div> ; }