The FullStory Relay
The FullStory Relay is an open source project that allows you to route all captured FullStory traffic from your users’ browser directly through your own domain, allowing for maximally secure CSP rules and avoiding potential data capture disruptions that may be caused by restrictive browser settings or extensions configured to block network traffic to third party domains.
Data captured from your site is Your Data
The FullStory mission is about empowering companies to use data to improve the online experience for their customers. FullStory runs on your site or app, storing and processing information about real customers, attempting to use your product or service to do things they care about.
This raw data captured from your digital property belongs to you, not FullStory.
FullStory Relay provides our customers with a way to help cement this notion of first-party data ownership in the minds of their end-users by routing FullStory traffic through their own domain. Legitimizing FullStory traffic in this way has many benefits to both end-user perception and site security and we hope you find this offering valuable.
How It Works
In the article How does FullStory data capture work, you’ll notice interactions to your website are “bundled” together and sent to FullStory servers every 5 seconds, like shown below.
With the FullStory Relay installed, that same traffic will first be sent to a service hosted in your own domain, and then relayed immediately to the FullStory servers for processing. For example, the traffic from your users’ browser may now look like this (where the domain would be your own company's domain instead):
Using the Relay allows you to capture traffic on your own website as a pre-approved first party domain, thus avoiding network restrictions that may have otherwise been configured by a subset of your users through browser settings or extensions.
To use Relay, you simply need to install it somewhere inside your domain and configure your FullStory data capture script to direct captured traffic to a new endpoint you expose. The following section will walk you through this process in detail.
Note: For your own security, we highly recommend installing the FullStory Relay in a sandboxed environment inside your domain with no permissions to the rest of your production environment.
How to Install the FullStory Relay
The FullStory Relay is an open source project available on github at https://github.com/fullstorydev/relay-core/
There are two ways to use the Relay: via a “path prefix” on your main domain or as a publicly accessible subdomain.
Using a Path Prefix
Using this method you’ll configure your load balancer to receive relay requests on a specific path off your main site url. For example, if your site root domain was https://your-company.com, you could route Relay traffic to https://your-company.com/fsrelay.
By using a path prefix, browser data capture traffic will connect only to your main site and no other hosts. This option offers a simplified experience to your users (all traffic to the same root domain), but may be a little harder to configure on the server side.
Using a Dedicated Subdomain
In this example, you register a publicly accessible subdomain off your site root domain to receive Relay traffic. For example, if your site root domain was https://your-company.com, you could register https://fsrelay.your-company.com.
Using the subdomain method has the advantage of not requiring special routing in your main site’s load balancer, but does mean that your users will be connecting to multiple subdomains off your site, which may have repercussions to how you configure your TLS certificates and other browser security measures like content security policies.
Configuring the Relay
The FullStory Relay project is a generic solution to redirect any type of traffic to any endpoint, so to configure for FullStory data capture requires some additional configuration through environment variables.
The Relay is configured through environment variables either passed into your docker container, or statically defined in a .env file. You can reference dotenv.example for a description of all available variables, as well as their default values.
To use with FullStory data capture, the Relay process (when run as a Docker container) requires the following environment variables to be configured. For RELAY_PORT, use the port number you configure when launching your docker container (8086 used as an example in this case):
If you’re using the path prefix method (see above) then you will also need these two values:
Note that TRAFFIC_PATHS_MATCH should be set to the actual path you’ve specified off your root domain for the FullStory Relay. For example, if your full URL was https://your-company.com/fsrelay, then you would set it like above: TRAFFIC_PATHS_MATCH=^/fsrelay/.
Nested paths will also work, for example https://your-company.com/apps/fullstory would be:
For the Docker image you’ll want to pass these values in as environment variables, as described in the Running Relay document.
When using a Relay binary you should set the same environment variables in a shell script or using the configuration options of your service host.
Configuring Your Data Capture Snippet
With your Relay up and running, you will now need to update your FullStory data capture snippet to send data capture traffic to the Relay. You may want to first read through the article How do I get FullStory up and running?
Within your FullStory snippet, you’ll find a parameter near the top called window['_fs_host'] like this:
If you’re using a path prefix (see above) then you should change two variables like so:
window['_fs_host'] = 'your-company.com/fsrelay';
window['_fs_script'] = 'your-company.com/fsrelay/s/fs.js';
If you're using a dedicated subdomain for the Relay then change the same variables but use these values (where fsrelay is replace with whatever subdomain you choose to use):
window['_fs_host'] = 'relay.your-company.com';
window['_fs_script'] = 'relay.your-company.com/s/fs.js';
Note: The fsrelay.your-company.com endpoint must be world-accessible over https. Also, do not include the https:// or a final / in _fs_host.
If you'd like to install the browser SDK directly when using FS Relay (rather than the snippet), the parameters that we pass into the
init should look as follows:
Verifying It's Working
To confirm the Relay is working, first and foremost you should be seeing new data capture sessions show up in your FullStory account. Additionally, we recommend you visit your site using Chrome, open up the Developer Tools network tab and filter on the word “bundle”. Every 5 seconds you should see an XHR request sent to an endpoint off the path you defined above for window['_fs_host']. For example, if your fs_host value was customer.transmutable.com, you should see something like this:
You should not see traffic to any fullstory.com domain. If you still see traffic to FullStory, double check you have properly set the fs_host value in the Configuring Your Data Capture Snippet section above.