---
**📚 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.

## 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 is on the same hostname as the short-link destination
- 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 the page requesting the script and the signed capture request are hosted on the same hostname as the short-link destination. For example, a short link that points to `https://example.com/pricing` can be embedded on `https://example.com/...` or `https://www.example.com/...`, but not on another website.

If the browser does not send a `Referer` or `Origin` header, or if the hostname does not match, 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, 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. The server still validates that this URL's hostname matches the configured short-link destination hostname before recording the click.

## 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 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)