Fullstory Companion

Fullstory Companion was developed by Fullstory as an exploratory project. Please note that this software is provided as-is without official support. We welcome feedback and ask that issues and requests be posted to our Chrome Support Hub.

Fullstory Companion helps new and existing Fullstory users get the most out of data capture on their website.

By combining access to the current webpage and Fullstory settings, users can easily:

  • List element data capture rules active on the current page.
  • Inspect a specific element and determine which rule is applied when multiple rules match the element.
  • Craft better CSS selectors that can be used to create elements and element data capture rules in Fullstory.
  • Locate data layers and their contents.
  • Author and test custom data layer capture rules to send instrumented events, user, and page variables to Fullstory.
  • Discover element attributes suitable for indexing.
  • View org settings and troubleshoot data capture issues.

Add Fullstory Companion to Chrome

To install Fullstory Companion, proceed to the Fullstory Companion extension on the Chrome Web Store and click Add to Chrome.  After installing, it is recommended to set up Fullstory Companion for just websites that you’re capturing with Fullstory.  Go to Manage Extensions and click on Details in the Fullstory Companion card.  On the Site access card, change the dropdown to “On specific sites” and add the site(s) used with Fullstory Companion.

Overview

Fullstory Companion has many features, but the top use cases are:

  • Understand and adjust privacy rules: see which privacy rules affect the current page - down to individual elements on the page.
  • Build reliable CSS selectors: inspect any element and build a reliable CSS selector for it. 
  • Author Data Layer Capture rules: avoid syntax and visually build and test custom Data Layer Capture rules.

Toolbar

Fullstory Companion remembers your settings across sessions, including the last view and tab within a view.

The toolbar is divided into three sections from left to right: the main menu, the name of the current view, and a set of buttons for various actions such as accessing the current session replay, copying the current session URL, refreshing Fullstory Companion, and additional context-specific buttons that are not currently displayed.

The items in the main menu are called views, and most views have sub-navigation tabs.

 

Fullstory Companion has different views based on whether Fullstory is capturing the page.

Fullstory Capture Active Fullstory Capture Inactive
  • Data Layer Capture
  • DLC Rules Editor
  • Element Explorer
  • IFrames
  • Capture Settings
  • Privacy
  • Watched Elements
  • Capture Events
  • Server API
  • Settings
  • Data Layer Capture
  • DLC Rules Editor
  • Element Explorer
  • IFrames
  • Add Capture
  • Settings

 

Refresh

If you ever feel Fullstory Companion is out of sync with the current page, press the refresh button to resync.

Session link

Clicking the play button opens the current Fullstory session replay in a new tab.  You can also use the copy button to copy the session URL to your clipboard.

Common components

Element component

Several views in Companion contain similar elements. One notable example is the collapsible element component displayed below:

This component displays the element name (DIV), its size on the screen, and a bullseye icon that highlights the element on the page when clicked. Clicking the plus button expands the component to reveal more details, typically the HTML source of the element.

Unexpected Error message

If you encounter an "Unexpected Error" message on a page, first click the refresh button located above the error message. If the error persists, reload the web page and then reload Companion.

Views

Element Explorer

The Element Explorer View has 3 tabs, Attributes, Query, and Inspect.

Attributes

The Attributes tab allows you to search for attributes on the current page that follow a specific pattern. By default, it only filters data attributes (those starting with data-).

Each discovered attribute is listed along with the count of unique values found for that attribute. You can choose to hide attributes with only one value by enabling the "Hide single use" option. Expanding a data attribute reveals all the different values associated with it. Likewise, expanding a value shows all elements that match that value. Clicking the Bullseye button will highlight the element on the page.

Query

The Query tab allows you to enter in a CSS query and it will return elements that match. The “Hide 0 size” flag will hide any elements with zero size in the query results.

Inspect

The Inspect tab has a feature called "start inspecting" that enables access to various tools for interacting with elements on the current page.

Once you enable "start inspecting," the tool changes to an "inspecting" mode. As you hover your cursor over elements on the page, they will be highlighted. This functionality works similarly to Chrome Dev Tools and Fullstory's Inspect mode. While in this mode, the page will not respond to mouse actions. To exit Inspect Mode, simply click the "stop inspecting" button (it will also deactivate if you switch to a different tab).

If you click on an element while in Inspect mode, you will be able to view the HTML code of the selected element and a CSS Selector Helper.

 

The CSS selector helper shows you the full path to the selected item, filtered by parent elements containing the desired CSS Path Elements. The default is to show Data Attributes (those that start with data-)and element IDs. Any parent that has those path elements will be shown. You can then click on any of the path elements to add them to the CSS Selector value.

When you choose the path elements, they will automatically appear in the CSS Selector Value field.

The last selected path element will be outlined on the target page (notice the blue outlines on the active page as the attributes are selected).

You can remove your selection by clicking the "X" icon, choose the bullseye icon to select the item on the page, or click the copy icon to copy the selector. When the "Expand All" option is enabled, the helper will display the complete path to the target element, and the collapse icons will be disabled.

Data Layer Capture

The Data Layer View allows you to examine the Data Layer and Data Layer Capture (DLC) if applicable. There are 3 tabs in the Data Layer view: Rules, Explore, and Config.

Rules

By default, the Rules tab is displayed first, allowing you to view the DLC rules applicable to the current page. You have the option to expand each rule to view its details.

Explore

The Explore tab allows you to examine the variables within the window. You have the option to expand them to view the data associated with each variable.

The filters available are as follows:

  • Suggested - This option will specifically display data layer variables from platforms like Google, Adobe, Tealium, etc.
  • Filtered - This filter excludes window properties that are commonly not dataLayer variables.
  • All - This filter shows all non-null object variables present on the window.

Config

The Config tab will show the DLC config for the page, if applicable.

Capture Events

The Debug view has two tabs, Raw and API.

Raw

By accessing the Raw Tab, you can examine the original data transmitted to Fullstory for the current page (through the rec/bundle calls).

Upon entering the Raw View for the first time, you will probably encounter this display.

 

This feature displays a collection of all the events observed on this page, sorted by the highest number of occurrences. If you wish to view only a specific type of event, you can click on the eye icon to focus on that particular event type.

 

A green chip will appear at the top of the current view, filtering and displaying only those events. Each event is timestamped in milliseconds. You can expand any event to view its details, designed for easy readability. To exit this view, click the green chip.

If your search yields over 500 raw events, you won't be able to deselect the Groupings option. With Groupings enabled, events are consolidated into groups, limiting visibility of individual event details. An information box will notify you of this restriction.

To get below 500 events, you can either hide groups of events with the X icon.

When you perform this action, Grey Chips will be displayed at the top indicating that you have hidden certain groups. You can easily restore them by clicking on the X on the Grey Chips.

Alternatively, you can click on the FILTER button, which will reveal a slide-out menu for selecting the items you wish to display.

If a type is hidden by using the X icon, it will appear as disabled in this display.

When the number of elements is less than 500, you can disable the Groupings view and view the raw list of the selected types.

You can expand any individual event to see the details behind it.

API

The API Tab displays client-side API calls made on the page, including FS.identify, FS.setUserVars, FS.setVars, and FS.event. You can expand each call to view more details.

DLC Rules Editor

The DLC Rules Editor View allows you to write and debug rules for capturing data layer information. You begin by defining data layer objects in the Source Tab, then move on to the Rules Tab to specify the rules, check the Output Tab for debugging, and finally apply the rules to the current page in the Page Tab.

Source

In the Source Tab, you specify the data layer object you want to work with in the Rules Tab.

 

You have the option to retrieve a window variable from the current page (such as adobeDataLayer) or manually input your own variable name and data into the data layer in JSON format.

Whatever name you use on this tab should match the source of the rules you use on the next tab. It does not have to be a variable that actually exists on the current page

Rules

The Rules tab is where you can build out rule(s) that you want to test.

 

There are two ways to modify rules. One method is the Visual view, where you can visually create a rule. You can toggle between the Visual and JSON views for a single rule, but if you have multiple rules, only the JSON view is available.

In the Visual View, you can choose a from (similar to source) and use various operators, each with its own user interface. You can add operators on the right side using the + button and remove them with the - button. The supported operators currently include:

  • select - For selecting specific properties including exact match and those that start or end with specific values. You can add or remove the values with the smaller + and - buttons. This is the equivalent of the query operator with just properties specified or the ^ and $ prefix. Link.
  • when - This is for selecting when a property exists, is equal to, is not equal to, etc. The equivalent of the query operator with the ? prefix and the various options there.
    • Available tests - exists, is, is not, starts with, does not start with, greater than, less than, greater than or equal, less than or equal, is not empty string Link.
  • remove - Removes properties from the rule. Equivalent to the query operator with the ! prefix. Link.
  • rename - Allows for renaming a property to a new value. Works just like the rename operator. Link
  • fan-out - Identical to the fan-out operator. No properties. Link
  • flatten - Identical to the flatten operator. No properties. Link
  • parse - Identical to the parse operator. Same properties as specified in the Link.

The JSON mode enables you to input rules directly. When using JSON mode, you can input either a single rule or a set of rules. If you input multiple rules, the Visual view will be disabled.

Output

The OUTPUT tab is where you can see the output of running the SOURCE through the RULES. You run it by clicking on the RUN button, and then can filter the output.

An Output message shows the result that would be sent to a destination.

If the Output doesn’t look like you expected, you can show the Success view, which will show the whole “stack” of operators that were run to produce the rule. The stack is right below the output.

The data displayed includes the initial source data and the result after each operation. This feature assists in troubleshooting the rule's execution process.

If a rule fails to reach its destination, you can select the Failure button to view Halted rules (rules that did not finish).

The list is organized based on the attempts that progressed the furthest. This sorting aids in diagnosing rules that do not complete successfully. Rules that do not complete successfully will have an operator that returns NULL. The detailed debug view will indicate which operator returned NULL.

Page

The Page tab allows you to apply the tested rule(s) to the live page.

Preview mode enables you to view rule outputs in the console without actually triggering the FS APIs. To activate the real FS API calls, disable Preview Mode. Note that Preview Mode affects all added rules collectively, not individually. The final setting determines the overall preview mode.

Clicking the Add N Rule(s) to Page button adds the rules to the current page. If Preview Mode is off and APIs are triggered, their activity will be visible in the session replay. With Preview Mode on, you can check the page's Console to verify the expected output.

A good approach is to ensure that the Rules are functioning correctly in the Output Tab before adding them to the page in Preview Mode and confirming their functionality.

Capture Settings View

This view displays brief and fundamental details regarding the Fullstory setup on the current page being examined. It includes information such as orgId, debug, version, ajaxWatches, watchedelements, and privacyRules. The General View consists of three tabs: Basic, Advanced, and Integrations.

Basic

The Basic Tab provides a straightforward overview of the fundamental details regarding the current Fullstory snippet displayed on the page.

Advanced

The Advanced Tab displays the complete output of the rec/page call, which initiates the Fullstory session on the page.

Integrations

The Integrations Tab displays the rec/integrations call and the corresponding URL. This feature is helpful for troubleshooting issues related to integrations that inject scripts onto the page.

IFrames View

The IFrame View will search the current page for all IFrames available. Sometimes, IFrames are configured not to respond to such searches, and in those instances, you will receive a warning message.

You can expand any of the IFrame boxes to see the HTML inside of it.

Privacy View

Within the Privacy view, you can review the privacy rules and how they impact the current page. The Privacy View consists of two tabs: Explore and Rules.

Explore

The Explore Tab enables you to view all the elements on the current page that are affected by privacy rules.

The default view displays elements with Privacy rules applied, ordered by their position in the DOM hierarchy.

Elements with a size of 0 are initially hidden but can be shown by clicking on the "Hide 0 Size" link.

You can expand any element to view the rules applied to it.

If you want to see what affects an element not listed, you can enter Inspect mode by clicking the Inspect button. In this mode, hovering over the page highlights elements. Clicking on a specific element will filter the list to show only the path to that element.

Additionally, you can filter for specific elements using the Filter input, entering in any CSS query.

 

Clicking on the bullseye icon will highlight the element on the page next to the sidebar (similar to inspect mode in Dev Tools).

Using the <> icon will display the full HTML of the element in a drawer.

Rules

The Rules Tab displays all query results for privacy elements, initially concealing those with 0 results. You can expand any rule to view matching elements. The same bullseye icon and code icon can be used here as well.

Server API View

The Server API View enables interaction with the Server Side API from Fullstory using your API Keys. Currently, it supports calling the Segment API to create and download CSV or JSON exports from a Segment.

Keys

Upon entering the Server API View, you will see the Keys Drawer displayed as shown below:

All Server API calls require an API Key, which is stored in the browser's local storage. To enhance security, the API Keys are encrypted using Crypto JS AES Ciphers and a user-defined "Passphrase" is needed to access the Server API View in Companion. This Passphrase is not saved anywhere and is solely known to the user. Users can choose any Passphrase to encrypt their API Keys.

After entering a Passphrase, your screen will appear as follows.

This section displays all the keys you have saved and allows you to add new ones. To add a key, provide a name (used for identification), the API key, click on Test, and if successful, click Add. Follow the prompts for guidance. Once keys are added, you can select them from the dropdown menu.

If the key is successfully decrypted with your passphrase and is valid, it will display details such as Org, Email, and Role. If you select a key that does not match the Org of the Fullstory snippet on the current page, a warning will appear in the drawer and the main Server API View.

In such cases, you can still use the key, but a warning will remind you. The API calls do not impact the current page.

You can also delete a previously added key from this section. If there is an issue with your key, such as an incorrect passphrase or an expired key, a warning message will be displayed.

 

It is impossible to know if the problem is the Passphrase or the Key itself, as Companion doesn’t know your Passphrase.

Once you have a valid Key selected, you can go back to the main Server API View. You can get back to the Keys Drawer by selecting the Keys button on this View.

Segment

The Segment Tab has two sections, Create and Results.

Create

In the Create section, you can generate a new Segment Export. It provides step-by-step instructions on the REST calls required to create a Segment API Export. You start by entering a Segment ID and clicking Validate. If the Segment ID is valid, you will see a confirmation message. Otherwise, an error message will be displayed. Once you have a valid Session ID, you can select the Export type, Scope (for Event type), Format (JSON or CSV), and Time Range.

By default, all available fields are included in the Export, resulting in a large file. It is recommended to choose only the necessary fields to reduce the file size. This can be done through the Advanced Settings by selecting the Use Advanced Settings checkbox.

Once you enable Advanced Settings, you will see a view like above, which will tell you how many fields you have selected and enable the Advanced button to take you to the Advanced Field Selector.

The Advanced Field Selector resembles the image displayed above. The fields are categorized as detailed in the documentation available here. The groupings that are expanded depend on the type of Export chosen (Event or Individual). You have the option to choose all fields within a grouping by using the ALL button, or you can pick individual fields. The first two categories (All User Vars and All Custom Event Properties) can be utilized to include all User Variables (if necessary) and/or all Custom Event properties (if needed). While selecting individual User Variables or Custom Event properties is not permitted within the interface, it is possible through API calls. 

When you exit the Advanced Field Selector, you can see the number of fields you have selected.

By selecting only certain fields, the file size can be reduced significantly, from many gigabytes to just a few megabytes. (Fullstory contains a large amount of data.)

After selecting your preferences, you can click on Create Export, which will trigger the API with your chosen settings. If successful, you will be directed to the Results Mini Tab. In case of failure, an error message containing JSON from the server will be displayed.

Results

In the Results Mini Tab, you can view the status of your exports – whether they are still processing or ready for download. If an export is in a PENDING (processing) state, the interface will automatically refresh every 10 seconds until it is completed.

You can monitor the 10-second countdown with a progress bar and check the current completion percentage in the table.

Expired past exports are hidden by default. To view them, simply uncheck the Hide Expired checkbox.

Once your results are ready, a cloud download icon will appear next to them.

Clicking the link triggers the download API to generate a URL.

You can utilize this link to download the requested results in your preferred format until it expires (the expiration time is displayed in the table).

Settings View

The Settings View allows you to choose the debug level for Companion. The default level is WARN, but you have the option to switch it to ERROR, WARN, INFO, DEBUG, or NONE. This preference is stored locally and will persist until modified or local storage is reset, in which case it reverts to the default setting of WARN.

Watched Elements View

The Watched Elements view allows you to see the watched element rules and their effect on the current page. There are two tabs in this view: Explore and Rules.

Explore

The Explore tab displays all elements on the current page that are affected by Watched Element rules.

By default, it shows elements with directly applied Watched Element Rules, ordered by their position in the DOM hierarchy.

Elements with a size of 0 are initially hidden but can be shown by clicking on the "Hide 0 Size" link.

You can expand any element to view the rule(s) applied to it.

If you want to find out what affects an element not listed, you can enter Inspect mode by clicking the Inspect button. In this mode, hovering over the page highlights different elements. Clicking on the desired element will filter the list to show only the path to that element.

 

You can also narrow down elements by using the Filter input and entering any CSS query.

By clicking on the bullseye icon, you can highlight the specific element on the page next to the sidebar (similar to inspect mode in Dev Tools).

The symbol will display the complete HTML code of the element in a separate panel.

Rules

The Rules Tab displays all query results for the monitored elements, initially hiding those with zero results. You can expand any rule to view the matched elements. The same bullseye and code icons can be used here as well.

Add Capture View

The Add View option is accessible when Fullstory is not detected on the current active tab. This view is handy for manually adding Fullstory to a page, such as for testing purposes or to demonstrate a concept. The Add View interface appears as shown below.

You would enter the OrgId, the Namespace you want to use, the host, and the script.  These are the same parameters that are used to add the Fullstory snippet to your webpage.  Here is the start of the Fullstory snippet.

window['_fs_host'] = 'fullstory.com';
window['_fs_script'] = 'edge.fullstory.com/s/fs.js';
window['_fs_org'] = 'myOrgId';
window['_fs_namespace'] = 'FS';

By entering these values in the form and clicking “Add to Page”, a Fullstory snippet is created in the active tab, simulating as if the snippet was originally added when the page loaded. If successful, you will see the General View appear, along with other views related to a page with Fullstory.

In the future, Fullstory Companion will detect when a new page is loaded from the same domain as the initially added page and will automatically add Fullstory to this new page. This allows you to maintain a session as you move between different pages.

If you attempt to add Fullstory to a page with a Content Security Policy that blocks Fullstory from functioning, you will still see the General View, but you will also notice that the Session URL is empty and a “Remove Content Security Policy” (shield) button is displayed.

By clicking the shield icon, you can temporarily disable the Content Security Policy in the Chrome extension. After doing this, a reload button will appear next to the empty Session URL field. This button will reload the page without the Content Security Policy, allowing the normal Session link to be displayed.

In cases where Content Security Policies are in place, you may need to click the reload icon when navigating between pages to continue building the session. This is an expected behavior and ensures the session is maintained. Although this situation is rare, it is documented here for reference if you encounter it.

 

Need to get in touch with us?

The Fullstory Team awaits your every question.

Ask the Community Technical Support