@commercetools-frontend/fullstory

This is a package used internally for Merchant Center applications. We do not provide any guarantees or support for the functionality.

This package provides an easy to use integration with FullStory. The official documentation of FullStory's SDK can be found here.

Installation

$ npm install --save @commercetools-frontend/fullstory

Usage

Initialization

At first you will need to initialize FullStory and its SDK

You need to add this before you render your application's entry point with for instance ReactDOM.render:

Configuration via a Custom Application configuration

If you are developing a Custom Application for the Merchant Center we recommend you to add a FULLSTORY_ORGANIZATION_ID as a value to the environment.

This environment variable should then we exposed via the additionalEnv and a fullstoryOrganizationId property in your Custom Application's configuration.

additionalEnv: {
    fullstoryOrganizationId: '${env:FULLSTORY_ORGANIZATION_ID}',
},

Given that you can just initialize FullStory like this:

import { initialize as initializeFullStory } from '@commercetools-frontend/fullstory';

initializeFullStory();

In order for the SDK to be able to connect with FullStory's APIs you have to extend the headers.csp property of your Custom Application config to contain the following properties:

import { CONTENT_SECURITY_POLICIES as FULLSTORY_CONTENT_SECURITY_POLICIES } from '@commercetools-frontend/fullstory/constants';

headers: {
    csp: {
        'connect-src': [...FULLSTORY_CONTENT_SECURITY_POLICIES.CONNECT_SRC],
        'script-src': [...FULLSTORY_CONTENT_SECURITY_POLICIES.SCRIPT_SRC],
    },
},

Configuration without Custom Application configuration

If you are not building a Custom Application or prefer not to configure FullStory using the Custom Application's configuration you can pass the organization ID of FullStory as an argument like this:

import { initialize as initializeFullStory } from '@commercetools-frontend/fullstory';

initializeFullStory('myFullStoryOrgId');

Please also make sure that the connect-src and script-src Content Security Policies allow FullStory to connect with their services. If needed you can use the provided constants from @commercetools-frontend/fullstory/constants exported as CONTENT_SECURITY_POLICIES.

Setting up the tracking effect

As a last step for any case above you have to use the useTrackingEffect in the entry point of your application. Make sure that it is rendered below the ApplicationShell component as it depends on its React context.

import { useTrackingEffect as useFullStoryTrackingEffect } from '@commercetools-frontend/fullstory';

function EntryPoint() {
    useFullStoryTrackingEffect();

    return <>
        <Application>
    </>
}

1. If you intend to send additional user variables you can pass them using the additionalUserVars object
2. If you intend to disable FullStory entirely (e.g. based on a feature flag), use the disable flag
   • Note that you can only disable until you initialized once.

Custom events

Domain-specific events recorded by FullStory add additional intelligence when you're searching across sessions and creating new user segments. You can define and record these events with FullStory custom events.

import { sendEvent as sendFullStoryEvent } from '@commercetools-frontend/fullstory';

sendFullStoryEvent('eventName', {});

Custom events should be needed only in very rare cases as any user interaction is tracked by default.

User variables

FullStory allows to record custom user data which is an object or dictionary containing simple key/value pairs you'd like to record.

import { setUserVars as setFullStoryUserVars } from '@commercetools-frontend/fullstory';

setFullStoryUserVars({ email: user.email });

It's recommended to be mindful in what you send especially with Personal Identifiable Information.

Masking

FullStory has a built-in way to mask, unmask or exclude certain elements on a page. As FullStory should be used with the Private By Default settings, unmasking may be considered and carefully implemented when needed.

If an unmasking request occurs and has been deemed necessary and can not be accomplished via the "app-first" approach within FullStory's settings only then a "code-first" approach should be taken. The "code-first" approach can be implemented using one of three masking components from this package.

import { Masking as FullStoryMasking } from '@commercetools-frontend/fullstory';

// Assuming some component three exists you can use one of:

<>
  <FullStoryMasking.Unmask>{props.children}</FullStoryMasking.Unmask>
  <FullStoryMasking.Mask>{props.children}</FullStoryMasking.Mask>
  <FullStoryMasking.Exclude>{props.children}</FullStoryMasking.Exclude>
</>;

Each of the components above accepts an as prop which can be either span or div depending on your layout needs.

Marking

FullStory allows definitions of CSS and other Elements that represent key pieces of data you use regularly. When defining these key pieces you will have to write stable CSS selectors to those elements. These selectors should be resilient to changes in the layout of any Merchant Center application.

One way to achieve this is to mark elements directly or contextualize them in a section element. The Marking API of this package helps with this.

To wrap an entire section of an application you can use FullStory.Marking.Section:

import { Marking as FullStoryMarking } from '@commercetools-frontend/fullstory';

<FullStoryMarking.Section name="Discount Rules">
  <PartOfApplication />
</FullStoryMarking.Section>;

You can also pass additional props to the FullStoryMarking.Section component, such as a className. These will be forwarded to the underlying section HTML element.

Please do not wrap individual elements. If you need to mark individual elements such as a unlabelled input you can use applyMarker:

import { Marking as FullStoryMarking } from '@commercetools-frontend/fullstory';

<input {...FullStoryMarking.applyMarker('Discount Rule')} />;

Both cases will add a data-tracking="Discount Rule" to either the input or section element. You can then use these elements to target the element as in input[data-tracking="Discount Rule"] or section[data-tracking="Discount Rules"] button[label="some label"].

FAQ

Question: I want to disable FullStory on a specific environment Answer: Unset or not set the FULLSTORY_ORGANIZATION_ID on that environments dotenv file.

Question: I want to unmask a specific part of the page Answer: Add an fs-unmask class name to the outer most element of the area you intend to unmask.

Question: A function of the FullStory SDK is not supported here. How can I use it? Answer: It's recommended to add wrapper to this package and release is to any FullStory SDK usage is encapsulated here.