Source: https://datafa.st/docs/script-configuration
Markdown source: https://datafa.st/docs/script-configuration.md
Description: Complete reference for all data attributes available in the DataFast tracking script to customize tracking behavior.

# DataFast script configuration

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

> New to DataFast? Start with the [installation guide](/docs/getting-started) first.


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

Your unique website identifier from DataFast.

**Example:**
```html
<script
  defer
  data-website-id="dfid_******" // 👈 ✅
  data-domain="your_domain.com"
  src="https://datafa.st/js/script.js"
></script>
```

### Domain `data-domain` (required)

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

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

> See [subdomain tracking documentation](/docs/subdomain-tracking) for tracking across subdomains.

**Example:**
```html
<script
  defer
  data-website-id="dfid_******" 
  data-domain="your_domain.com" // 👈 ✅
  src="https://datafa.st/js/script.js"
></script>
```



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

Comma-separated list of additional domains for cross-domain tracking.
 (comma-separated)
- **Default:** Empty (no cross-domain tracking)
- **Example:** `app.io,shop.example.com`
- **Use case:** Track users across different root domains

**Example:**
```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-allowed-hostnames="app.io,myapp.org" // 👈 ✅
  src="https://datafa.st/js/script.js"
></script>
```

> See [cross-domain tracking documentation](/docs/cross-domain-tracking) 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:**
```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-api-url="https://api.example.com/track" // 👈 ✅ Full URL
  src="https://datafa.st/js/script.js"
></script>
```

**Example with path:**
```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-api-url="/custom-analytics-endpoint" // 👈 ✅ Relative path
  src="https://datafa.st/js/script.js"
></script>
```

> **Note:** DataFast 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, DataFast will fall back to the default endpoint. See [proxy guides](/docs/proxy-guide) for detailed setup instructions.

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

Enable tracking on localhost for development and testing.
 (`"true"` or `"false"`)
- **Default:** `false`
- **Example:** `data-allow-localhost="true"`
- **Use case:** Testing analytics implementation locally

**Example:**
```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-allow-localhost="true" // 👈 ✅
  src="https://datafa.st/js/script.js"
></script>
```

> Tracking is disabled on localhost by default to prevent polluting your production analytics data. See [excluding visits](/docs/excluding-analytics) 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).
 (`"true"` or `"false"`)
- **Default:** `false`
- **Example:** `data-allow-file-protocol="true"`
- **Use case:** Testing with local HTML files

**Example:**
```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-allow-file-protocol="true" // 👈 ✅
  src="https://datafa.st/js/script.js"
></script>
```

### Debug Mode `data-debug` (optional)

Enable debug mode to allow tracking inside iframes.
 (`"true"` or `"false"`)
- **Default:** `false`
- **Example:** `data-debug="true"`
- **Use case:** Testing tracking in embedded contexts

**Example:**
```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-debug="true" // 👈 ✅
  src="https://datafa.st/js/script.js"
></script>
```

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

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

Disable all console logging from DataFast tracker.
 (`"true"` or `"false"`)
- **Default:** `false`
- **Example:** `data-disable-console="true"`
- **Use case:** Clean console logs in production

**Example:**
```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-disable-console="true" // 👈 ✅
  src="https://datafa.st/js/script.js"
></script>
```

### 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`. See [Stripe payment links](/docs/stripe-payment-links) for more details).
 (`"true"` or `"false"`)
- **Default:** `false`
- **Example:** `data-disable-payments="true"`
- **Use case:** When using server-side revenue attribution to avoid duplicate payment events

**Example:**
```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-disable-payments="true" // 👈 ✅
  src="https://datafa.st/js/script.js"
></script>
```

> Manual `window.datafast("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-fast-goal` (optional)

Track clicks on any element as a custom goal.
 (goal name)
- **Rules:** Lowercase letters, numbers, underscores, hyphens, and colons only. Max 64 characters.
- **Example:** `checkout_initiated` or `initiate:checkout`
- **Use case:** Track button clicks, link clicks, or any user interaction

**Example:**
```html
<button data-fast-goal="add_to_cart">Add to Cart</button> // 👈 ✅
```

> See [custom goals documentation](/docs/custom-goals) for more examples.

### Goal Parameters `data-fast-goal-*` (optional)

Add custom parameters to goal events. The parameter name is extracted from the attribute name.
 (parameter value)
- **Naming:** `data-fast-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-fast-goal-product-id="prod_123"`

**Example:**
```html
<button 
  data-fast-goal="product_added" 
  data-fast-goal-product-id="prod_123" // 👈 ✅
  data-fast-goal-product-name="Premium Plan" // 👈 ✅
  data-fast-goal-price="49"> // 👈 ✅
  Add to Cart
</button>
```

In this example, DataFast tracks a goal named `product_added` with parameters:
```javascript
{
  product_id: "prod_123",
  product_name: "Premium Plan",
  price: "49"
}
```

### Scroll Tracking `data-fast-scroll` (optional)

Automatically track when element becomes visible during scrolling.
 (goal name)
- **Default trigger:** Element is 50% visible
- **Rules:** Same as `data-fast-goal` (lowercase, numbers, underscores, hyphens, colons, max 64 chars)
- **Example:** `scroll_to_pricing` or `scroll:pricing`

**Example:**
```html
<section data-fast-scroll="viewed_pricing"> // 👈 ✅
  <h2>Pricing</h2>
  <!-- Pricing content -->
</section>
```

> See [scroll tracking documentation](/docs/scroll-tracking) for detailed examples.

### Scroll Threshold `data-fast-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:**
```html
<section 
  data-fast-scroll="viewed_hero" 
  data-fast-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-fast-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:**
```html
<section 
  data-fast-scroll="read_testimonials" 
  data-fast-scroll-threshold="0.7" // 👈 ✅
  data-fast-scroll-delay="3000">
  <!-- Tracks only if element stays visible for 3 seconds -->
</section>
```

### Scroll Parameters `data-fast-scroll-*`

Add custom parameters to scroll tracking events, similar to `data-fast-goal-*`.
 (parameter value)
- **Naming:** `data-fast-scroll-{parameter-name}` (kebab-case, converted to snake_case)
- **Example:** `data-fast-scroll-section-name="hero"`

**Example:**
```html
<section 
  data-fast-scroll="section_viewed" 
  data-fast-scroll-section-name="testimonials" // 👈 ✅
  data-fast-scroll-section-order="3">
  <!-- Custom parameters help analyze which sections engage users -->
</section>
```

---

## Common configuration examples

### Development environment

Enable tracking on localhost for testing:

```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-allow-localhost="true" // 👈 ✅
  src="https://datafa.st/js/script.js"
></script>
```

### Production with proxy

Proxy script through your domain to bypass ad blockers:

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

> DataFast auto-detects proxied setup. No `data-api-url` needed if you proxy both `/js/script.js` and `/api/events`. See [proxy setup guide](/docs/proxy-guide) for implementation details.

### Cross-domain tracking (optional)  

Track users across multiple domains:

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

> Use the same configuration on all tracked domains.

### Clean production setup

Minimal console output in production:

```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  data-disable-console="true" // 👈 ✅
  src="https://datafa.st/js/script.js"
></script>
```

### Hash-based navigation tracking

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

```html
<script
  defer
  data-website-id="dfid_******"
  data-domain="your_domain.com"
  src="https://datafa.st/js/script.hash.js" // 👈 ✅
></script>
```

> See [hashed page paths documentation](/docs/hashed-page-paths-tracking) for more details on tracking hash-based navigation.

---

## Validation rules summary

### Goal and event names
- **Characters:** Lowercase letters, numbers, underscores (_), hyphens (-), colons (:)
- **Length:** Maximum 64 characters
- **Examples:** `checkout_started`, `newsletter-signup`, `add_to_cart`, `initiate:checkout`

### Custom parameter names
- **Characters:** Lowercase letters, numbers, underscores (_), hyphens (-)
- **Length:** Maximum 64 characters
- **Conversion:** kebab-case attributes automatically converted to snake_case
- **Example:** `data-fast-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:

```html
<script data-allow-localhost="true" ... ></script> // 👈 ✅   
```

> For excluding your own visits on production, see [excluding visits documentation](/docs/excluding-analytics).

### 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:
1. Same `data-website-id` on all domains
2. All additional domains listed in `data-allowed-hostnames`
3. 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](/docs/scroll-tracking) for detailed troubleshooting and examples.

---

## Related documentation

- **[Getting started guide](/docs/getting-started)** - Initial setup and installation
- **[Custom goals](/docs/custom-goals)** - Track user actions and events
- **[Scroll tracking](/docs/scroll-tracking)** - Track element visibility and engagement
- **[Conversion funnels](/docs/conversion-funnels)** - Analyze multi-step user journeys
- **[Cross-domain tracking](/docs/cross-domain-tracking)** - Track users across different domains
- **[Subdomain tracking](/docs/subdomain-tracking)** - Track users across subdomains
- **[Proxy setup guides](/docs/proxy-guide)** - Bypass ad blockers with proxying
- **[Excluding visits](/docs/excluding-analytics)** - Exclude specific traffic from analytics
- **[User identification](/docs/user-identification)** - Track users across devices and sessions
- **[Revenue attribution](/docs/revenue-attribution-guide)** - Connect payments to marketing channels