Skip to main content

Install the Tracking Script

Add the Ovyxa tracking script to your website to start collecting analytics data.

Basic Installation​

Add this script tag to the <head> section of every page:

<script async src="https://ingest.ovyxa.com/js/script.js" data-domain="yourdomain.com"></script>

Replace yourdomain.com with your actual domain (e.g., example.com). This must match the domain you added in your Ovyxa dashboard.

Full HTML Example​

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>My Website</title>

    <!-- Ovyxa Analytics -->
    <script async src="https://ingest.ovyxa.com/js/script.js" data-domain="yourdomain.com"></script>
  </head>
  <body>
    <!-- Your content -->
  </body>
</html>

Script Attributes Reference​

All configuration is done via data-* attributes on the script tag. Only data-domain is required.

Required​

AttributeDescription
data-domainYour site domain (must match the domain in your Ovyxa dashboard)

Routing & Behavior​

AttributeDescription
data-apiCustom API endpoint URL. Used when proxying through your own domain (e.g., data-api="/api/event")
data-hash-modeEnable hash-based SPA routing. Tracks /#/page changes as separate pageviews
data-allowed-hostnamesComma-separated whitelist of hostnames to track. Events from other hostnames are ignored

Privacy & Cookies​

AttributeDescription
data-cookielessDisable cookies entirely. Uses localStorage for visitor ID and server-side session hashing. No cookie consent banner needed
data-disable-paymentsSkip automatic payment link detection (Stripe session_id / checkout_session_id, LemonSqueezy order_id, Polar checkout_id)

Extensions​

AttributeDescription
data-engagementLoad the engagement tracking extension. Tracks time-on-page and active engagement
data-outbound-linksTrack clicks on outbound links (links to external domains)
data-tagged-eventsTrack events via HTML attributes (data-ovyxa-event="EventName") without writing JavaScript
data-scroll-depthTrack scroll milestones (25%, 50%, 75%, 100%)

Development & Debugging​

AttributeDescription
data-allow-localhostTrack events on localhost. By default, localhost is excluded
data-allow-file-protocolTrack events on file:// pages
data-debugEnable console logging. Logs every event to the browser console for debugging
data-disable-consoleSuppress all Ovyxa console messages (overrides data-debug)

Example with Multiple Attributes​

<script
  async
  src="https://ingest.ovyxa.com/js/script.js"
  data-domain="yourdomain.com"
  data-cookieless
  data-outbound-links
  data-tagged-events
  data-engagement
></script>

Script Extensions​

Extensions add optional tracking capabilities. Enable them with the corresponding data-* attribute.

Engagement Tracking (data-engagement)​

Tracks active time-on-page. Reports how long visitors actively engage with your content (scrolling, clicking, typing), not just how long the tab is open.

Automatically tracks clicks on links pointing to external domains. Events appear as Outbound Link: Click in your dashboard with the destination URL as a property.

Tagged Events (data-tagged-events)​

Track events directly from HTML without writing JavaScript:

<button data-ovyxa-event="SignupClicked">Sign Up</button>
<a href="/pricing" data-ovyxa-event="PricingViewed">View Pricing</a>

Scroll Depth (data-scroll-depth)​

Tracks how far visitors scroll on each page. Reports scroll milestones at 25%, 50%, 75%, and 100%.

The tracking script automatically detects payment checkout URLs and captures the session/order ID. This enables revenue attribution — connecting a pageview to a completed payment.

Supported URL parameters (checked in priority order):

ParameterProvider
session_idStripe
checkout_session_idStripe
order_idLemonSqueezy
checkout_idPolar

When a visitor lands on a page with one of these URL parameters (e.g., your "thank you" page after checkout), the tracking script sends the ID to the ingest API. The API then matches it to a payment via webhooks to attribute revenue to the original traffic source.

To disable this behavior, add data-disable-payments to the script tag.

Proxy Auto-Detection​

When you proxy the tracking script through your own domain (e.g., via Caddy, Nginx, or Next.js rewrites), the script automatically detects that it's being served from the same origin as your website and sends events to a relative /e path instead of a cross-origin URL.

This means no data-api attribute is needed when both the script and the event endpoint are proxied through the same domain. CORS is avoided entirely.

SetupEndpoint Used
Script from ingest.ovyxa.com, page on example.comhttps://ingest.ovyxa.com/e (cross-origin)
Script proxied through example.com/js/script.js/e (same-origin, auto-detected)
data-api="/api/event" set explicitly/api/event (always takes priority)

If you need the event endpoint at a different path than /e, use data-api to override.

JavaScript API​

The tracking script exposes a global window.ovyxa() function for programmatic event tracking.

Track a Custom Event​

window.ovyxa('event', 'SignupCompleted')

Track an Event with Properties​

window.ovyxa('event', 'PurchaseCompleted', {
  plan: 'pro',
  amount: '99.00',
  currency: 'EUR'
})

Track a Manual Pageview​

window.ovyxa('pageview')

Useful for SPAs where you need to manually trigger pageview tracking after client-side navigation.

Identify a Visitor​

window.ovyxa('identify', {
  name: 'Jane Smith',
  email: 'jane@example.com',
  plan: 'pro'
})

Associates the current visitor with a named profile. See User Identification for details.

Queue Pattern​

If your code runs before the tracking script loads, events are automatically queued:

// This works even before script.js loads
window.ovyxa = window.ovyxa || function() {
  (window.ovyxa.q = window.ovyxa.q || []).push(arguments)
}

window.ovyxa('event', 'EarlyEvent')

Script Size​

The base script is < 2KB gzipped. Extensions add minimal overhead. The script is loaded with async so it never blocks page rendering.

Content Security Policy (CSP)​

If your site uses a Content Security Policy, add these directives:

script-src 'self' https://ingest.ovyxa.com;
connect-src 'self' https://ingest.ovyxa.com;

If you're using a proxy, point these at your proxy domain instead.

Where to Add the Script​

CMS Platforms​

For WordPress, Webflow, Squarespace, and other CMS platforms — look for a "Custom Code" or "Header Scripts" section. See our Integrations section for platform-specific guides.

Single Page Applications​

The script automatically tracks client-side navigation via the History API. For framework-specific setup:

Testing​

After adding the script:

  1. Open your website in a browser
  2. Open DevTools → Network tab
  3. Look for a request to ingest.ovyxa.com/js/script.js
  4. Navigate to a page — look for a POST to /e
  5. Check your Ovyxa dashboard for incoming data

Use data-debug during development to see all tracked events in the browser console.

See Verify Installation for a detailed testing guide.

Troubleshooting​

Script not loading?

  • Check the script URL is exactly https://ingest.ovyxa.com/js/script.js
  • Verify data-domain matches your domain in the Ovyxa dashboard
  • Check for CSP headers blocking the script
  • Check if an ad blocker is blocking the request (consider proxying)

No data in dashboard?

  • Wait 1-2 minutes for data to appear
  • Verify the script is in the <head> section (not <body>)
  • Check the browser console for JavaScript errors
  • Ensure you're not on localhost (add data-allow-localhost for dev)

Events firing but not showing?

  • Check the site domain matches exactly
  • Verify bot filtering isn't flagging your requests
  • Check your site's shields/exclusion settings