@keymetrics/vue-multianalytics

    1.9.9 • Public • Published

    Vue-multianalytics

    A VueJS multianalytics tool

    About

    At Glovo we need to track a lot of events. And not in only one platform, but a few. That is why we needed vue-multianalytics, a simple plugin that allows you to track any event in multiple platforms at the same time.

    This plugin has been inspired by the awesome library vue-ua, so a big thank you to it. If you want to just have Google Analytics, you should use vue-ua instead of vue-multianalytics.

    Configuration

    A typical npm install vue-multianalytics -s will be enough to download it.

    To start using it, you need to add the plugin in your main .js entry

    import VueMultianalytics from 'vue-multianalytics'
     
    let gaConfig = {
      appName: 'Test', // Mandatory
      appVersion: '0.1', // Mandatory
      trackingId: 'YOUR_UA', // Mandatory
      debug: true, // Whether or not display console logs debugs (optional)
    }
     
    let mixpanelConfig = {
      token: 'YOUR_TOKEN'
    }
     
     
    Vue.use(VueMultianalytics, {
      modules: {
        ga: gaConfig,
        mixpanel: mixpanelConfig
      }
    })

    Tracking

    Once the configuration is completed, you can access the vue-multianalytics instance in your components like that :

    this.$ma.trackEvent(params, excludedModules)

    ExcludedModules

    You can easily exclude modules from being fired by an event adding them to the excludedModules array. This is per-event based, so feel free to use them as you want

    // this will exclude mixpanel from being fired
    let excludedModules = ['mixpanel']
    this.$ma.trackEvent(params, excludedModules)
     
    // this will exclude both, mixpanel and ga from beign fired
    this.$ma.trackEvent(params, ['mixpanel', 'ga'])
     
    // this will exclude nothing from beign fired, all the modules will be triggered
    this.$ma.trackEvent(params)

    VueRouter integration

    vue-multianalytics can be integrated with vue-router to track each new screen view on router change.

    To use this feature, you just need to pass your vue-router instance in the params property as vueRouter.

     
    import VueMultianalytics from 'vue-multianalytics'
    import VueRouter from 'vue-router'
    const router = new VueRouter(...)
     
    let mixpanelConfig = {
      token: 'YOUR_TOKEN'
    }
     
    Vue.use(VueMultianalytics, {
      modules: {
        mixpanel: mixpanelConfig
      },
      routing: {
        vueRouter: router, //  Pass the router instance to automatically sync with router (optional)
        preferredProperty: 'name', // By default 'path' and related with vueRouter (optional)
        ignoredViews: ['homepage'], // Views that will not be tracked
        ignoredModules: ['ga'] // Modules that will not send route change events. The event sent will be this.$ma.trackView({viewName: 'homepage'}, ['ga'])
      }
    })
     

    This feature will generate the view name according to a priority rule:

    • If you have defined a meta field in your route named analytics
    const homeRoute = {
      path: '/home',
      name: 'home',
      meta: {analytics: 'ThisWillBeTheName'}
    }
    • If you define a preferredProperty in your vue-multianalytics params, that params will be the used as screen name. Possible params are: name, path, fullPath.
    • If nothing is provided path will be used.

    If you want to ignore some routes, just specify then in the ignoredViews param.

    Custom Plugin

    Usually you don't want to call directly the library, but call an interface first to manipulate the data before.

    // Not a very good practice
     
    //component1
    if (=== condition1) {
      this.$ma.trackEvent({action: 'User click'})
    } else {
      this.$ma.trackError({description: 'Fatal error'})
    }
     
    //component2
    if (=== condition1) {
      this.$ma.trackEvent({action: 'User click'})
    }
     
    // Much better using an interface and handle the logic there. No code repeated, better understanding of the flow
     
    // component1
    this.$mam.onUserClick(a)
    // componen2
    this.$mam.onUserClick(b)

    To do it so, you just need to create a mixin to act as an interface with the vue-multianalytics.

    Mixin

    Just create a module that exports a function accepting as a parameter the analytics library:

    export default function (multianalytics) {
     
      return {
        onUserClick (input) {
          if (input === true) {
            multianalytics.trackEvent({action: 'User click'})
          } else {
            multianalytics.trackError({description: 'Fatal error'})
          }
        }
      }
    }

    You can define inside all the methods that you want and call all the library api from the parameter received.

    Binding

    You just need to pass the mixin as the third parameter when you initialize the plugin

    import VueMultianalytics from 'vue-multianalytics'
    import analyticsMixin from './analyticsMixin.js'
     
    Vue.use(VueMultianalytics, {
      modules: {
        ga: gaConfig
      }
    }, analyticsMixin)

    Usage

    Everything is already set, you can now call your mixin methods from anywhere in your vue application using this.$mam (instead of this.$ma).

    //Component1
    export default {
      data () {
     
      },
      methods: {
        bannerClick (input) {
          this.$mam.onUserClick(input)
        }
      }
    }

    API

    trackView({viewName})

    /**
      * Dispatch a view using the screen name
      * params should contain
      * @param viewName
      */
     
    this.$ma.trackView({screenName: 'Homepage'})  

    trackEvent({category = 'Event', action, label = null, value = null})

    /**
      * Dispatch a view using the screen name
      * params object should contain
      *
      * @param category
      * @param action
      * @param label
      * @param value
      */
     
    this.$ma.trackEvent({category: 'Click', action: 'Homepage Click', label: 'Great', value: ''})  

    addTransaction({id, affiliation = '', revenue = 0, shipping = 0, tax = 0, currency = 'USD'})

    /**
    * Ecommerce transactions.
    * ecommerce needs to be enabled in the module options (ecommerce = true)
    * More info at https://developers.google.com/analytics/devguides/collection/analyticsjs/ecommerce
    @param {long} id - Transaction ID. Required
    @param {string} affiliation -  Affiliation or store name
    @param {float} revenue - Grand Total
    @param {flat} shipping -  Shipping
    @param {float} tax - Tax
    @param {string} currency - Currency - https://developers.google.com/analytics/devguides/platform/features/currencies
    */
    this.$ma.addTransaction({
      id: 1234,                     // Transaction ID. Required.
      affiliation: 'Acme Clothing',   // Affiliation or store name.
      revenue: 11.99,               // Grand Total.
      shipping: 5,                  // Shipping.
      tax: 1.29                     // Tax.
    })

    addItem({id, name, sku, category, price = 0, quantity = 1})

    /**
    * Ecommerce transactions.
    * ecommerce needs to be enabled in the module options (ecommerce = true)
    * More info at https://developers.google.com/analytics/devguides/collection/analyticsjs/ecommerce
    @param {long} id - Transaction ID. Required
    @param {string} name -  Product name. Required.
    @param {string} sku - SKU/code.
    @param {string} category -  Category or variation.
    @param {float} price - Unit price.
    */
    this.$ma.addItem({
      id: 123,
      name: 'Fluffy Pink Bunnies',    // Product name. Required.
      sku: 'DD23444',                 // SKU/code.
      category: 'Party Toys',         // Category or variation.
      price: '11.99',                 // Unit price.
      quantity: '1'  
    })

    trackTransaction()

    /**
    * Ecommerce transactions.
    * ecommerce needs to be enabled in the module options (ecommerce = true)
    * Sends the transaction
    */
    this.$ma.trackTransaction()

    clearTransactions()

    /**
    * Ecommerce transactions.
    * ecommerce needs to be enabled in the module options (ecommerce = true)
    * Clears the transaction
    */
    this.$ma.clearTransactions()

    identify()

    /**
      * Identify
      *
      * @param userId - The userId to identify with
      * @param options -
      */
     
    this.$ma.identify({userId: 12345, options: {newUser: true}})  

    reset()

    /**
      * Reset the user & clears storage
      *
      */
     
    this.$ma.reset()  

    setAlias(alias)

    /**
      * Set an alias
      *
      * @param alias
      */
     
    this.$ma.setAlias('user1234@test.com')  

    setUsername(name)

    /**
      * Set a username
      *
      * @param name
      */
     
    this.$ma.setUsername('user1234@test.com')  

    setUserProperties(properties)

    /**
      * Set some user properties
      *
      * @param properties
      */
     
    this.$ma.setUserProperties({userId: '12345', name: 'John'})  

    setUserPropertiesOnce(properties)

    /**
      * Set some user properties, but only once
      *
      * @param properties
      */
     
    this.$ma.setUserPropertiesOnce({userId: '12345', name: 'John'})  

    incrementUserProperties(properties)

    /**
      * Increment some user properties
      *
      * @param properties
      */
     
    this.$ma.incrementUserProperties({loginCount: 1, pagesPrinted: 5})

    setSuperProperties(properties)

    /**
      * Set some properties to be sent in every event
      *
      * @param properties
      */
     
    this.$ma.setSuperProperties({platform: 'Mobile'})  

    setSuperPropertiesOnce(properties)

    /**
      * Set some properties to be sent in every event
      *
      * @param properties
      */
     
    this.$ma.setSuperPropertiesOnce({platform: 'Mobile'})  

    Modules

    Currently, supported modules are the following

    Google Analytics

    Name: ga Config:

    appName: 'Test', // Mandatory
    appVersion: '0.1', // Mandatory
    trackingId: 'YOUR_UA', // Mandatory
    ecommerce: true, // Enables ecommerce support (optional)
    debug: true // Whether or not display console logs debugs (optional)

    Supported Events: trackView, trackEvent, trackException, addTransaction, addItem, trackTransaction, clearTransactions, setUsername, trackTiming

    Mixpanel

    Name: mixpanel Config:

    token: 'YOUR_TOKEN'
    config: {} // Initial mixpanel config
    debug: true // Whether or not display console logs debugs (optional)

    Supported Events: trackView, trackEvent, setAlias, setUsername, setUserProperties, setUserPropertiesOnce, incrementUserProperties, setSuperPropertiesOnce, setSuperProperties, setSuperPropertiesOnce

    Facebook Pixel

    Name: facebook Config:

    token: 'YOUR_TOKEN'
    debug: true // Whether or not display console logs debugs (optional)

    Supported Events: trackView, trackEvent

    Segment

    Name: segment Config:

    token: 'YOUR_TOKEN'
    debug: true // Whether or not display console logs debugs (optional)

    Supported Events: trackView, trackEvent, setAlias, setUserProperties, setSuperProperties

    MParticle

    Name: mparticle Config:

    token: 'YOUR_TOKEN'
    debug: true // Whether or not display console logs debugs (optional)

    Supported Events: trackView, trackEvent, setAlias, setUserProperties, setSuperProperties

    Custom Modules

    You can now add your own custom modules simply by calling VueMultianalytics.addCustomModule(name, Module)

    Example:

    // OwnModule.js
    class OwnModule extends BasicModule {
      init() {
        // ...
      }
     
      trackView ({viewName}) {
        if (this.config.debug) {
          logDebug(viewName)
        }
        myowntrack("Page Viewed", { "page": viewName })
      }
     
      // ..  
    }
    // main.js
    import Vue from 'vue'
    import VueMultianalytics from 'vue-multianalytics'
    import OwnModule from 'OwnModule.js'
     
    VueMultianalytics.addCustomModule('ownModule', OwnModule)
    // or VueMultianalytics.use('owenit', OwenItModule)
     
    Vue.use(VueMultianalytics, {
      modules: {
       ownModule: { /* module config */ }
      }
    })

    Thanks @anteriovieira for the suggestion

    Todo

    • Demo 👍
    • Further integration with mixpanel 👍
    • Ecommerce support 👍
    • Own module 👍
    • New events: registerSuperproperties, alias, timedEvents
    • New modules: segment, mparticle appboy, kissmetrics?
    • Tests

    License

    MIT

    Install

    npm i @keymetrics/vue-multianalytics

    DownloadsWeekly Downloads

    17

    Version

    1.9.9

    License

    MIT

    Unpacked Size

    1.17 MB

    Total Files

    31

    Last publish

    Collaborators

    • envision-dashboard
    • keymetrics_bot
    • tknew