JavaScript SDK
Reference for the window.invoker API exposed by the tracking script.
Installation
The SDK is the tracking script itself — there is no npm package to install. Add the snippet to your site's <head> and replace YOUR_SITE_ID with the Site ID from your site settings:
<script defer src="https://cdn.invoker.app/script.js" data-site="YOUR_SITE_ID"></script>
All configuration attributes (data-spa, data-auto, data-honor-dnt, domain filters, auto-tracking toggles) are documented in the Tracking Script reference.
defer, window.invoker is undefined until it has run, and it is an empty object if the Site ID is missing or invalid. Always call it defensively: window.invoker?.trackEvent?.('signup').Methods
| Method | Description |
|---|---|
invoker.trackPageview({ url?, referrer?, title? }) | Record a pageview. Called automatically on load unless data-auto="false". |
invoker.trackEvent(name, payload?, title?) | Record a custom event with an optional object of properties. |
invoker.trackGoal(code, cents?, title?) | Record a goal conversion. The optional value is an integer in cents. |
invoker.trackRevenue({ amount, currency?, transaction_id?, items? }) | Record a purchase. amount is in currency units (e.g. 49.99) and must be > 0; currency defaults to USD. |
invoker.trackOutboundLink(url, text?) | Manually record an outbound link click (sent as an outbound_link event). |
invoker.trackDownload(url, filename?) | Manually record a file download (sent as a file_download event). |
invoker.track404(path?) | Manually record a 404 (sent as a 404_error event). Useful for SPA not-found routes. |
invoker.blockTrackingForMe() / enableTrackingForMe() | Opt the current browser out of / back into tracking. Stores a blockInvokerTracking flag in localStorage and shows a browser alert(). |
invoker.isTrackingEnabled() | Returns false if this browser won't be tracked (opt-out, DNT with data-honor-dnt, or a script domain filter). |
invoker.getClientId() / getSessionId() | Return the current visitor and session identifiers in Enhanced mode (for debugging). Return null in Privacy mode, where nothing is stored in the browser. |
invoker.setSite(siteId) | Switch the Site ID used for subsequent hits. |
Custom events
// Simple event
window.invoker?.trackEvent('signup_button_clicked')
// Event with properties
window.invoker?.trackEvent('plan_selected', {
plan: 'starter',
billing: 'yearly',
location: 'pricing_page'
})See Events for naming conventions and more examples.
Goals
// Goal without a value
window.invoker?.trackGoal('newsletter_signup')
// Goal with a value in cents ($149.99)
window.invoker?.trackGoal('purchase', 14999)See Goals.
Revenue
window.invoker?.trackRevenue({
amount: 149.99, // currency units, not cents
currency: 'EUR', // optional, defaults to USD
transaction_id: 'ORD-1042',
items: [{ id: 'SKU-123', name: 'Pro plan', price: 149.99, quantity: 1 }]
})See Revenue tracking.
Manual pageviews
// Current page
window.invoker?.trackPageview()
// Custom URL / title (e.g. virtual pages in a multi-step form)
window.invoker?.trackPageview({ url: '/checkout/step-2', title: 'Checkout – Shipping' })Automatic events
Unless disabled with the matching attribute, the script records these events on its own: outbound_link (clicks on links to other hostnames), file_download (links to common file types) and 404_error (pages whose title contains "404" / "not found", or that set <meta name="invoker-status" content="404">).
Single-page applications
Client-side route changes are not tracked unless you opt in. Add data-spa="history" for pushState routers (Next.js, React Router, Vue Router, SvelteKit, Angular), data-spa="hash" for hash routing, or data-spa="auto".
Next.js (App Router)
// app/layout.tsx
import Script from 'next/script'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Script
src="https://cdn.invoker.app/script.js"
data-site={process.env.NEXT_PUBLIC_INVOKER_SITE_ID}
data-spa="history"
strategy="afterInteractive"
/>
</body>
</html>
)
}Manual SPA tracking
If you prefer full control, load the script with data-auto="false" (and without data-spa), then call trackPageview() yourself on every route change:
// React Router
import { useEffect } from 'react'
import { useLocation } from 'react-router-dom'
export function PageviewTracker() {
const location = useLocation()
useEffect(() => {
window.invoker?.trackPageview?.()
}, [location.pathname])
return null
}Consent and opt-out
In Privacy mode (the default) the script stores nothing on the visitor's device, so it's designed to run without a consent banner and you can load it normally. In Enhanced mode (data-mode="enhanced") it stores a random visitor ID and session ID in localStorage, which needs consent in the EU/UK. In that case, only load the script once the visitor has agreed:
function loadInvoker() {
if (document.querySelector('script[data-site]')) return
const s = document.createElement('script')
s.src = 'https://cdn.invoker.app/script.js'
s.defer = true
s.dataset.site = 'YOUR_SITE_ID'
s.dataset.mode = 'enhanced'
document.head.appendChild(s)
}
// Call from your consent banner's "accept" handler
onConsentGranted(loadInvoker)To let visitors opt out on a site where the script is already loaded, call window.invoker.blockTrackingForMe() (and enableTrackingForMe() to undo). Both show a confirmation alert(). See our Cookie Policy and Privacy Policy for what is stored.
TypeScript
// invoker.d.ts
// Flat object; booleans and nested objects aren't stored as properties
type InvokerPayload = Record<string, string | number>
interface InvokerApi {
siteId: string
trackPageview(params?: { url?: string; referrer?: string; title?: string }): void
trackEvent(name: string, payload?: InvokerPayload, title?: string): void
trackGoal(code: string, cents?: number, title?: string): void
trackRevenue(data: {
amount: number
currency?: string
transaction_id?: string
items?: Array<Record<string, unknown>>
}): void
trackOutboundLink(url: string, text?: string): void
trackDownload(url: string, filename?: string): void
track404(path?: string): void
blockTrackingForMe(): void
enableTrackingForMe(): void
isTrackingEnabled(): boolean
getClientId(): string | null
getSessionId(): string | null
setSite(siteId: string): void
}
declare global {
interface Window {
// Undefined before the script loads; empty if the Site ID is missing
invoker?: Partial<InvokerApi>
}
}
export {}