0.4.0 • Published 1 year ago

@analytics/simple-analytics v0.4.0

Weekly downloads
12
License
MIT
Repository
-
Last release
1 year ago

Simple Analytics Plugin

Integration with simple analytics Simple Analytics

The simple analytics plugin automatically tracks page views on route changes for single page applications.

For more information see the docs.

Installation

npm install analytics
npm install @analytics/simple-analytics

How to use

The @analytics/simple-analytics package works in the browser. To use, install the package, include in your project and initialize the plugin with analytics.

Below is an example of how to use the browser plugin.

import Analytics from 'analytics'
import simpleAnalyticsPlugin from '@analytics/simple-analytics'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [simpleAnalyticsPlugin()]
})

/* Track a custom event */
analytics.track('cartCheckout', {
  item: 'pink socks',
  price: 20
})

After initializing analytics with the simpleAnalyticsPlugin plugin, data will be sent into Simple Analytics whenever or analytics.track are called.

See additional implementation examples for more details on using in your project.

Platforms Supported

The @analytics/simple-analytics package works in the browser

Browser usage

The Simple Analytics client side browser plugin works with these analytic api methods:

Browser API

import Analytics from 'analytics'
import simpleAnalyticsPlugin from '@analytics/simple-analytics'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [simpleAnalyticsPlugin()]
})

Configuration options for browser

Optiondescription
customDomain optional - stringCustom domain for simple analytics script. https://docs.simpleanalytics.com/script
hostname optional - stringAllow overwriting domain name https://docs.simpleanalytics.com/overwrite-domain-name
collectDnt optional - booleanAllow collecting DNT visitors https://docs.simpleanalytics.com/dnt
mode optional - stringAllow hash mode https://docs.simpleanalytics.com/hash-mode
ignorePages optional - stringAdd ignore pages https://docs.simpleanalytics.com/ignore-pages
saGlobal optional - stringOverwrite SA global for events https://docs.simpleanalytics.com/events#the-variable-sa_event-is-already-used
autoCollect optional - booleanOverwrite SA global for events https://docs.simpleanalytics.com/trigger-custom-page-views#use-custom-collection-anyway
onloadCallback optional - stringAllow onload callback https://docs.simpleanalytics.com/trigger-custom-page-views#use-custom-collection-anyway

Additional examples

Below are additional implementation examples.

Below is an example of importing via the unpkg CDN. Please note this will pull in the latest version of the package.

<!DOCTYPE html>
<html>
  <head>
    <title>Using @analytics/simple-analytics in HTML</title>
    <script src="https://unpkg.com/analytics/dist/analytics.min.js"></script>
    <script src="https://unpkg.com/@analytics/simple-analytics/dist/@analytics/simple-analytics.min.js"></script>
    <script type="text/javascript">
      /* Initialize analytics */
      var Analytics = _analytics.init({
        app: 'my-app-name',
        plugins: [simpleAnalytics()]
      })

      /* Track a custom event */
      analytics.track('cartCheckout', {
        item: 'pink socks',
        price: 20
      })
    </script>
  </head>
  <body>
    ....
  </body>
</html>

Using @analytics/simple-analytics in ESM modules.

<!DOCTYPE html>
<html>
  <head>
    <title>Using @analytics/simple-analytics in HTML via ESModules</title>
    <script>
      // Polyfill process.
      // **Note**: Because `import`s are hoisted, we need a separate, prior <script> block.
      window.process = window.process || { env: { NODE_ENV: 'production' } }
    </script>
    <script type="module">
      import analytics from 'https://unpkg.com/analytics/lib/analytics.browser.es.js?module'
      import simpleAnalytics from 'https://unpkg.com/@analytics/simple-analytics/lib/analytics-plugin-simple-analytics.browser.es.js?module'
      /* Initialize analytics */
      const Analytics = analytics({
        app: 'analytics-html-demo',
        debug: true,
        plugins: [
          simpleAnalytics()
          // ... add any other third party analytics plugins
        ]
      })

      /* Track a custom event */
      analytics.track('cartCheckout', {
        item: 'pink socks',
        price: 20
      })
    </script>
  </head>
  <body>
    ....
  </body>
</html>