FullStory Relay is a capability 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.
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, who would like 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.
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, as seen below.
With FullStory Relay installed, that same traffic will first be sent to a service addressed with 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 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.
There are two types of Relay that can be deployed into your managed infrastructure: Cloud Relay and On-Prem Relay. In technical terms, both are merely setting up what’s known as a reverse-proxy to FullStory servers from your users’ browsers.
|Cloud Relay||On-Prem Relay|
|Using a CDN hosted at a PaaS provider, customers can quickly and easily set up a reverse-proxy, without the complexity or maintenance of On-Prem Relay.||FullStory developed an open source project that serves as an on-prem reverse-proxy cluster.|
The process to set up Relay includes, simply deploying the infrastructure inside your domain and configuring your FullStory data capture script (for browser capture) or metadata file (for native mobile capture) 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 FullStory Relay in a sandboxed environment inside your domain with no permissions to the rest of your production environment.
Deploying FullStory Relay
FullStory supports deployments of Cloud Relay on AWS and GCP Platform-as-a-Service (PaaS) providers. Using Terraform, customers are able to easily and confidently deploy a Relay environment tailored to their configuration. The steps for this process on either platform provider can be found here:
- Amazon Web Services (AWS): https://registry.terraform.io/modules/fullstorydev/fullstory-cloud-relay/aws/
- Google Cloud Platform (GCP): https://registry.terraform.io/modules/fullstorydev/fullstory-cloud-relay/google/
Please contact support for questions on setting up Cloud Relay.
Now that you've deployed your Relay environment, scroll down to Configuring Your Website or Application for Data Capture to continue the setup process.
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 variables passed into your docker container, or statically defined in a .yaml file. Refer to Running Relay for more information about Relay parameters.
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):
TRAFFIC_RELAY_SPECIALS=^/s/ https://edge.fullstory.com/s/ ^/datalayer/ https://edge.fullstory.com/datalayer/ ^/echo https://services.fullstory.com/echo
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 for Path Prefix
The typical method of deploying Relay is in a dedicated subdomain scenario. It may be more preferable to deploy Relay using a path prefix scenario, where paths that are prepended with a specific prefix (like /fsrelay) trigger system to rewrite the path and direct it to the Relay origin host.
If this is the case and you are using path prefix, 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';
Now that you've deployed your Relay environment, head back over to the main Relay setup page to walk through configuring your web snippet or mobile SDK.
Configuring Your Website or Application for Data Capture
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'; window['_fs_app_host'] = 'app.fullstory.com';
If you're using a dedicated subdomain for the Relay then change the same variables but use these values (where
fsrelay is replaced with whatever subdomain you choose to use):
window['_fs_host'] = 'relay.your-company.com'; window['_fs_script'] = 'relay.your-company.com/s/fs.js'; window['_fs_app_host'] = 'app.fullstory.com';
fsrelay.your-company.comendpoint must be world-accessible over https. Also, do not include the
https://or a final
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:
Relay support is available starting in version 1.37.0 of the native mobile SDKs. See Getting Started with Android Data Capture and Getting Started with iOS Data Capture for how to configure your SDK version and perform other setup.
Configuring a Relay server for your mobile app will also apply to web view contents in the app.
In the Fullstory Block of your app’s
build.gradle add a
serverUrl configuration with the value of your Relay server’s url. If you are using a path prefix, make sure to include that here.
In the FullStory Dictionary of your app’s
Info.plist file add a
ServerUrl configuration of type
String with the value of your Relay server’s url. If you are using a path prefix, make sure to include that here.
Verifying It's Working
To confirm that the Relay is working, 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.
What benefits come with FullStory Relay?
- Increased number of sessions
- Sometimes you may have difficulty locating a session in FullStory, even when you know a user has interacted with your site. Users can sometimes take extra steps to be security conscious, such as installing third-party extensions (such as Tracker and Ad blockers) or using strict browser settings. Using FullStory Relay would keep these sessions from being blocked by tracking protection measures, helping to provide a more complete picture of user interactions.
- Greater trust from web visitors
- Custom analysis or processing prior to sending data to FullStory