# JavaScript events
Source: https://docs.luriart.com/reference/javascript-events
Plain text: https://docs.luriart.com/reference/javascript-events.txt

Precise reference for window.luria.convert, what the snippet tracks automatically, auto-detected conversions, timing, and safe call patterns.

This page assumes you are comfortable with JavaScript. For the bigger picture see the [API reference](/reference/api).

## `window.luria.convert(goal, value)`
Records one conversion for the current visitor and attributes it to whatever variant they saw earlier in the session.

```js
window.luria.convert("purchase", 129.0);   // monetary goal
window.luria.convert("lead");              // non-monetary goal, value omitted
window.luria.convert("booked_call", null); // same as above
```

### Parameters
| Name    | Type                     | Default        | Notes                                                                                                                                                                                                       |
| ------- | ------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `goal`  | string                   | `"conversion"` | A short label for what happened. Common values: `"purchase"`, `"lead"`, `"signup"`, `"booked_call"`, `"download"`, `"trial"`. Use the same string every time for the same goal; the dashboard groups by it. |
| `value` | number, null, or omitted | `null`         | Monetary value of this conversion in your store's currency. Plain number, no currency symbol, no thousands separators.                                                                                      |

There is no currency parameter. Currency is inferred from your site settings in the dashboard.  If you sell in several currencies, convert to your store's base currency before calling.

Returns `undefined`. Never throws. If Luria is not running (consent not granted, blocked, failed to load), `window.luria` does not exist, so guard your call (see Timing below).

### Where to call it
On the page that only renders after the conversion happened: the order confirmation, the thank-you page after a form, the "you're booked" screen. Calling it on a button click counts intent, not outcomes, and will overstate your results.

### Call it once per conversion
Each call is counted. On non-Shopify sites, if the visitor reloads your thank-you page and your code runs again, you may double count. Guard with your own order or lead id:

```js
(function () {
  var orderId = "ORDER_ID_FROM_YOUR_TEMPLATE";
  var key = "my_conv_" + orderId;
  if (localStorage.getItem(key)) return;
  localStorage.setItem(key, "1");
  if (window.luria) window.luria.convert("purchase", 129.0);
})();
```

Luria's own auto-detection (below) already applies this kind of guard. Your manual call is separate, so add your own.

## Auto-detected conversions
You do not always need to call `convert`.

**Non-Shopify sites.** The snippet fires a conversion automatically, once per order, when the page path matches any of:

* `/thank-you`
* `/thank_you`
* `/orders/<id>` (an order token of 6 or more characters)

It keys the guard on the order or checkout token in the URL, so a reload of the same confirmation page does not count twice. The auto-detected goal is recorded as `"auto"` with no value. If you want a value attached, call `convert` yourself on that page; both will be recorded, so pick one approach per page.

**Shopify.** Purchases are counted by the Luria app (checkout pixel plus order webhook), never by the snippet. The snippet does not auto-convert on Shopify, and you do not need to call `convert` for purchases. Calling it anyway records an extra, non-purchase event under the goal you pass, which is harmless but unnecessary.  Use `convert` on Shopify only for non-purchase goals you care about (for example a quiz completion or a newsletter signup).

## What the snippet tracks automatically
Once the visitor is allowed to be tracked (see [Consent](/reference/consent)), the snippet records:

| Event            | When                                                                                                        |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| Session start    | Once per visitor per day: device class (mobile/desktop), referrer, UTM source/medium/campaign.              |
| Pageview         | Every page load.                                                                                            |
| Click            | Clicks on links, buttons, and elements with `role="button"`, with up to 60 characters of the visible label. |
| Form start       | The first time a visitor focuses any input, textarea, or select on a page. No values.                       |
| Checkout step    | A pageview whose path contains `checkout` or `payment`.                                                     |
| Variant exposure | Which test and which version the visitor was shown.                                                         |
| Conversion       | From `convert`, from auto-detection, or (Shopify) from the app.                                             |

Events are batched and sent in the background, about 1.5 seconds after the last event and on page unload. Nothing blocks navigation.

## What it never collects
* Keystrokes or typed form values (it records that a form was started, not what was entered).
* Passwords, card numbers, or any checkout field contents.
* Precise location, device fingerprints, or cross-site identifiers.
* Anything at all when Global Privacy Control or Do Not Track is on.

Where session recordings are enabled, inputs are masked by default. More on [Data and privacy](/reference/data-and-privacy).

## Timing
The snippet is `async`, so `window.luria` may not exist yet when your own inline code runs, especially on a fast confirmation page. Two safe patterns:

**Pattern 1: guard and retry briefly.**

```js
(function fire(tries) {
  if (window.luria) return window.luria.convert("purchase", 129.0);
  if (tries > 0) setTimeout(function () { fire(tries - 1); }, 250);
})(20); // tries for ~5 seconds, then gives up quietly
```

**Pattern 2: call from a deferred script.** If your conversion code lives in a `<script defer>` or runs on `DOMContentLoaded`, the snippet has normally finished by then; still wrap the call in `if (window.luria)`.

Never block your page waiting for `window.luria`. If Luria is blocked or declined, it will never appear, and that is by design.

## Single-page apps
Variants are fetched for the path at load time. If your site changes routes without a full page load (React, Vue, Next.js client navigation), new routes do not automatically fetch their own variants or fire a pageview.  Conversions via `convert` work fine anywhere. If you run a test on a route that is only ever reached client-side, tell support and they can advise.

## Listening to variant exposures
Some merchants want to send "visitor saw version B" into their own analytics (GA4, Mixpanel, a data warehouse). There is no public, supported hook for this yet.  The `window.luria.exposure` method you will see in the source is called by the snippet and is not a subscription point. Do not wrap or override it; doing so can break attribution. A documented callback is planned.  For now, compare results inside the Luria dashboard. See [Reading results](/dashboard/reading-results).

## Quick checklist
* Snippet in `<head>` with the right Site ID.
* `convert` called on the confirmation page, guarded with `if (window.luria)`.
* One call per conversion, deduped on your own order id if the page can reload.
* On Shopify, skip `convert` for purchases; the app handles them.

## Next steps
  - [API reference](/reference/api)
  - [Verify your install](/install/verify-install)
  - [Set your goal](/train/goals)
  - [Snippet not firing](/troubleshooting/snippet-not-firing)