Embedded click tracking

Track a Hoko short-link click from an owned page without redirecting the visitor.

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

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

Code 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	Description
`shortId` (path)	string	Yes	The Hoko short ID in `/{shortId}/analytics.js`.
`utm_source` (query)	string	No	UTM source to store on the click.
`utm_medium` (query)	string	No	UTM medium to store on the click.
`utm_campaign` (query)	string	No	UTM campaign to store on the click.
`utm_term` (query)	string	No	UTM term to store on the click.
`utm_content` (query)	string	No	UTM content to store on the click.
`ref` (query)	string	No	Referral value to store on the click.
`referral` (query)	string	No	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.

Code 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.