@analytics/fullstory

FullStory plugin for 'analytics' module

Usage no npm install needed!

<script type="module">
  import analyticsFullstory from 'https://cdn.skypack.dev/@analytics/fullstory';
</script>

README

FullStory plugin for analytics

Integration with FullStory for analytics

FullStory is a tool that tracks user behavior in your application. User sessions are recorded and can be played back allowing developers and product owners to identify areas for improvement in their software.

This analytics plugin will add the FullStory javascript library to your app & send custom events into FullStory.

View the docs

Click to expand

Installation

Install analytics and @analytics/fullstory packages

npm install analytics
npm install @analytics/fullstory

You will need your org ID from FullStory setting to connect to your account and initialize analytics.

To find your FullStory account's org ID go to Settings > FullStory Setup. and grab the _fs_org value.

How to use

The @analytics/fullstory 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 fullStoryPlugin from '@analytics/fullstory'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    fullStoryPlugin({
      org: 'your-org-name'
    })
  ]
})

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

/* Identify a visitor */
analytics.identify('user-id-xyz', {
  firstName: 'bill',
  lastName: 'murray'
})

After initializing analytics with the fullStoryPlugin plugin, data will be sent into FullStory whenever analytics.identify, or analytics.track are called.

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

Platforms Supported

The @analytics/fullstory package works in the browser

Browser usage

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

Browser API

import Analytics from 'analytics'
import fullStoryPlugin from '@analytics/fullstory'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    fullStoryPlugin({
      org: 'your-org-name'
    })
  ]
})

Configuration options for browser

Option description
org
required - string
FullStory account's org ID. The _fs_org value in settings.

Additional examples

Below are additional implementation examples.

Using in HTML

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/fullstory in HTML</title>
    <script src="https://unpkg.com/analytics/dist/analytics.min.js"></script>
    <script src="https://unpkg.com/@analytics/fullstory/dist/@analytics/fullstory.min.js"></script>
    <script type="text/javascript">
      /* Initialize analytics */
      var Analytics = _analytics.init({
        app: 'my-app-name',
        plugins: [
          analyticsFullStory({
            org: 'your-org-name'
          })
        ]
      })

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

      /* Identify a visitor */
      analytics.identify('user-id-xyz', {
        firstName: 'bill',
        lastName: 'murray'
      })
    </script>
  </head>
  <body>
    ....
  </body>
</html>

Using in HTML via ES Modules

Using @analytics/fullstory in ESM modules.

<!DOCTYPE html>
<html>
  <head>
    <title>Using @analytics/fullstory 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 analyticsFullStory from 'https://unpkg.com/@analytics/fullstory/lib/analytics-plugin-fullstory.browser.es.js?module'
      /* Initialize analytics */
      const Analytics = analytics({
        app: 'analytics-html-demo',
        debug: true,
        plugins: [
          analyticsFullStory({
            org: 'your-org-name'
          })
          // ... add any other third party analytics plugins
        ]
      })

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

      /* Identify a visitor */
      analytics.identify('user-id-xyz', {
        firstName: 'bill',
        lastName: 'murray'
      })
    </script>
  </head>
  <body>
    ....
  </body>
</html>

Formatting payloads

Full story requires specific naming conventions for tracking.

We have taken the liberty of making this easier to use with this plugin. 🎉

Values sent to Full Story will be automatically converted into a values their API will understand.

Example

analytics.track('itemPurchased', {
  price: 11.11,
  is_user: true,
  first_name: 'steve'
})

This tracking payload will be automatically converted to the fullstory naming conventions and will be sent like:

FS.event('itemPurchased', {
  price_real: 11.11,
  isUser_bool: true,
  firstName_str: 'steve'
})

This will ensure data flows into full story correctly.