Skip to content
Developers

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:

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

Methods

MethodDescription
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 {}