JavaScript API - GhostlyX

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.

JS 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');

JS 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. optional

Example

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

JS 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');

JS 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.

Ready to start tracking events?

Get started free REST API reference