Complete reference for all data attributes available in the Faurya tracking script to customize tracking behavior.

Faurya script configuration

Faurya tracking script supports several data attributes that allow you to customize tracking behavior. This guide covers all available configuration options.

New to Faurya? Start with the installation guide first.

Website ID `data-website-id` (required)

Your unique website identifier from Faurya.

Example:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  src="https://faurya.com/js/script.js"
></script>

Domain `data-domain` (required)

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

Note: By default, Faurya will track all subdomains of your root domain. For instance, if your root domain is example.com, Faurya will work on app.example.com, blog.example.com, shop.example.com, etc.

See subdomain tracking documentation for tracking across subdomains.

Example:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  src="https://faurya.com/js/script.js"
></script>

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

Example:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-allowed-hostnames="app.io,myapp.org"
  src="https://faurya.com/js/script.js"
></script>

See cross-domain tracking documentation for setup details.

API URL `data-api-url` (optional)

Custom API endpoint for sending events. Provide 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 use a relative path, it will be appended to your domain. For instance, if your domain is example.com and you use /custom-events, the full URL will be https://example.com/custom-events.

Example with full URL:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-api-url="https://api.example.com/track"
  src="https://faurya.com/js/script.js"
></script>

Example with path:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-api-url="/custom-analytics-endpoint"
  src="https://faurya.com/js/script.js"
></script>

Note: Faurya automatically detects proxied setups. Only use this if you need a custom endpoint path or want to send events to a completely different server. If the provided URL is invalid, Faurya will fall back to the default endpoint. See proxy guides for detailed setup instructions.

Allow Localhost `data-allow-localhost` (optional)

Enable tracking on localhost for development and testing.

Type: "true" or "false"
Default: false
Use case: Testing analytics implementation locally

Example:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-allow-localhost="true"
  src="https://faurya.com/js/script.js"
></script>

Tracking is disabled on localhost by default to prevent polluting your production analytics data. See excluding visits for other ways to exclude traffic.

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

Enable tracking when opening HTML files directly in browser (file:// protocol).

Type: "true" or "false"
Default: false
Use case: Testing with local HTML files

Example:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-allow-file-protocol="true"
  src="https://faurya.com/js/script.js"
></script>

Debug Mode `data-debug` (optional)

Enable debug mode to allow tracking inside iframes.

Type: "true" or "false"
Default: false
Use case: Testing tracking in embedded contexts

Example:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-debug="true"
  src="https://faurya.com/js/script.js"
></script>

By default, Faurya doesn't track inside iframes to prevent duplicate tracking.

Disable Console `data-disable-console` (optional)

Disable all console logging from Faurya tracker.

Type: "true" or "false"
Default: false
Use case: Clean console logs in production

Example:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-disable-console="true"
  src="https://faurya.com/js/script.js"
></script>

Disable Payments `data-disable-payments` (optional)

Disable automatic payment tracking from URL parameters (Stripe session_id, LemonSqueezy order_id, Polar checkout_id).

Type: "true" or "false"
Default: false
Use case: When using server-side revenue attribution to avoid duplicate payment events

Example:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-disable-payments="true"
  src="https://faurya.com/js/script.js"
></script>

Manual window.Faurya("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 in your page to enable automatic tracking.

Goal Tracking `data-faurya-goal` (optional)

Track clicks on any element as a custom goal.

Rules: Lowercase letters, numbers, underscores, hyphens only. Max 64 characters.
Example: checkout_initiated
Use case: Track button clicks, link clicks, or any user interaction

Example:

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

See custom goals documentation for more examples.

Goal Parameters `data-faurya-goal-*` (optional)

Add custom parameters to goal events. The parameter name is extracted from the attribute name.

Naming: data-faurya-goal-{parameter-name} (kebab-case, converted to snake_case)
Rules: Max 10 parameters per event. Parameter names: lowercase, numbers, underscores, hyphens, max 64 chars. Values: max 255 chars.
Example: data-faurya-goal-product-id="prod_123"

Example:

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

In this example, Faurya tracks a goal named product_added with parameters:

{
  product_id: "prod_123",
  product_name: "Premium Plan",
  price: "49"
}

Scroll Tracking `data-faurya-scroll` (optional)

Automatically track when element becomes visible during scrolling.

Default trigger: Element is 50% visible
Rules: Same as data-faurya-goal (lowercase, numbers, underscores, hyphens, max 64 chars)
Example: scroll_to_pricing

Example:

<section data-faurya-scroll="viewed_pricing">
  <h2>Pricing</h2>
  <!-- Pricing content -->
</section>

See scroll tracking documentation for detailed examples.

Scroll Threshold `data-faurya-scroll-threshold` (optional)

Customize visibility threshold for scroll tracking.

Type: Number (decimal between 0 and 1)
Default: 0.5 (50% of element visible)
Example: 0.8 (80% visible)
Use case: Fine-tune when tracking triggers based on element visibility

Example:

<section data-faurya-scroll="viewed_hero" data-faurya-scroll-threshold="0.8">
  <!-- Tracks when 80% of this section is visible -->
</section>

Common threshold values:

0.1 - Track as soon as element appears (10% visible)
0.5 - Track when half visible (default)
0.9 - Track when almost fully visible (90% visible)
1.0 - Track only when completely visible

Scroll Delay `data-faurya-scroll-delay` (optional)

Add delay before tracking scroll event.

Type: Number (milliseconds)
Default: 0 (no delay)
Example: 2000 (2 seconds)
Use case: Ensure users spend time viewing content before tracking

Example:

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

Scroll Parameters `data-faurya-scroll-*`

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

Naming: data-faurya-scroll-{parameter-name} (kebab-case, converted to snake_case)
Example: data-faurya-scroll-section-name="hero"

Example:

<section
  data-faurya-scroll="section_viewed"
  data-faurya-scroll-section-name="testimonials"
  data-faurya-scroll-section-order="3"
>
  <!-- Custom parameters help analyze which sections engage users -->
</section>

Common configuration examples

Development environment

Enable tracking on localhost for testing:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-allow-localhost="true"
  src="https://faurya.com/js/script.js"
></script>

Production with proxy

Proxy script through your domain to bypass ad blockers:

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

Faurya auto-detects proxied setup. No data-api-url needed if you proxy both /js/script.js and /api/events. See proxy setup guide for implementation details.

Cross-domain tracking

Track users across multiple domains:

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

Use the same configuration on all tracked domains.

Clean production setup

Minimal console output in production:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-disable-console="true"
  src="https://faurya.com/js/script.js"
></script>

For Single Page Applications with hash routing (e.g., #home, #about), use the hash-enabled script:

<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  src="https://faurya.com/js/script.hash.js"
></script>

See hashed page paths documentation for more details on tracking hash-based navigation.

Validation rules summary

Goal and event names

Characters: Lowercase letters, numbers, underscores (_), hyphens (-)
Length: Maximum 64 characters
Examples: checkout_started, newsletter-signup, add_to_cart

Custom parameter names

Characters: Lowercase letters, numbers, underscores (_), hyphens (-)
Length: Maximum 64 characters
Conversion: kebab-case attributes automatically converted to snake_case
Example: data-faurya-goal-product-id → product_id

Custom parameter values (any characters)

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

Scroll threshold

Type: Decimal number
Range: 0.0 to 1.0
Default: 0.5
Examples: 0.1 (10%), 0.75 (75%), 1.0 (100%)

Scroll delay

Type: Integer (milliseconds)
Range: 0 or greater
Default: 0 (no delay)
Examples: 1000 (1 second), 5000 (5 seconds)

Troubleshooting

Tracking not working on localhost

Make sure you've added data-allow-localhost="true" to enable local tracking:

<script data-allow-localhost="true" ...></script>

For excluding your own visits on production, see excluding visits documentation.

Custom goals not firing

Check your goal name follows validation rules:

Lowercase only
No spaces or special characters (except _ and -)
Max 64 characters

Cross-domain tracking not working

Verify:

Same data-website-id on all domains
All additional domains listed in data-allowed-hostnames
Users click links between domains (tracking params appended to URLs)

Scroll tracking not triggering

Common issues:

Element not in viewport long enough
Threshold set too high (try lowering from 1.0 to 0.5)
IntersectionObserver not supported (check browser compatibility)

See scroll tracking documentation for detailed troubleshooting and examples.

Getting started guide - Initial setup and installation
Custom goals - Track user actions and events
Scroll tracking - Track element visibility and engagement
Conversion funnels - Analyze multi-step user journeys
Cross-domain tracking - Track users across different domains
Subdomain tracking - Track users across subdomains
Proxy setup guides - Bypass ad blockers with proxying
Excluding visits - Exclude specific traffic from analytics
User identification - Track users across devices and sessions
Revenue attribution - Connect payments to marketing channels

Script configuration

Faurya script configuration

Website ID `data-website-id` (required)

Domain `data-domain` (required)

Allowed Hostnames `data-allowed-hostnames` (optional)

API URL `data-api-url` (optional)

Allow Localhost `data-allow-localhost` (optional)

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

Debug Mode `data-debug` (optional)

Disable Console `data-disable-console` (optional)

Disable Payments `data-disable-payments` (optional)

HTML element attributes

Goal Tracking `data-faurya-goal` (optional)

Goal Parameters `data-faurya-goal-*` (optional)

Scroll Tracking `data-faurya-scroll` (optional)

Scroll Threshold `data-faurya-scroll-threshold` (optional)

Scroll Delay `data-faurya-scroll-delay` (optional)

Scroll Parameters `data-faurya-scroll-*`

Common configuration examples

Development environment

Production with proxy

Cross-domain tracking

Clean production setup

Hash-based navigation tracking

Validation rules summary

Goal and event names

Custom parameter names

Custom parameter values (any characters)

Scroll threshold

Scroll delay

Troubleshooting

Tracking not working on localhost

Custom goals not firing

Cross-domain tracking not working

Scroll tracking not triggering

On this page