3. Installing the Tracker

Chapter 2 covered the express install. This chapter is the complete, accurate reference for installing the FullSession tracker. It documents the exact snippet FullSession generates for you, what every line of it does, the alternative install paths (Google Tag Manager, the fullsession npm package, and the native mobile SDKs), and how FullSession verifies that recording has actually started.

One Customer ID, many sites

Your account has a single Customer ID that is shared across all the domains you track. You don't get a different ID per website — instead, you install the same snippet (carrying that one Customer ID) on every domain you want to record.

FullSession then sorts the incoming data for you: when a session is recorded, FullSession matches the origin domain the session came from against the URLs of the sites you've saved in your account, and files the session under the matching site automatically. This is what lets a single Customer ID power a marketing site, a web app, and a help center — each one's sessions land in its own site, even though they all share the same tracking code.

Wherever you see YOUR_CUSTOMER_ID below, the Installation page will have already substituted your real Customer ID.

Add your domains first. Because sessions are routed by matching their origin domain to your saved site URLs, make sure each domain you intend to track is listed under Settings → Sites before (or shortly after) you install. A domain that isn't saved has no site to be filed under.

---

3.1 JavaScript Snippet Installation

The direct <script> snippet is the most universal install method. It works on any site where you can edit the page HTML — a custom site, WordPress, Shopify, Webflow, and so on.

The snippet

This is the exact snippet FullSession generates. Copy it from Settings → Installation → Script (don't retype it — the app embeds your Customer ID and the correct CDN URL for your environment automatically):

<!-- Fullsession Recording Code for http://fullsession.io/ -->
<script type="text/javascript">
    window.FUS_IS_IN_IFRAME = (window.top != window.self);
    (function (m, n, t, l, x, p, o) {
        window["_fus_host"] = l;
        window["_site_id"] = p;
        window["_fus_id"] = x;
        o = n.createElement(t);
        o.type = "text/javascript";
        o.async = true;
        o.src = "https://emitter.fullsession.io/RTSessions.js";
        y = n.getElementsByTagName(t)[0];
        y.parentNode.insertBefore(o, y);
    })(window, document, "script", "fullsession.io", 'YOUR_CUSTOMER_ID');
</script>

The same snippet goes on every domain in your account. You do not customize it per site — the Customer ID is identical everywhere, and FullSession handles the per-site routing on its end.

Anatomy of the snippet

You don't need to understand the internals to install it, but knowing what each part does helps when troubleshooting:

Line	What it does
window.FUS_IS_IN_IFRAME = (window.top != window.self);	Detects whether the page is running inside an iframe. The tracker uses this to behave correctly when your site is embedded.
(function (m, n, t, l, x, p, o) { … })(...)	A self-executing function (IIFE) that injects the recorder script without blocking your page.
window["_fus_host"] = l;	Stores the FullSession host ("fullsession.io").
window["_fus_id"] = x;	Stores your Customer ID — the value passed in as 'YOUR_CUSTOMER_ID'. This is what ties recordings to your account.
o = n.createElement("script"); o.async = true;	Creates a new <script> element and marks it async so it loads in the background.
o.src = "https://emitter.fullsession.io/RTSessions.js";	The recorder library that actually captures sessions.
y.parentNode.insertBefore(o, y);	Inserts the recorder ahead of the first existing script on the page.

The key takeaways:

• The tracker is loaded asynchronously (async = true), so it never blocks your page from rendering.

• Your Customer ID is the last argument to the function — 'YOUR_CUSTOMER_ID'. This single value is what every domain in your account shares.

• The recorder itself is served from FullSession's emitter CDN, so you never host or update any tracking code yourself — improvements ship automatically.

• The origin domain of each recorded page is what FullSession later uses to route the session to the correct site — you don't encode the site anywhere in the snippet.

CDN URLs by environment

The src in your snippet depends on which FullSession environment your account uses:

Environment	Recorder URL
Production	https://emitter.fullsession.io/RTSessions.js
Development / staging	https://dev-emitter.fullsession.io/RTSessions-dev.js

The Installation page always shows the correct one for your account — you normally never need to change this by hand.

Where to paste it

Paste the snippet inside the <head> of every page you want to record, as high as possible — ideally right after the opening <head> tag. Placing it early means the recorder initializes before the rest of your page loads, so it captures the full session from the very first moment.

If your site uses a shared layout, theme header, or master template, paste the snippet there once so it's automatically present on every page of that domain. Repeat for each separate domain you want to track.

Common platforms

Platform	Where to paste
WordPress	Theme's header.php, or a "Header & Footer Scripts" plugin
Shopify	Online Store → Themes → Edit code → theme.liquid, inside <head>
Webflow	Project Settings → Custom Code → Head Code
Squarespace	Settings → Advanced → Code Injection → Header
Custom site	The shared <head> include / master layout

Tracking multiple domains

Because all your domains share one Customer ID, adding another site to FullSession is straightforward:

1. Add the new domain under Settings → Sites so FullSession has a URL to match sessions against.

2. Install the same snippet on that domain.

3. Sessions from the new domain are automatically filed under its site, separate from your other sites' data.

Publish and check

After pasting, save and publish your site, then open it in an incognito window and browse for ~30 seconds. The Installation page should change from Waiting for data to Verified (covered in detail in section 3.5).

---

3.2 Google Tag Manager Installation

If your site runs Google Tag Manager (GTM), FullSession can install the tracker for you — no copy-pasting into your site's code. This is the path most marketing-managed sites use.

Automated GTM setup (recommended)

From the GTM tab on the Installation page, you can connect your Google account and let FullSession create and publish the tag for you:

1. On the Installation page, open the GTM tab.

2. Click Connect Google Tag Manager and authorize access to your GTM account.

3. Select the GTM container for your site.

4. Confirm — FullSession will then automatically:

   • Create a page-view trigger named "Fullsession Trigger".

   • Create a Custom HTML tag named "Fullsession Tracking Script" containing your snippet (with your Customer ID).

   • Wire the tag to fire on the trigger (i.e. on every page view).

   • Create and publish a new container version named "Fullsession tracking code added".

     

When the flow finishes, the tracker is live on every page covered by the container — no manual GTM work required. If that container serves more than one domain, all of them report under your single Customer ID and are routed to their respective sites automatically.

Manual GTM setup

If you'd rather not connect your Google account, you can add the tag yourself:

1. In Google Tag Manager, open your container and go to Tags → New.

2. Name the tag Fullsession Tracking Script.

3. Choose Tag Configuration → Custom HTML.

4. Paste the FullSession Script snippet (from section 3.1) into the HTML field.

5. Under Triggering, create or select a trigger that fires on All Pages (a page-view trigger).

6. Click Save.

7. Click Submit → Publish to push a new container version live.

Don't forget to publish. In GTM, saving a tag is not enough — the tracker only goes live after you Submit and publish a new container version. The automated flow does this for you; the manual flow does not.

A note on the HTML tag settings

When FullSession creates the GTM tag automatically, it configures it as a Custom HTML tag with convertJsValuesToExpressions enabled and usePostscribe disabled. If you build the tag manually, the GTM defaults are fine — you don't need to change these unless your container has special requirements.

---

3.3 NPM Package Installation

For applications built with a bundler (React, Vue, Angular, Svelte, Next.js, etc.), FullSession publishes an official npm package. This is often cleaner than a raw <script> tag because the tracker becomes part of your app's normal dependency and build process.

Install

npm i fullsession

Initialize

Import the tracker and initialize it once, as early as possible in your app's startup (for example, in your root entry file — main, index, App, or equivalent):

import { fullSessionTracker } from 'fullsession'

// initialize fullsession tracker
fullSessionTracker.initialize('YOUR_CUSTOMER_ID');

Where to put initialize

Call initialize exactly once, at app boot — not inside a component that re-renders or a route that re-mounts. Initializing repeatedly can start the recorder more than once.

Framework	Recommended location
React (Vite/CRA)	src/main.tsx / src/index.tsx, before rendering the root
Next.js	A top-level client component / app/layout.tsx (client side), or _app.tsx
Vue	src/main.ts, before app.mount()
Angular	main.ts, or an APP_INITIALIZER

Single-page apps capture navigation automatically

Once initialized, the tracker detects client-side route changes on its own — each route change is recorded as a separate page within the same session, even though there's no full page reload. You do not need to re-initialize on navigation. This applies to both the npm package and the <script> snippet.

---

3.4 Mobile SDK Installation (Android & iOS)

FullSession also records native mobile apps through dedicated SDKs. The Installation page has Android and iOS tabs that generate the exact dependency and initialization code, pre-filled with your Customer ID and site URL. (React Native and Flutter are listed as coming soon.)

Android

Add the dependency in your module's build.gradle:

implementation("io.fullsession:fullsession-android:0.1.2")

Initialize the SDK when your application starts (typically in your Application class):

import io.fullsession.FullSession
import io.fullsession.config.FullSessionConfig

FullSession.init(application, FullSessionConfig(
    customerId = "YOUR_CUSTOMER_ID",
    siteUrl = "https://yoursite.com"
  )
)

iOS

Add the package via Swift Package Manager in your Package.swift (or through Xcode → Add Packages):

dependencies: [
    .package(url: "https://github.com/fullsession/ios-sdk-releases", from: "0.1.2")
],
targets: [
    .target(
        name: "<YOUR_TARGET_NAME>",
        dependencies: [
            .product(name: "FullSessionIos", package: "FullSessionIos")
        ]
    )
]

Initialize recording at app launch:

import FullSessionIos

let config = FullSessionConfig(
    customerId: "YOUR_CUSTOMER_ID",
    siteUrl: "https://yoursite.com"
)

FullSession.shared.initRecording(config: config)

Mobile configuration

Both mobile SDKs take the same two configuration values:

Option	Required	Purpose
customerId	Yes	Your Customer ID — ties recordings to your account
siteUrl	Yes	The app's site URL, used for context and to route data to the matching site

---

3.5 Identifying Users & Sending Events (the FUS API)

Once the tracker is installed via the <script> snippet or GTM, it exposes a small global object called FUS on window. You'll use this to attach identities and custom events to recordings. (This section is a quick reference; [Chapter 4 — Identifying Users] and [Chapter 7 — Recording Rules & Element Tracking] cover the concepts in depth.)

The FUS object exposes two primary methods:

FUS.identify(...) — attach a user identity

window.FUS.identify('YOUR_USER_ID', {
  name: 'Jane Doe',
  email: '[e-mail]'
});

• First argument — a stable, unique identifier for the user (your internal user ID or their email).

• Second argument (optional) — a properties object. The recognized fields are name and email.

Call this right after a user logs in, so their sessions become searchable by identity.

FUS.event(...) — record a custom event

window.FUS.event('funnel_access', {
  funnel_id: '1024',
  funnel_name: 'Checkout'
});

• First argument — the event name.

• Second argument (optional) — a properties object of any key/value details you want attached.

Custom events become the building blocks of funnels, segments, and insight cards.

Guard against early calls. Because the tracker loads asynchronously, window.FUS may not exist for the first few milliseconds after page load. If you call FUS.identify or FUS.event very early, check that window.FUS is defined first, or call it after the user has interacted (e.g. right after login).

---

3.6 Site Verification & Troubleshooting

After you install the tracker, FullSession verifies that it's actually loading and reaching your account. Verification is a real handshake between FullSession and your live site — not just a check that the snippet text is present.

How verification works

When you open the Installation page (or click Verify), FullSession loads your site in a hidden iframe and listens for messages the tracker posts back as it initializes:

Signal	Meaning
FUS_LOADED	The tracker initialized successfully. It includes a customer_id, which FullSession checks against your expected Customer ID.
FUS_FAILED_TO_REACH_SITE	The tracker could not initialize. It includes an error with details.

If no signal arrives within about 8 seconds, verification times out and falls back to checking whether any sessions have been recorded for the site yet.

The two status states

The Installation page shows one of two states:

Status	Meaning
🟢 Verified	The tracker loaded and its customer_id matches your account — data is being recorded. You're done.
🟡 Waiting for data	The snippet may be present, but no successful handshake or session has been received yet.

The fastest way to flip from Waiting for data to Verified is to open your site in an incognito window and browse a few pages — that produces a real session and a real FUS_LOADED signal.

Troubleshooting: "It still says Waiting for data"

Work through these in order:

1. Are you testing in incognito? Sessions from signed-in internal users may be excluded. Use a private window. See [Chapter 4, section 4.4].

2. Is the snippet actually on the live page? View page source (Ctrl+U / Cmd+Option+U) and search for FUS or RTSessions.

3. Does the Customer ID match? Verification only succeeds when the snippet's customer_id equals your account's Customer ID. If you pasted a malformed or truncated ID, the tracker will load but never verify. Re-copy the snippet from the Installation page.

4. Is the domain saved as a site? Sessions are routed by matching their origin domain to your saved site URLs. If you're testing on a domain that isn't listed under Settings → Sites, add it so the session has a site to land in.

5. Is a Content Security Policy (CSP) blocking it? A strict CSP can stop the recorder from loading or sending data. Allow the FullSession emitter domain (emitter.fullsession.io) in your script-src and connect-src directives.

6. Did you publish your GTM container? If you installed via GTM, confirm you published a new version — a saved-but-unpublished tag won't fire. See section 3.2.

7. Are ad blockers active? Test in a browser without blockers, or allowlist your own test page.

[img_place_holder] An example CSP that allows the FullSession recorder to load (script-src) and report sessions (connect-src).

Troubleshooting: sessions landing under the wrong site (or no site)

Because routing is based on matching the origin domain to your saved site URLs:

• If sessions aren't showing up under the expected site, confirm the domain is spelled and saved correctly under Settings → Sites (watch for www vs. non-www, http vs. https, and subdomain differences).

• If a domain isn't saved at all, its sessions have no matching site to be filed under. Add the domain, and subsequent sessions will route correctly.

Troubleshooting: replay shows broken styling

If sessions record but the replay looks unstyled, the recorder usually couldn't read some of your CSS:

• Cross-origin stylesheets without CORS headers won't be captured. Host them on the same origin, or serve them with crossorigin="anonymous" and a permissive Access-Control-Allow-Origin header.

• Authenticated/login-gated CSS that the player can't fetch won't render. Make critical styles public or inline them.

Troubleshooting: wrong pages, or too many/too few sessions

• Check Settings → Recording Rules to see whether any rules limit which URLs are recorded. See [Chapter 7 — Recording Rules & Element Tracking].

• Remember that bot traffic and pre-render requests are filtered out and won't appear as sessions.

The big picture — one Customer ID powers all your domains; the snippet loads an async recorder from emitter.fullsession.io keyed to that ID; GTM, the fullsession npm package, and the native mobile SDKs are alternative ways to load the same recorder; and FullSession routes each session to the right site by matching its origin domain to your saved site URLs. Once you see Verified, every other chapter in this guide is fed by the data the tracker captures.

---

Next up: [Chapter 4 — Identifying Users] builds on the FUS.identify call introduced here, showing how to turn anonymous recordings into searchable, named user journeys.