Skip to main content

​
SDK overview

The Selektable client SDK is a lightweight JavaScript library that runs on your product pages. It manages the widget lifecycle, product context, identity tracking, and communication between your page and the widget iframe.

​
Global object

After the embed script loads, it exposes a global window.Selektable object with the following methods:
MethodDescription
open(widgetId, options?)Open a widget with optional product data
close(widgetId)Close an open widget
preload(widgetId)Preload a widget iframe for faster opening
discover()Auto-discover data-selektable-widget elements
identify(userId, traits?)Associate visitor with a user identity
reset()Clear stored identity
getIdentity()Get current identity object
setVisitorId(id)Manually set the visitor ID

​
How it works

When the embed script loads, it:
  1. Initializes identity: generates or restores visitor/session IDs from browser storage
  2. Discovers widget elements: scans the DOM for data-selektable-widget attributes
  3. Manages iframes: creates, shows, hides, and communicates with widget iframes
  4. Handles cart operations: proxies add-to-cart requests between the widget and your callbacks
  5. Detects context: auto-detects product info, fonts, and translation service language

​
Widget states

Each widget instance goes through these states: 
idle → loading → ready → open
                   ↑       ↓
                   └───────┘
StateDescription
idleNo iframe created yet
loadingIframe created, waiting for it to load (shows loading spinner)
readyIframe loaded, widget can be opened instantly
openWidget is visible and interactive
Calling preload() moves the widget from idle to ready without showing it. Calling open() on an already ready widget shows it instantly with no loading spinner.

​
Browser support

All modern browsers are supported. The SDK uses standard web APIs (localStorage, sessionStorage, postMessage). If localStorage is unavailable (e.g., Safari private browsing), the SDK generates ephemeral IDs that don’t persist.