---
**📚 Main Documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)
This is an individual endpoint documentation file. For the complete API reference, see the main documentation above.
---
# Embedded click tracking
Track a Hoko short-link click from an owned page without redirecting the visitor.
**Category:** Conversion Tracking
## Overview

Embedded click tracking lets you record a normal Hoko click when a visitor lands on a page you control, without sending that visitor through the short-link redirect first.

Use this when you already know which short link, referral code, partner code, or campaign should receive attribution on the page.

> **Info: Outside the REST OpenAPI contract**
> `/{shortId}/analytics.js` is a browser script endpoint, not an authenticated JSON REST endpoint. It is documented here for implementation guidance but is intentionally outside the OpenAPI REST contract.

## How it works

- Create a dedicated Hoko short link, such as `https://hoko.to/1234`
- Add the embedded analytics script using that short ID
- Hoko verifies that the page requesting the script uses the short-link destination hostname or one of its subdomains
- Hoko returns JavaScript with a short-lived signed capture token
- The script reads or creates a first-party visitor session ID on the page, persists it for 90 days, then sends a signed capture request back to the same script URL
- Hoko records the click only after that signed capture request is verified
- The script first stores any `hoko_id` already present on the page URL
- If the page URL does not include `hoko_id`, Hoko stores the generated embedded click ID as `hoko_id`
- Conversion endpoints can later use `hoko_id` as the `clickId`

> **Info: Redirect attribution wins first**
> The embedded script includes the same page URL behavior as `/analytics.js`, so a `?hoko_id=...` from a normal short-link redirect takes priority. When there is no `hoko_id` on the page URL, the embedded click ID does not overwrite an existing `hoko_id` cookie.

## Add the script

```html
<script src="https://hoko.to/1234/analytics.js?utm_source=site&ref=hero" defer></script>
```

The short ID in the path identifies the Hoko link to track. Query parameters on the script URL are captured with the click.

You do not need to include `https://hoko.to/analytics.js` alongside this script. The embedded script also persists `hoko_id` from normal short-link redirects.

## Host verification

Embedded click tracking only records a click when both the browser `Origin`/`Referer` URL and the current page URL sent by the signed capture request use the short-link destination hostname or a genuine subdomain of it.

For example, a short link that points to `https://example.com/pricing` can be embedded on `https://example.com/...`, `https://www.example.com/...`, `https://shop.example.com/...`, or a deeper subdomain. If the configured destination is `https://shop.example.com/...`, `https://checkout.shop.example.com/...` is allowed, but the parent `https://example.com/...` and sibling `https://blog.example.com/...` are not. An expired link with an expiry destination uses that destination hostname as its boundary.

If the browser does not send a usable `Referer` or `Origin` header, either page URL falls outside the applicable destination boundary, or a URL is invalid, Hoko returns a no-op script and does not create a click. This protects clients from unrelated websites embedding their script and inflating their analytics.

## Supported attribution parameters

| Parameter    | Type   | Required | Location | Description                                                     |
| ------------ | ------ | -------- | -------- | --------------------------------------------------------------- |
| shortId      | string | Yes      | path     | The Hoko short ID in `/{shortId}/analytics.js`.                 |
| utm_source   | string | No       | query    | UTM source to store on the click.                               |
| utm_medium   | string | No       | query    | UTM medium to store on the click.                               |
| utm_campaign | string | No       | query    | UTM campaign to store on the click.                             |
| utm_term     | string | No       | query    | UTM term to store on the click.                                 |
| utm_content  | string | No       | query    | UTM content to store on the click.                              |
| ref          | string | No       | query    | Referral value to store on the click.                           |
| referral     | string | No       | query    | Alternative referral parameter. Used when `ref` is not present. |

## What gets captured

The signed capture request is captured using the same short-link click pipeline as a redirect click. Hoko records request-level attributes such as timestamp, IP-derived location, visitor session ID, user agent, browser, operating system, device, language, browser referrer, and the UTM/referral parameters in the script URL.

For embedded clicks, Hoko stores the browser's full current page URL as the click destination. Before recording the click, the server validates that this URL uses the applicable destination hostname or one of its subdomains.

## Conversion attribution

After the script runs, read the `hoko_id` cookie and pass it to conversion endpoints.

```javascript
const clickId = document.cookie
	.split('; ')
	.find((row) => row.startsWith('hoko_id='))
	?.split('=')[1];

await fetch('https://hoko.to/api/track/lead', {
	method: 'POST',
	headers: {
		Authorization: 'Bearer <API_KEY>',
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
		clickId: clickId ?? '',
		eventName: 'Sign up',
		customerExternalId: 'customer_123',
		customerName: 'John Doe'
	})
});
```

## Behavior notes

- The response is not cached, because each script request creates a short-lived capture token.
- The script does not redirect the visitor.
- A `hoko_id` on the current page URL is stored the same way as `/analytics.js`, including replacing an older cookie value.
- Without a page URL `hoko_id`, the embedded click ID does not overwrite an existing `hoko_id` cookie.
- The script does not mark clicks as QR scans. Use the normal short-link redirect for QR tracking.
- If JavaScript is blocked, the embedded click is not recorded and the `hoko_id` cookie is not stored.
- Browser referrer policies may limit how much of the page URL Hoko receives. The embedded script stores `document.referrer` as the click referrer, and still needs either a `Referer` or `Origin` header for host verification.
- Pass page-specific attribution in the script query string when needed.

---

**Back to main documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)