search

fullstorydev / fullstory-browser-sdk

Official FullStory SDK for JavaScript, for web browsers
MIT License
55 stars 17 forks source link

readme

Fullstory Browser SDK

CircleCI npm (scoped)

Fullstory's browser SDK lets you manage Fullstory data capture on your site as well as retrieve deep links to session replays and send your own custom events. More information about the Fullstory API can be found at https://developer.fullstory.com.

NOTE: this is the documentation for version 2. For version 1 documentation, please see @fullstory/browser@1.7.1.

Install the SDK

with npm

npm i @fullstory/browser --save

with yarn

yarn add @fullstory/browser

Migrating to Version 2.x.x

In version 2.x.x, init is a separate named export from FullStory. You will need to update all of your wildcard ('*') imports to explicit named imports.

Version 1.x.x

import * as FullStory from '@fullstory/browser';

Version 2.x.x

import { FullStory, init } from '@fullstory/browser';

init

You can use the named import init by itself:

import { init } from '@fullstory/browser';

init({ orgId: 'my-org-id' })

You can also rename the function for readability:

import { init as initFullStory } from '@fullstory/browser';

initFullStory({ orgId: 'my-org-id' })

FullStory

The FullStory named export is equivalent to the global FS object described in the developer documentation. You can use it to make all version 2 API calls:

import { FullStory } from '@fullstory/browser';

FullStory('trackEvent', {
  name: 'My Event',
  properties: {
    product: 'Sprockets',
    quantity: 1,
  },
})

Initialize the SDK

Call the init() function with options as soon as you can in your website startup process. Calling init after successful initialization will trigger console warnings - if you need to programmatically check if FullStory has been initialized at some point in your code, you can call isInitialized().

Configuration Options

The only required option is orgId, all others are optional.

Ready Callback

The init function also accepts an optional readyCallback argument. If you provide a function, it will be invoked when the Fullstory session has started. Your callback will be called with one parameter: an object containing information about the session. Currently the only property is sessionUrl, which is a string containing the URL to the session.

import { init } from '@fullstory/browser';

init({ orgId }, ({ sessionUrl }) => console.log(`Started session: ${sessionUrl}`));

Initialization Examples

React

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import { init as initFullStory } from '@fullstory/browser';

initFullStory({ orgId: '<your org id here>' });

ReactDOM.render(<App />, document.getElementById('root'));

Angular with devMode enabled

import { Component } from '@angular/core';
import { init as initFullStory } from '@fullstory/browser';
import { environment } from '../environments/environment';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {

  constructor() {
    initFullStory({
      orgId: '<your org id here>',
      devMode: !environment.production,
    });
  }
}

Vue

import Vue from 'vue';
import App from './App.vue';
import { init as initFullStory, FullStory } from '@fullstory/browser';

initFullStory({ orgId: '<your org id here>' });
Vue.prototype.$FullStory = FullStory;

new Vue({
  render: h => h(App)
}).$mount('#app');

Vue 3

import { createApp } from 'vue';
import App from './App.vue';
import { init as initFullStory, FullStory } from '@fullstory/browser';

initFullStory({ orgId: '<your org id here>' });

const app = createApp(App);
app.config.globalProperties.$FullStory = FullStory;
app.mount('#app');

Using the SDK

Once FullStory is initialized, you can make calls to the FullStory SDK. See the developer documentation for more information.

Sending custom events

FullStory('trackEvent', {
  name: 'Subscribed',
  properties: {
    uid: '750948353',
    plan_name: 'Professional',
    plan_price: 299,
    plan_users: 10,
    days_in_trial: 42,
    feature_packs: ['MAPS', 'DEV', 'DATA'],
  },
  schema: {
    properties: {
      plan_users: 'int', // override default inferred "real" type with "int"
      days_in_trial: 'int', // override default inferred "real" type with "int"
    }
  }
});

NOTE: The inclusion of type suffixes - appending _str or _int to the end of properties - is no longer required. All custom properties are inferred on the server. To override any default inference, you can add a schema. See Custom Properties for more information.

Generating session replay links

const startOfPlayback = FullStory('getSession');
const playbackAtThisMomentInTime = FullStory('getSession', { format: 'url.now' });

Sending custom user properties

FullStory('setProperties', {
  type: 'user',
  properties: {
    displayName: 'Daniel Falko',
    email: 'daniel.falko@example.com',
    pricing_plan: 'free',
    popup_help: true,
    total_spent: 14.50,
  },
});

For more information on sending custom user properties, view the Fullstory help article on Capturing custom user properties.

Sending custom page properties

FullStory('setProperties', {
  type: 'page',
  properties: {
    pageName: 'Checkout', // what is the name of the page?
    cart_size: 10, // how many items were in the cart?
    used_coupon: true, // was a coupon used?
  },
  schema: {
    properties: {
      cart_size: 'int', // override default inferred "real" type with "int"
    }
  }
});

For more information on setting page properties, view the Fullstory help article on Sending custom page data to Fullstory.