JavaScript API

Trigger custom events, track goals, and push metadata from your front-end code using the window.ghostlyx() function exposed by the tracking script.

Prerequisites

The JavaScript API is only available after the GhostlyX tracking script has loaded. Add the snippet to the <head> of every page:

HTML

<script
  src="https://ghostlyx.com/js/script.min.js"
  data-site-id="YOUR_SITE_ID"
  defer
></script>

Find your data-site-id in the site settings inside your dashboard.

ghostlyx(name) Track a custom event

Fires a named custom event tied to the current page. Events appear in your dashboard immediately under Custom Events, broken down by page, referrer, and country.

Parameters

  • name string The event name. Use descriptive, human-readable names such as "Signup" or "Clicked CTA".

Example

// Track a named event
ghostlyx('Signup');

ghostlyx(name, props) Track a custom event with properties

Same as the basic event call, but attaches a flat object of metadata. Properties are stored as JSON and are visible in the dashboard when you inspect an individual event.

Parameters

  • name string The event name.
  • props object A plain key/value object. Values must be strings, numbers, or booleans. Nested objects are not supported.

Example

// Track a purchase with metadata
ghostlyx('Purchase', {
  plan:    'pro',
  revenue: 29,
});

ghostlyx('opt-out') Opt the visitor out of tracking

Sets a ghostlyx_opt_out flag in localStorage. Once set, no pageviews or events will be sent for this visitor in this browser until they opt back in. The flag persists across sessions.

Example

// Called from a privacy settings UI
ghostlyx('opt-out');

ghostlyx('opt-in') Re-enable tracking for the visitor

Removes the ghostlyx_opt_out flag from localStorage, restoring normal pageview and event tracking.

Example

// Restore tracking when the user opts back in
ghostlyx('opt-in');

Auto-tracking extensions

Enable these optional behaviours by adding data-* attributes to the script tag. Each extension fires a named event automatically without writing any JavaScript.

data-outbound-links="true" Outbound link clicks

Fires an Outbound Link: Click event whenever a visitor clicks a link pointing to a different hostname. The target URL is included as a property.

<script
  src="https://ghostlyx.com/js/script.min.js"
  data-site-id="YOUR_SITE_ID"
  data-outbound-links="true"
  defer
></script>

data-file-downloads="true" File download clicks

Fires a File Download event when a visitor clicks a link to a downloadable file. Tracked extensions include pdf, zip, xlsx, docx, mp4, and more. The filename is included as a property.

<script
  src="https://ghostlyx.com/js/script.min.js"
  data-site-id="YOUR_SITE_ID"
  data-file-downloads="true"
  defer
></script>

data-form-submissions="true" Form submit events

Fires a Form Submission event on every form submit. The form is identified by its id, name, or action attribute (whichever is present first).

<script
  src="https://ghostlyx.com/js/script.min.js"
  data-site-id="YOUR_SITE_ID"
  data-form-submissions="true"
  defer
></script>

Privacy behaviour

The script will silently skip all tracking and expose a no-op window.ghostlyx() function when any of the following conditions are true:

  • Global Privacy Control navigator.globalPrivacyControl === true The visitor's browser or extension has set the GPC signal.
  • Do Not Track navigator.doNotTrack === "1" The visitor has enabled the legacy Do Not Track browser preference.
  • Explicit opt-out ghostlyx('opt-out') The visitor called the opt-out API or visited the /gx-opt-out page.