Getting Started

Script Configuration

All available tracking script options and data attributes

The Flowsery Analytics tracking script supports several data attributes for customizing tracking behavior. This guide covers every available configuration option.

New to Flowsery Analytics?

Start with the installation guide first to add the tracking script to your website.

Script attributes

Website ID — data-fl-website-id (required)

Your unique website identifier from Flowsery Analytics.

Basic script tag
<script
  defer
  data-fl-website-id="flid_******"
  data-domain="your_domain.com"
  src="https://analytics.flowsery.com/js/script.js"
></script>

Domain — data-domain (required)

Your website's root domain. Used for cookie management across subdomains.

Subdomain tracking

By default, Flowsery Analytics tracks all subdomains of your root domain. For example, if your root domain is example.com, Flowsery Analytics operates on app.example.com, blog.example.com, shop.example.com, etc.

Allowed Hostnames — data-allowed-hostnames (optional)

Comma-separated list of additional domains for cross-domain tracking.

  • Default: Empty (no cross-domain tracking)
  • Example: app.io,shop.example.com
  • Use case: Track users across different root domains
Cross-domain tracking
<script
  defer
  data-fl-website-id="flid_******"
  data-domain="your_domain.com"
  data-allowed-hostnames="app.io,myapp.org"
  src="https://analytics.flowsery.com/js/script.js"
></script>

API URL — data-api (optional)

Custom API endpoint for sending events. Accepts a full URL or a relative path.

  • Example: https://api.example.com/events or /custom-events
  • Use case: Custom API endpoints, third-party analytics proxies, or advanced proxy configurations

If you supply a relative path, it is appended to your domain.

Automatic proxy detection

Flowsery Analytics automatically detects proxied setups. Only use this if you need a custom endpoint path or want to send events to a completely different server.

Allow Localhost — data-local (optional)

Enable tracking on localhost for development and testing. Accepts "true" or "false". Default: false.

Allow File Protocol — data-allow-file-protocol (optional)

Enable tracking when opening HTML files directly in a browser (file:// protocol). Accepts "true" or "false". Default: false.

Debug Mode — data-debug (optional)

Enable debug mode to allow tracking inside iframes. Accepts "true" or "false". Default: false. By default, Flowsery Analytics does not track inside iframes to prevent duplicate tracking.

Disable Console — data-disable-console (optional)

Disable all console logging from the Flowsery Analytics tracker. Accepts "true" or "false". Default: false.

Disable Payments — data-disable-payments (optional)

Disable automatic payment tracking and revenue attribution from URL parameters (Stripe session_id, LemonSqueezy order_id, Polar checkout_id). Accepts "true" or "false". Default: false.

  • Use case: When using server-side revenue attribution to avoid duplicate payment events

Manual payment tracking

Manual window.flowsery("payment", { email }) calls still work when this is enabled. Only automatic detection from URL parameters is disabled.

HTML element attributes

These attributes are added to HTML elements on your page to enable automatic tracking.

Goal Tracking — data-fs-goal (optional)

Track clicks on any element as a custom goal. Lowercase letters, numbers, underscores, hyphens only. Max 64 characters.

<button data-fs-goal="add_to_cart">Add to Cart</button>

Goal Parameters — data-fs-goal-* (optional)

Add custom parameters to goal events. The parameter name is derived from the attribute name (kebab-case, converted to snake_case). Max 10 parameters per event. Parameter names: max 64 chars. Values: max 255 chars.

Goal with parameters
<button
  data-fs-goal="product_added"
  data-fs-goal-product-id="prod_123"
  data-fs-goal-product-name="Premium Plan"
  data-fs-goal-price="49">
  Add to Cart
</button>

Scroll Tracking — data-fs-scroll (optional)

Automatically track when an element becomes visible during scrolling. Default trigger: element is 50% visible. Same naming rules as data-fs-goal.

<section data-fs-scroll="viewed_pricing">
  <h2>Pricing</h2>
</section>

Scroll Threshold — data-fs-scroll-threshold (optional)

Customize the visibility threshold for scroll tracking. Decimal between 0 and 1. Default: 0.5 (50% of element visible). Common values: 0.1 (10%), 0.5 (50%), 0.9 (90%), 1.0 (100%).

Scroll Delay — data-fs-scroll-delay (optional)

Add a delay in milliseconds before the scroll event is tracked. Default: 0 (no delay).

Scroll tracking with threshold and delay
<section
  data-fs-scroll="read_testimonials"
  data-fs-scroll-threshold="0.7"
  data-fs-scroll-delay="3000">
  <!-- Tracks only if element stays visible for 3 seconds -->
</section>

Scroll Parameters — data-fs-scroll-*

Add custom parameters to scroll tracking events, similar to data-fs-goal-*.

Common configuration examples

Development environment

<script
  defer
  data-fl-website-id="flid_******"
  data-domain="your_domain.com"
  data-local="true"
  src="https://analytics.flowsery.com/js/script.js"
></script>

Production with proxy

<script
  defer
  data-fl-website-id="flid_******"
  data-domain="your_domain.com"
  src="/js/script.js"
></script>

Flowsery Analytics auto-detects proxied setups. No data-api needed if you proxy both /js/script.js and /api/events.

Cross-domain tracking

<script
  defer
  data-fl-website-id="flid_******"
  data-domain="your_domain.com"
  data-allowed-hostnames="app.io,shop.example.net"
  src="https://analytics.flowsery.com/js/script.js"
></script>

Use the same configuration on all tracked domains.

Hash-based navigation tracking

For Single Page Applications with hash routing:

<script
  defer
  data-fl-website-id="flid_******"
  data-domain="your_domain.com"
  src="https://analytics.flowsery.com/js/script.hash.js"
></script>

Validation rules summary

Goal and event names

  • Characters: Lowercase letters, numbers, underscores (_), hyphens (-)
  • Length: Maximum 64 characters

Custom parameter names

  • Characters: Lowercase letters, numbers, underscores (_), hyphens (-)
  • Length: Maximum 64 characters
  • Conversion: kebab-case attributes are automatically converted to snake_case

Custom parameter values

  • Length: Maximum 255 characters
  • HTML/XSS: Dangerous characters are automatically sanitized
  • Limit: Maximum 10 custom parameters per event

Scroll threshold

Decimal number, range 0.0 to 1.0, default 0.5.

Scroll delay

Integer (milliseconds), range 0 or greater, default 0.

Troubleshooting

Tracking not working on localhost

Add data-local="true" to enable local tracking.

Custom goals not firing

Verify your goal name follows the validation rules: lowercase only, no spaces or special characters (except _ and -), max 64 characters.

Cross-domain tracking not working

Verify: same data-fl-website-id on all domains, all additional domains listed in data-allowed-hostnames, users click links between domains.

Scroll tracking not triggering

Common issues: element not in viewport long enough, threshold set too high, IntersectionObserver not supported.