Installation

Before you start

You will need:

A tracker created in Flowtag Analytics
Access to your website's code, CMS, or tag manager
Your production domain set in the tracker's settings

Get the snippet from the Dashboard

Always copy the snippet from the Flowtag UI — it is generated with your tracker's ID already filled in.

Open your tracker

In the Flowtag Dashboard, go to Trackers and open the tracker you want to install.

Copy snippet

In the install dialog, click Copy snippet.

The copied snippet looks like this:

<script
  src="https://beacon.flowtagservices.com/tag.js"
  defer
  async
  data-ft="YOUR_TRACKER_ID"
  data-debug="false"
  data-gtagsync="true"
  data-auto-init="true"
  data-base-url="https://beacon.flowtagservices.com"
></script>

Do not hardcode or reuse another tracker's data-ft value. The tracker ID is also shown in the Dashboard toolbar — click it to copy.

Install the snippet on your site

Install it once per page load, in your global layout, theme, or site-wide header/footer include. Installing it twice on the same page causes two handshakes and duplicate sessions.

Use the @flowtag/next package for a typed React component.

pnpm add @flowtag/next

Add <Flowtag /> once in your root layout:

import { Flowtag } from "@flowtag/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <Flowtag trackerId="YOUR_TRACKER_ID" />
      </body>
    </html>
  );
}

Client-side navigations are detected automatically — you do not need to report route changes to Flowtag yourself.

Find the tracker ID in Connect, or paste the generated script snippet instead if you prefer a script-based install.

Snippet attributes

Attribute	Required	Default	Description
`data-ft`	Yes	—	Your tracker ID.
`data-debug`	No	`false`	When `true`, the tag logs debug information to the browser console.
`data-gtagsync`	No	`true`	Follows Google Tag Manager's `analytics_storage` consent signal. Recommended if you use GTM.
`data-auto-init`	No	`true`	Starts tracking on page load. Set to `false` to call `flowtag.init()` yourself.
`data-base-url`	No	Flowtag's beacon	The beacon endpoint. Do not change this value.

The tag removes these attributes from the DOM after reading them, so they will not appear if you inspect the element afterwards. That is expected.

Deferring the start

Set data-auto-init="false" when tracking must not begin until something else has happened — a consent banner being answered, for example. Nothing is recorded until you call:

window.flowtag.init();

The tag starts cookieless: no visitor ID cookie is written until consent is granted. Wire your banner to the consent API:

window.flowtag.consentCookies(true);  // accepted
window.flowtag.consentCookies(false); // declined — clears any stored ID

If you use Google Tag Manager and leave data-gtagsync="true", this happens automatically from the analytics_storage signal. See visitor identity and consent for what changes between the two modes.

Verifying the tag

After publishing, verify from the same Connect dialog:

Run the checker

Open your tracker, click Connect, then Check your website, and confirm the tracker is detected.

Confirm real traffic

Visit your site, then watch the Active (last 30 min) card on the tracker Dashboard. It should show at least one session within a few seconds.

You can also verify in browser DevTools — open the Network tab, filter for beacon.flowtagservices.com, and reload. You should see a handshake request followed by periodic envelope requests.

If your site injects scripts dynamically, the checker may fail even though tracking works. Live sessions in your Dashboard are the source of truth.

For a detailed console trace, set data-debug="true" temporarily, or run flowtag.setConfig("debug", true) in the console.

Troubleshooting

Symptom	Likely cause
No data at all	Tracker is `paused`, the snippet is missing from the deployed template, or a CDN is still serving a cached page.
Requests blocked in the console	A Content Security Policy is blocking the beacon. Allow `beacon.flowtagservices.com` in `script-src` and `connect-src`.
Data on some pages only	The snippet is on a single template rather than the global layout.
Data appears under the wrong tracker	A staging tracker ID was copied into production, or vice versa.
Sessions counted twice	The snippet is included twice — check for both a manual snippet and an SDK component.
Nothing from your own visits	`doNotTrackMe()` was enabled in that browser, or an ad blocker is blocking the request. Call `flowtag.doNotTrackMe()` again to re-enable.
Collection stopped abruptly mid-month	A plan limit was reached. The Dashboard shows a banner with the reset date.
Events rejected in the console	`capture()` ran before the handshake completed. Call it after mount rather than at module scope.

Common mistakes

Installing the snippet on one page instead of the global layout or template
Copying a tracker ID from the wrong environment
Forgetting to purge a CDN or theme cache after publishing
A Content Security Policy that omits the beacon domain
Testing on localhost and expecting it in production reports — the tag warns in the console when it detects localhost