@impervaos/google-analytics-spa

    1.4.1 • Public • Published

    downloads per month html5 coverage tests Known Vulnerabilities

    Google Analytics automatic reporter

    This library was created with Single Page Application architecture in mind. You can use it with ReactJs, Angular, Vue or just vanilla javascript code. Its goal is to provide as automatic as possible usage of Google Analytics for SPAs (Single Page Applications). So you could free yourself to deal with other tasks

    Some of its features that come virtually without any "price tag" are

    • AUTOMATIC reporting of virtual navigation (based on HTML5 history object) including reporting page alias and not the actual url
    • AUTOMATICALLY reports your REST call & navigation performance to GA - so you could monitor download, server and duration times.
    • AUTOMATICALLY reports the "time to first paint" for your application - i.e. how fast the users see the first meaningful page of your application (and not a blank page)
    • Reporting any Redux action AUTOMATICALLY to GA using 'reportGoogleAnalytics' decorator and 'GaReportingReduxMiddleware' middleware
    • Easily report events / pageviews / performance values
    • Written in plain javascript, i.e. ReactJs, Angular, Vue or anything else that can run JS

    Live demo

    Play with our live demo

    Edit live demo

    Edit @impervaos/google-analytics-spa

    Installation

    Install the package

    npm i @impervaos/google-analytics-spa 

    Configuration and Initialization

    Add the following snippet in your index.html (or whatever page that is loaded first)***

        <!-- Google Analytics -->
        <script>
            window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
        </script>
        <script defer src='https://www.google-analytics.com/analytics.js'></script>
        <!-- End Google Analytics -->

    Add the following in your first JSX / JS file (the root of your SPA application)

    /* eslint-disable */
    import { googleAnalyticsInit } from '@impervaos/google-analytics-spa';
    import { createBrowserHistory } from 'history';
    
    //[OPTIONAL] You dont have to use the 'history' package
    // However if you do, page navigation would be traced and reported to GA automatically
    const history = createBrowserHistory({ basename: '' });
    
    //This is your GA application id.
    //from https://analytics.google.com/analytics/web/#/.../admin/property/settings (your GA property page)
    const myGaApplicationId = 'UA-XXXXXXX-XX';
    //[OPTIONAL] The name of your tracker, in case you will be using multiple trackers
    const myTrackerName = 'MyTrackerName';
    //--------------------
    //performance reporting configuration
    // it can be either regex - and then only the requests whos urls can be matched using this regex will be reported
    //for example: if my backend requests go to http://some.com/api/v1/getMyData we would set this parameter to /.*api\/v1/
    // OR it can be an object {include: {regex}, initi: [{string}...{string}], category: {function}}
    //  *          See types here: https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/initiatorType
    
    const performanceRegex = {include: /.*my_api.*/i, initiatorTypes: ['xmlhttprequest','fetch'], category: e => e.name.replace('.','_')};
    
    //every request will also piggyback these dimensions with it
    //For example: user email or any other custom dimension that you need to better track your application usage
    //read more here https://support.google.com/analytics/answer/2709829?hl=en
    const customDimensions = {
        dimension1: MyUserDetails.email,
        dimension2: MyUserSession.id,
        dimension3: Date.now(), //example: session start timestamp
    };
    //[OPTIONAL] In case you would like to track your users using "GA User explorer" you need to provide GA
    // with a unique identifier per user.
    // If you would not provide this identifier, google will generate a random id
    //GA tracker properties (https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference)
    const properties = { userId: MyUserDetails.id }; //example reporting userId
    
    googleAnalyticsInit( myGaApplicationId,
        myTrackerName,
        history,
        performanceRegex,
        properties,
        customDimensions
    );

    ***I decided not to embed the ga.js code, since google promissed to change it unexpectedly

    Usage

    /* eslint-disable */
    import { tracker } from '@impervaos/google-analytics-spa';
    
    function myComplicatedAction() {
        try {
            performSomeComplicatedAction();
        } catch(e) {
            //in case of an error we report it to google analytics
            tracker().reportException(e.message, false);
            return;
        }
    
        tracker().reportEvent( 'MY_CATEGORY', 'MY_ACTION_PERFORMED', 'my_label_text', 0 );
    }
    
    //manual page view reporting (i.e. reporting that navigation was done to page http://page.com/first)
    tracker().reportPage( 'my site title', 'http://page.com/first' );
    
    //navigating to another page in the application
    // @impervaos/google-analytics-spa will report navigation to page called '/virtual/path' automatically instead of reporting navigation to '/test/path'
    history.push( '/test/path', gaBuildPageViewState( 'TITLE', '/virtual/path', true ) );

    Usage with Redux

    import {reportGoogleAnalytics, GaReportingReduxMiddleware} from '@impervaos/google-analytics-spa';
    const store = createStore(state => state, applyMiddleware(GaReportingReduxMiddleware));
    
    //In order to use this annotation your code need to be able to process annotations
    //So you might want to use something like https://babeljs.io/docs/en/babel-plugin-proposal-decorators
    //In the future the decorators will be part of ES
    
    class ReduxActions {
        @reportGoogleAnalytics('MyCategory', null, 'my label', 1)
        static doSomethingWithAnnotation() {
            return {
                type: 'DO_SOMETHING'
            };
        } 
    
       static doSomething() {
            return {
                type: 'DO_SOMETHING_ELSE'
            };
        }
    }
    //When this event is dispatched, an automatic even report will be sent to Google Analytics
    //equal to: tracker().reportEvent('MyCategory','DO_SOMETHING', 'my label', 1); 
    store.dispatch(ReduxActions.doSomethingWithAnnotation());
    
    //When this event is dispatched, an automatic even report still being sent to Google Analytics
    //equal to: tracker().reportEvent('','DO_SOMETHING_ELSE', '', 0); 
    store.dispatch(ReduxActions.doSomething());

    API

    reportEvent

    Kind: global instance method of tracker()
    Summary: Reporting an event performed
    Access: public
    Params

    • category string - event category
    • action string - event name
    • label string - label of the event
    • value number - how much this event worth (usually in USD)

    GaTracker

    Kind: global class
    Access: public


    ############## gaTracker.setCustomDimension Kind: instance instance method of tracker() of GaTracker
    Summary: sets a custom dimension on the fly. Read more here: https://developers.google.com/analytics/devguides/collection/analyticsjs/custom-dims-mets
    Access: public
    Params

    • dimensionId number - integer > 1 - maxMetrics allowed (usually 20)
    • value any - value to be set inside dimension

    ############## gaTracker.setCustomMetric Kind: instance instance method of tracker() of GaTracker
    Summary: sets a custom metric on the fly. Read more here: https://developers.google.com/analytics/devguides/collection/analyticsjs/custom-dims-mets
    Access: public
    Params

    • metricId number - integer > 1 - maxMetrics allowed (usually 20)
    • value any - value to be set inside metric

    ############## gaTracker.setUserId(identifier) Kind: instance method of GaTracker
    Summary: (Usually should not be used) Manually set user id (might be overriden by next requests)
    Access: public
    Params

    • identifier string - identifier that is used to identify this specific user across multiple sessions and / or devices

    ############## gaTracker.reportLastRequestDuration(category, requestUrl, label) Not required by default

    Kind: instance method of GaTracker
    Summary: Manually report the duration of last sent request
    duration = request initiation until last byte receipt
    Access: public
    Params

    • category string - perofmance event category
    • requestUrl string - url of the request we want to report.
      In case of multiple requests with this url, only the last one will be reported
    • label string - the label of your liking for this request

    ############## gaTracker.reportLastRequestWait(category, requestUrl, label) Not required by default

    Kind: instance method of GaTracker
    Summary: Reports the server waiting time until download starts
    Access: public
    Params

    • category string
    • requestUrl string
    • label string

    ############## gaTracker.reportLastRequestDownloadTime(category, requestUrl, label) Not required by default

    Kind: instance method of GaTracker
    Summary: Reports the resource download time
    Access: public
    Params

    • category string
    • requestUrl string
    • label string

    ############## gaTracker.reportPage(title, page) Not required by default, if you are using 'history' package

    Kind: instance method of GaTracker
    Access: public
    Params

    • title string - reported page title
    • page string - page url

    ############## gaTracker.reportException(exDescription, isFatal) Kind: instance method of GaTracker
    Summary: Reporting a code exception to GA
    Access: public
    Params

    • exDescription string - what happened
    • isFatal boolean - was the exception fatal to your code or not

    googleAnalyticsInit(trackerId, trackerName, [history], [performanceConfig], [gaProperties], [gaDimensions]) ⇒ GaTracker

    Kind: global function
    Summary: Run this function as soon as possible in your code in order to initialize google analytics reporting
    Returns: GaTracker - pointer to the singleton object through which reporting is made
    Access: public
    Params

    • trackerId string - Id of your app defined in your Google analytics account.
      Looks like this UA-XXXXXXXX-XX
    • trackerName string - a name to represent a GA tracker.
      Useful if you want to have 2 separate GA trackers.
      Can be any string.
    • [history] Object - history object.
      We advice to use https://www.npmjs.com/package/history package.
      If not provided, automatic reporting of pages navigation will not work
    • [performanceConfig] RegExp | Object | String - automatic performance tracking purposes. (default = /.*/)


    regex string - urls to be reported should match this regex
    object - type PerformanceConfig
    null - performance reporting is disabled


    gaBuildPageViewState(title, virtualPath, isVirtualPathOnly) ⇒ Object

    Kind: global function
    Access: public
    Params

    • title string - reported page title
    • virtualPath string - the virtual path
    • isVirtualPathOnly boolean -
      true - the virtual page will be appended to the actual path,
      false - will replace the path completely with virtualPath

    PerformanceConfig : Object

    Configuration object used in googleAnalyticsInit function

    Kind: global typedef
    Version: 1.1.0
    Properties

    • include string - Only requests who's URL match this regex would be reported.
    • initiatorTypes [ 'Array' ].<string> - Only requests who's type matches this strings would be reported.
    • category function - The result of this function will be sent as category of timing event

    Contributing

    node ver

    Building requires node v12 and higher

    Pull requests are welcome.

    For major changes, please open an issue first to discuss what you would like to change.

    Please make sure to update tests as appropriate.

    License

    MIT License

    Copyright (c) 2018 Imperva

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Install

    npm i @impervaos/google-analytics-spa

    DownloadsWeekly Downloads

    27

    Version

    1.4.1

    License

    MIT

    Unpacked Size

    211 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar
    • avatar