# askbowtie tracking reference
Machine-friendly reference for the askbowtie tracker. Everything here is current and verified against the shipped tracker (v7.3). Human-readable version: https://askbowtie.com/docs/
## Install
One tag, in ``, on every page:
```html
```
The `data-token` shown is a placeholder. Yours is unique to your site and is how askbowtie
confirms the site is yours, so copy the real line from your dashboard at
https://askbowtie.com/app/ . Without it the tracker still sends events, but the site stays
unverified and MCP returns nothing for it.
`async`, not `defer`: the tracker captures errors that happen during page parse. Never version the URL. The domain must be registered at askbowtie.com or the tracker disables itself.
## Tracked automatically (zero config)
| Signal | Event types |
|--------|-------------|
| Page views and sessions | `page_load`, `session_start`, `page_hidden` |
| Clicks | `click`, `external_link_click`, `rage_click` |
| Forms | `form_submit` |
| Errors | `console_error`, `resource_error`, `network_error`, `csp_violation` |
| Performance | `web_vitals` (LCP, CLS, INP, TTFB) |
| Engagement | `page_hidden` carries engaged time and scroll depth: the furthest scroll % reached (0-100), surfaced per page in analytics |
UTM parameters and ad click IDs (gclid, msclkid, fbclid) are captured on landing and survive internal navigation. No cookies. No PII: input values are never read, query-string PII is redacted.
## Public API
The API lives at `window.bowtie` after the script loads. The script is async, so guard calls that could run before load with optional chaining: `window.bowtie?.track(...)`. In user-action handlers (clicks, submits) the tracker is always ready.
### Custom events
```js
bowtie.track(eventType, data?)
bowtie.track('signup_started', { source: 'homepage_cta' });
bowtie.track('plan_selected', { plan: 'agency', seats: 5 });
```
`eventType` is a string you choose. `data` is a flat object of context, queryable later through MCP.
### Conversions and revenue
```js
bowtie.converted(goalName, details?)
bowtie.converted('purchase', { value: 99.00, currency: 'USD', transaction_id: 'ord_1842' });
bowtie.converted('lead_captured', { source: 'contact_form' });
bowtie.converted('trial_started');
```
| Field | Type | Notes |
|-------|------|-------|
| `value` | number | Revenue or goal value. Optional. |
| `currency` | string | ISO code, default `USD` |
| `transaction_id` | string | Dedupe key: the same conversion never counts twice |
| `pixels` | boolean or string | Also fire to connected ad platforms. `true` = primary Google Ads label, `'secondary'` = secondary label, default off |
| `email`, `phone` | string | Enhanced conversions, hashed by gtag before leaving the page. Only used when `pixels` fires |
Any other keys you pass are stored with the event.
### Application errors
```js
bowtie.error(code, details?)
bowtie.error('payment_declined', { reason: 'insufficient_funds', amount: 99.00 });
bowtie.error('validation_failed', { field: 'email' });
```
For errors your own code catches. Uncaught JS errors, failed resources, and failed fetches are captured automatically.
### Guardrails
```js
bowtie.guardrail(code, details?)
bowtie.guardrail('rate_limited', { endpoint: '/api/checkout', limit: '10/min' });
bowtie.guardrail('geo_blocked', { country: 'XX' });
```
Intentional blocks that are not failures: rate limits, quota, access denied, feature flags. Kept separate from errors so error rates stay honest.
### Utilities
```js
bowtie.getSessionId() // current session id: REQUIRED for server-side conversions, see Rule 2
bowtie.flush() // send the queue now (before a hard navigation)
bowtie.debug(true) // tag this tab's events debug:true; persists across pages
bowtie.debug(false) // off
```
### Legacy
`window.itbroke` is an alias of `window.bowtie`. Sites migrated from itbroke.dev keep working unchanged.
## Page roles (`data-askbowtie-tag`)
Declare what a page IS, in the page itself:
```html
```
This is a **tag, not an event**: no API call, nothing to fire. bowtie reads the marker on every crawl (served HTML, so even zero-traffic pages classify) and on every `page_load` from the tracker. Analytics can then be grouped and filtered by role instead of slug: "how does editorial convert vs commercial" is one question, not a scan of every page.
| Rule | Detail |
|------|--------|
| Value | A free lowercase slug you choose: `editorial`, `commercial`, `conversion`, `lander`, … Keep roles coarse (3-6 that mean something). |
| Read on | Every crawl and every `page_load`. Ship a new page with the marker and it classifies itself, no reminders. |
| Precedence | manual > declared > suggested. A tag set explicitly (via the `tag_pages` MCP tool) wins over the page's marker. Auto-detection only **suggests** roles for untagged pages and never overwrites anything. |
| Where it surfaces | `get_page_types` (role rollup + untyped bucket + suggestions), `get_top_pages {type}`, and the Type column and filter on the app's analytics page. |
Put the marker in your layout/template once and every page using that template carries the role forever. For legacy sections you won't re-template, an agent can bulk-assign with `tag_pages {tag, match: '/blog/'}` over MCP.
## Sections (`data-askbowtie-section`)
Name the regions of a page, and analytics can split that page's viewers by which section they clicked: share of viewers per section, plus how each group converted afterwards.
```html