nuǝW pǝuoᴉʇᴉsoԀ ʎlǝʌᴉʇɐƃǝN

    analytics-plugin-tab-events

    0.2.1 • Public • Published

    Analytics Tab Events Plugin

    This analytics plugin fire events on tab visibility changes. When visitors switch between browser tabs callbacks are fired.

    Tab visibility changes can be useful for session information, pausing videos/carousels, and displaying calls to action when a visitor returns to a tab.

    The plugin exposes tab events (tabHidden and tabVisible) that listeners & other plugins can react to.

    This package comes with a standalone onTabChange function for usage anywhere in your app.

    How to use

    Install from npm.

    npm install analytics
    npm install analytics-plugin-tab-events

    Then initialize analytics with the plugin.

    import Analytics from 'analytics'
    import tabEventsPlugin from 'analytics-plugin-tab-events'
    
    const analytics = Analytics({
      app: 'my-app',
      plugins: [
        /* Include tab events plugin */
        tabEventsPlugin,
        // ...other plugins
      ]
    })
    
    // expose analytics instance for your app to use
    export default analytics

    Reacting from listeners

    You can listen to the tabHidden & tabVisible events with .on & .once listeners directly in your app code.

    /* import analytic instance in your app code */
    import analytics from '/src/analytics'
    
    // Somewhere in your app
    
    /* Or fire .on listeners */
    analytics.on('tabHidden', () => {
      // do stuff when tab hidden
    })
    analytics.on('tabVisible', () => {
      // do stuff when tab visible
    })
    
    /* Or fire listeners just once */
    analytics.once('tabHidden', () => {
      // do stuff ONCE when tab hidden
    })
    analytics.once('tabVisible', () => {
      // do stuff ONCE when tab visible
    })
    
    /* Clean up events */
    const remove = analytics.on('tabHidden', () => {/* logic */})
    // Call remove() to detach listener
    remove()

    Reacting from a plugin

    Instead of listening inline with .on or .once, you can create plugins to also react to tabHidden and tabVisible events.

    This keeps your app code nice an clean & centralizes functionality where your analytics instance is initialized.

    Here is an example:

    import Analytics from 'analytics'
    import tabEventsPlugin from 'analytics-plugin-tab-events'
    
    let tabInterval
    /* Example plugin that listener to tab events */
    const customPluginExample = {
      NAMESPACE: 'custom-plugin-with-tab-listeners',
      tabHidden: () => {
        console.log('Tab is now hidden')
        let tabHiddenCount = 0
        tabInterval = setInterval(() => {
          console.log(`tab counter ${tabHiddenCount++}`)
        }, 500)
      },
      tabVisible: () => {
        console.log('Tab now visible again')
        clearInterval(tabInterval)
      },
    }
    
    const analytics = Analytics({
      app: 'my-app',
      plugins: [
        /* Include tab events plugin */
        tabEventsPlugin,
        /* Example plugin that listener to tab events */
        customPluginExample,
      ]
    })

    Using onTabChange

    This standalone onTabChange function can imported and used by itself, without the plugin being attached to analytics, anywhere in your application logic.

    import { onTabChange } from 'analytics-plugin-tab-events'
    
    const myListener = onTabChange((isHidden) => {
      if (isHidden) {
        console.log('Tab is not visible')
      } else {
        console.log('Welcome back tab is visible')
      }
    })
    
    // Optionally remove the listener
    myListener()

    Install

    npm i analytics-plugin-tab-events

    DownloadsWeekly Downloads

    1,139

    Version

    0.2.1

    License

    MIT

    Unpacked Size

    69.4 kB

    Total Files

    11

    Last publish

    Collaborators

    • davidwells