Reference
SDK API
The window.signals surface and init options.
The tag exposes a global window.signals object once loaded.
Methods
| Method | Signature | Notes |
|---|---|---|
init | init(options?) | Called automatically on load unless data-no-init="true". Idempotent - the second call is a no-op |
track | track(event, properties?) | Queue an event (batched; flushed every 10s, at 20 events, and on page hide) |
trackFromTarget | trackFromTarget(event, target, properties?) | Like track, but honors data-signals-no-capture on the target's ancestors |
identify | identify(distinctId, properties?) | Switch to a known-user id and send $identify. Include email/phone in properties to power identity stitching |
alias | alias(newId) | Record an alias then switch the distinct id |
group | group(type, key, properties?) | Send $groupidentify |
reset | reset() | Clear identity + super properties and mint a fresh anonymous id (use on logout) |
optOut / optIn | optOut() / optIn() | Persistently disable/enable all tracking for this browser |
hasOptedOut | hasOptedOut(): boolean | True when opted out or the browser sends Do-Not-Track |
setSuperProperties | setSuperProperties(props) | Merge properties attached to every future event |
flush | flush() | Force-send the current batch |
getDistinctId | getDistinctId(): string | The current visitor id |
Init options
signals.init({
apiKey: "sig_live_…", // required (or data-signals-key)
host: "https://api.pixelfox.app", // ingest API base URL
autocapture: true, // clicks/submits/pageviews/forms (default true)
inventory: true, // element auto-discovery (default true)
remoteEvents: true, // dashboard-defined definitions (default true)
vendorTags: true, // Clarity/Pixel/ttq/gtag injection (default true)
capturePageview: true, // initial $pageview (default true)
engagement: false, // scroll/time/rage-click/vitals/errors bundle (default false)
productPathPrefixes: ["/products", "/categories"], // catalog_filter_applied scope
});All feature flags except engagement are opt-out - everything is on by default.
engagement (also data-signals-engagement="true" on the tag) loads a second, lazy
bundle so the core tag stays inside its size budget.
Reserved event names
$pageview, $identify, $create_alias, $groupidentify are emitted by the SDK
itself. Names starting with $ are reserved; use plain snake_case for your own events.
Auto-captured events
With autocapture on: $pageview, catalog_filter_applied, product_viewed,
section_viewed, image_load_failed, form_validation_error,
stock_status_displayed, form_abandoned, page_not_found, plus any event named by a
data-signals-event attribute.
With engagement on, additionally:
| Event | Properties | When |
|---|---|---|
scroll_depth_reached | depth (25/50/75/100), pathname | first time each bucket is passed per page |
time_on_page | duration_ms, active_ms (tab visible), pathname | on leaving the page or an SPA navigation |
rage_click | tag, id, text, pathname | 3 clicks on one element within 800 ms |
dead_click | tag, id, text, pathname | a click on a non-interactive element that changed nothing within 1 s |
web_vitals | lcp, fcp, cls, inp, ttfb (ms; CLS unitless), pathname | once, when the page is hidden or unloaded |
$exception | message, source, line, stack, unhandled_rejection | uncaught errors and unhandled promise rejections |