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.

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

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

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