rentspree-tracker

Tracking multiple analytics module for React

Overview

This module is the tracking event wrapper for widespread analytics tools. It solve the problem for application which integrates multiple analytics model by staggering events/pageview fire up and pass it through each of your config analytic models.

Install

$ npm install --save @rentspree/tracker

Usage

start by creating your new tracker

import Tracker from "@rentspree/tracker"

const tracker = new Tracker()

then you must create your tracker instance, one provider per one tracker instance

For example, I will import GoogleAnalytic

import { GATracker } from "@rentspree/tracker"

const gaTracker = new GATracker({ trackerId: "the-tracker-id-from-ga" })

After this, you must register your new tracker instance to the Tracker

tracker.registerTracker(gaTracker)

That's all the setup! now upon your event, you can call

tracker.trackEvent("ButtonClick", { data: "some-data" })

and the tracker will send the tracker event to every register tracker. In this case, it's only gonna be GoogleAnalytics that receive the tracking events.

API

Table of Contents

• Tracker
  • registerTracker
    • Parameters
    • Examples
  • trackPageView
    • Parameters
  • identifyUser
    • Parameters
  • identifyAmplitude
    • Parameters
  • trackEvent
    • Parameters
  • setAliasUser
    • Parameters
  • logout
• AmplitudeTracker
  • Parameters
  • getTracker
  • identifyUser
    • Parameters
  • identifyAmplitude
    • Parameters
  • trackEvent
    • Parameters
  • logout
• BaseTracker
  • Parameters
  • trackPageView
  • identifyUser
  • identifyAmplitude
  • trackEvent
  • setAliasUser
  • logout
• FullStoryTracker
  • identifyUser
    • Parameters
  • getTracker
• GATracker
  • Parameters
  • trackPageView
    • Parameters
  • identifyUser
    • Parameters
  • trackEvent
    • Parameters
  • getTracker
• HotjarTracker
  • Parameters
  • identifyUser
    • Parameters
  • logout
  • getTracker
• HubspotTracker
  • identifyUser
    • Parameters
  • getTracker
• MixpanelTracker
  • trackPageView
    • Parameters
  • identifyUser
    • Parameters
  • trackEvent
    • Parameters
  • setAliasUser
    • Parameters
  • getTracker
  • checkReady
• UserRecorderTracker
  • identifyUser
    • Parameters
  • logout
  • getTracker

Tracker

The tracker class, this class will be the one place to trigger any tracking event It will manage Instance that connect to each analytic provider and call to track all of those providers api when one event occur.

registerTracker

Register the tracker Instance to track. Each tracker must be initialize before register to the tracker

Parameters

• trackerInstance BaseTracker the tracker to be tracked

Examples

const tracker = new Tracker()
const gaTracker = new GATracker({trackerId: "hello-tracker"})
tracker.registerTracker(gaTracker)
// with this the gaTracker event handler will be fired everytime
// the tracker got an event

trackPageView

pass track page view parameter to every registeredTracker

Parameters

• url String the url to track
• path String the path to track
• properties Object the additional properties object to be passed to trackers (optional, default {})

identifyUser

pass identify user parameter to every registered tracker

Parameters

• profile Object the profile object that will be passed through mapUserIdentity and mapUserProfile for each tracker instance.

identifyAmplitude

pass identify user on the amplitude only

Parameters

• profile Object the profile object that will be passed through mapUserIdentity and mapUserProfile for only amplitude tracker instance.

trackEvent

pass track event parameter to every registered tracker

Parameters

• eventName String the event name
• eventProperties Object the event properties object to be passed to trackers

setAliasUser

pass alias user parameter to every registered tracker

Parameters

• alias String the alias to define alias of user

logout

trigger logout method on each trackers

AmplitudeTracker

Extends BaseTracker

The class for Amplitude tracker

Parameters

• options

getTracker

Static method for getting the amplitude tracker

Returns (Function | Proxy) the amplitude instance if it exist, this method will return Proxy to avoid error

identifyUser

Identify the user by calling setUserId(userId) the userId is a return from options.mapUserIdentity(profile) the method also send user properties for identify user in amplitude by calling identify(userPropertiesObj) the userPropertiesObject is a return from function _setUserProperties(this.mapUserProfile(profile)) which will create amplitude's user identify object from mapped user data the mapUserProfile should return the data with format below

{
   id: {
     value: "this-is-user-id",
     setOnce: true
   }
}

which value is the value of the key setOnce is indicator to set this key as unchangeable value in amplitude

Parameters

• profile Object the profile object

identifyAmplitude

This method is identifying for the amplitude analytics only

Parameters

• profile Object the user profile data

trackEvent

track the event by calling logEvent("event name here", properties)

Parameters

• eventName String the eventName
• properties Object the properties to be passed to amplitude (optional, default {})

logout

generate new session for amplitude tracker when user logout set userId to null

BaseTracker

Base for all Tracker class

Parameters

• options Object specify the tracker options

trackPageView

Dummy function for tracking page view

identifyUser

Dummy function for identify user

identifyAmplitude

Dummy function for identify user on the amplitude only

trackEvent

Dummy function for track event

setAliasUser

Dummy function for set alias of user

logout

Dummy function for user logged out

FullStoryTracker

Extends BaseTracker

The class for FullStory tracker

identifyUser

send the identity of this user to FullStory

• the identity of the user is the return from options.mapUserIdentity(profile)
• the user detail is the return from options.mapUserProfile(profile) The method simply call FA.identity(options.mapUserIdentity(profile), options.mapUserProfile(profile))

Parameters

• profile Object the user object

getTracker

Static method for getting the tracker from window

Returns (Object | Proxy) the FA object, if the function is not existed in window.FA, this method will return Proxy to avoid error

GATracker

Extends BaseTracker

The class for Google analytic tracker

Parameters

• options

trackPageView

Track the page view by calling gtag("config", trackingId, {page_locationi: url, page_path: path})

Parameters

• url String the url to track, this will be passed to page_location key
• path String the path, this will be passed to page_path key
• properties Object the additional properties
  • properties.ipAddress

identifyUser

Identify the user by calling gtag("config", ...userObject) the userObject is a return from options.mapUserProfile(profile)

Parameters

• profile Object the profile object

trackEvent

track the event by calling gtag("event", eventName, properties)

Parameters

• eventName String the eventName
• properties Object the properties to be passed to gtag (optional, default {})

getTracker

Static method for getting the tracker from window

Returns (Function | Proxy) the gtag function, if the function is not existed in window.gtag, this method will return Proxy to avoid error

HotjarTracker

Extends BaseTracker

The class for HotjarTracker tracker

Parameters

• args ...any

identifyUser

send the identity of this user to HotjarTracker

• the identity of the user is the return from options.mapUserIdentity(profile)
• the user detail is the return from options.mapUserProfile(profile)

Parameters

• profile Object the user object

logout

This method is removing Hotjar session with Local Storage and Cookie for getting a newer Hotjar session for recording correct a new user logged in

getTracker

Static method for getting the tracker from window

Returns (Object | Proxy) the hj object, if the function is not existed in window.hj, this method will return Proxy to avoid error

HubspotTracker

Extends BaseTracker

The class for Hubspot Analytic Tracker

identifyUser

Identify the user by calling _hsq.push(["identify",{ email: userObject.email }]) the userObject is a return from options.mapUserIdentity(profile) The Hubspot identify will not immediately create the user contact in Hubspot. Hubspot need to receive event or pageView after the identify to create the user contact. If you want to instantly create the user contact then you need to send instantlyCreateContact as true from options.mapUserIdentity(profile)

Parameters

• profile Object the profile object

getTracker

Static method for getting the tracker from window

Returns (object | Proxy) the Hubspot tracking sdk, if the sdk is not existed in window._hsq, this method will return proxy to prevent error

MixpanelTracker

Extends BaseTracker

Class For Mixpanel tracker This is a complex class working directly with Mixpanel Lib It ensure the readiness of Mixpanel.js library and prepare API for React

trackPageView

Track the page view by calling mixpanel.track("page viewd", ...)

Parameters

• url String the url to track
• path String the path
• properties Object the additional properties (optional, default {})

identifyUser

Identify the user this will call two mixpanel methods

• mixpanel.identify sending mapUserIdentity(profile)
• mixpanel.people.set sending (mapUserProfile(profile)

Parameters

• profile Object the user object to be mapped and sent to Mixpanel
• ip

trackEvent

Track the event by calling mixpanel.track(eventName, properties)

Parameters

• eventName String the eventName
• properties Object the properties object to be passed to Mixpanel (optional, default {})

setAliasUser

Setup alias to identify user when that user signup successfully by calling mixpanel.alias(alias)

Parameters

• alias String the alias to define alias of user

getTracker

Static method for getting the tracker from window

Returns (Object | Proxy) the mixpanel object, if the object is not existed in window.mixpanel, this method will return Proxy to avoid error

checkReady

Check if mixpanel object is ready by checking `window.mixpanel.__loaded

Returns Boolean wether the mixpanel object is ready

UserRecorderTracker

Extends BaseTracker

This class for capturing user behavior and user reaction on the website

identifyUser

identity the user information to provider script for mapping user on user recording provider

Parameters

• profile Object the user data object

logout

This method is removing session recording with Local Storage and Cookie for getting a newer recording session for recording correct a new user logged in

getTracker

Static method for getting the tracker from window

Returns (Object | Proxy) the user-recorder object from the provider if the function is not existed, this method will return Proxy to avoid error

License

MIT © Putt