Configuration Every initSiteping option, with its real default and behavior.
All options of initSiteping(config). Only projectName plus one of endpoint / store are required.
Option Type Default What it does endpointstring— URL of your SitePing API (e.g. /api/siteping) storeSitepingStore— Client-side mode: write to a store in the browser instead of HTTP. Wins over endpoint; apiKey/headers are ignored projectNamestring— Required. Scopes everything the widget reads and writes apiKeystring— Sent as Authorization: Bearer <key> on every request headersobject or function — Extra headers, static or computed per request (sync or async). Merged last, so an explicit Authorization here beats apiKey
Option Type Default What it does forceShowbooleanfalseBypasses the production and viewport guards (never the SSR guard) minViewportWidthnumber768Below this width the widget skips with onSkip("mobile"). Use 0 to allow any width position"bottom-right" | "bottom-left""bottom-right"Corner for the floating button showAnnotationsTogglebooleantrueSet false to remove the marker-visibility toggle from the radial menu
Option Type Default What it does accentColorstring"#0066ff"Hex only (#RGB, #RRGGBB, #RRGGBBAA). Named colors, rgb(), hsl() etc. log a warning and fall back to the defaulttheme"light" | "dark" | "auto""light"auto reads the system preference once at init — an OS theme change mid-session doesn't re-theme the widgetlocalestring"en"Any BCP-47 tag; see Languages
Option Type Default What it does enableScreenshotbooleanfalseCapture a JPEG of the annotated area on submit — see Screenshots enableRightClickCommentbooleanfalseRight-click anywhere to comment instantly — see Right-click comments captureDiagnosticsboolean or objectfalseAttach recent console entries (max 50) and network requests (max 20) to each feedback. true enables both; an object picks channels and limits deepLinkboolean or { param?: string }falseOn first load, focus the feedback referenced by ?siteping=<id> (or your custom param). Initial load only — for route changes, call focusFeedback() identity{ name, email }— Pre-fill the author (SSO apps): skips the identity modal entirely, never persisted to localStorage
Option Type Default What it does scopeAnnotationsByUrlbooleantrueOnly show markers created on the current page. Filtered both server-side and client-side, so annotations can't leak across pages getPageScope() => { url, urlPattern }pathname Customize what "the current page" means — return a stable url (and optionally a template like /products/:id as urlPattern) so dynamic routes share their feedback watchNavigationbooleantrueRe-fetch feedbacks on SPA navigation (History API patch + popstate/hashchange). Data only — it never scrolls or refocuses. Set false and call refresh() yourself to opt out
The default page scope is window.location.pathname — by construction it contains no query string, so tokens or search params in the URL never reach the server. If you provide getPageScope, keep that property: return a path or a template, not location.href.
Option Signature Fires when onFeedbackSent(feedback) => voidA feedback was successfully created onError(error) => voidA submission or fetch failed — see error handling onOpen / onClose() => voidThe panel opened / closed onAnnotationStart / onAnnotationEnd() => voidAn annotation session began / ended — pause chat bubbles or analytics overlays here onSkip(reason) => voidThe widget decided not to render: "ssr", "production", or "mobile". Invalid config logs a console.error instead
Option Type Default What it does debugbooleanfalseVerbose [siteping] lifecycle logging via console.debug