# 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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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.