Script Configuration
Complete reference for all tracking script configuration options.
Script Configuration
The EngageTrack tracking script is configured entirely through HTML data-* attributes on the <script> tag. No JavaScript configuration file is needed.
Basic Script Tag
<script
defer
data-site-id="YOUR_SITE_ID"
src="https://cdn.engagetrack.net/sdk.js"
></script>Script Attributes Reference
| Attribute | Type | Default | Description |
|---|---|---|---|
data-site-id | string | — | Required. Your site ID from the EngageTrack dashboard. Also accepts data-site as an alias. |
data-api | string | https://api.engagetrack.net/api/v1/event | Custom event endpoint URL. Use this when proxying the SDK through your own domain. |
data-outbound | "true" / "false" | "true" | Track clicks on links to external domains. |
data-downloads | "true" / "false" | "true" | Track file download clicks (pdf, doc, zip, exe, etc.). |
data-forms | "true" / "false" | "true" | Track form submissions. Auth-related forms are automatically excluded. |
data-phone | "true" / "false" | "true" | Track clicks on tel: phone links. |
data-hash | "true" / "false" | "false" | Enable hash-based routing mode. When "true", the full URL including #hash is tracked as the page path. |
data-persistence | "memory" / "storage" | "memory" | Tracking persistence mode. "memory" (default): zero device storage — session ID lives in a JS variable, lost on tab close. No consent banner needed. "storage": persistent visitor ID in localStorage, session in sessionStorage. Enables multi-day visitor tracking but requires a consent banner in the EU. |
data-debug | "true" / "false" | "false" | Log all tracking events to the browser console. |
data-allowed-hostnames | string | "" | Comma-separated list of hostnames for cross-domain tracking. Requires data-persistence="storage". |
data-exclude | string | "" | Comma-separated list of path patterns to exclude from pageview tracking (e.g., /dashboard/*,/admin/*). Supports * wildcards. Custom events and purchases are never excluded. |
The data-site-id attribute is required. Without it, the script will not
initialize and will log a warning to the console.
HTML Element Attributes
These attributes can be added to any HTML element to trigger tracking behavior.
Goal Tracking
| Attribute | Description |
|---|---|
data-goal | Fires a custom goal event when the element is clicked. Value is the goal name (lowercase, numbers, hyphens, underscores, max 64 chars). |
data-goal-* | Attach custom properties to the goal. The suffix becomes the property name (kebab-case is converted to snake_case). Max 10 properties per goal. |
<!-- Simple goal -->
<button data-goal="signup">Create Account</button>
<!-- Goal with properties -->
<button
data-goal="add-to-cart"
data-goal-product="pro-plan"
data-goal-price="49"
>
Add to Cart
</button>Goal names must match the pattern [a-z0-9_-] and be at most 64
characters. Property values are truncated to 255 characters.
Scroll Tracking
| Attribute | Description |
|---|---|
data-scroll | Fires a custom event when the element scrolls into view (50% visibility threshold). Value is the goal name. Each goal fires only once per page load. |
<!-- Track when a user scrolls to the pricing section -->
<section data-scroll="viewed-pricing">
<h2>Pricing</h2>
<!-- ... -->
</section>
<!-- Track when a user sees the CTA at the bottom -->
<div data-scroll="reached-bottom-cta">
<button>Get Started</button>
</div>Scroll tracking uses the IntersectionObserver API. Goals reset on SPA
navigation, so they can fire again on the next page.
Configuration Examples
Development Setup
Track localhost traffic with debug logging enabled:
<script
defer
data-site-id="YOUR_SITE_ID"
data-debug="true"
src="https://cdn.engagetrack.net/sdk.js"
></script>Open your browser console to see all events being sent in real time.
Production with Proxy
Serve the SDK through your own domain to bypass ad blockers:
<script
defer
data-site-id="YOUR_SITE_ID"
data-api="https://yourdomain.com/api/event"
src="https://yourdomain.com/js/script.js"
></script>See the Proxy Setup guide for full instructions.
Persistent Tracking (Storage Mode)
Enable multi-day visitor tracking. Requires a consent banner in the EU:
<script
defer
data-site-id="YOUR_SITE_ID"
data-persistence="storage"
src="https://cdn.engagetrack.net/sdk.js"
></script>Storage mode writes a visitor ID to localStorage and session data to
sessionStorage. Under the ePrivacy Directive, this requires informed
consent before the script loads for EU visitors.
Cross-Domain Tracking
Track visitors across multiple domains as a single session. Requires data-persistence="storage":
<script
defer
data-site-id="YOUR_SITE_ID"
data-persistence="storage"
data-allowed-hostnames="checkout.example.com,app.example.com"
src="https://cdn.engagetrack.net/sdk.js"
></script>See the Cross-Domain Tracking guide for setup details.
Hash-Based Navigation
For apps using hash-based routing (e.g., /#/dashboard, /#/settings):
<script
defer
data-site-id="YOUR_SITE_ID"
data-hash="true"
src="https://cdn.engagetrack.net/sdk.js"
></script>Minimal Tracking
Disable all automatic tracking except pageviews:
<script
defer
data-site-id="YOUR_SITE_ID"
data-outbound="false"
data-downloads="false"
data-forms="false"
data-phone="false"
src="https://cdn.engagetrack.net/sdk.js"
></script>