Web SDK Overview

How the elNudge Web SDK loads, what it does, and what to expect from the browser environment.

The elNudge Web SDK is a single JavaScript file that runs in the visitor's browser. It collects behavioral signals, maintains a session, and renders the nudge widget when the AI decides to engage.

Bundle size

The SDK is under 12 KB gzipped. It is designed to be as lightweight as possible so it does not affect Core Web Vitals or Lighthouse scores. The bundle is served from https://cdn.elnudge.com/v1/sdk.js over a global CDN with aggressive cache headers.

Async loading

The async attribute on the script tag means the browser fetches the SDK in parallel with the rest of the page and executes it as soon as it is downloaded — without blocking the HTML parser or delaying DOMContentLoaded. Page render is never held up waiting for the SDK.

<!-- async ensures the script never blocks page render -->
<script
  src="https://cdn.elnudge.com/v1/sdk.js"
  data-site-key="sk_live_YOUR_SITE_KEY"
  async
></script>

Pre-load queue

Because the script loads asynchronously, window.__eln may not be defined when the rest of your page JavaScript runs. The pre-load queue pattern handles this gracefully:

// Define a stub before the SDK loads.
// Any calls made now are queued and replayed once the SDK is ready.
window.__eln = window.__eln || function () {
  (window.__eln.q = window.__eln.q || []).push(arguments)
}

// Safe to call immediately — will replay after load if needed
window.__eln('track', 'PRODUCT_VIEW', { product_id: 'prod_abc' })
window.__eln('identify', { user_id: '42', email: '[email protected]' })

window.__eln.q is the raw array holding queued calls. The SDK drains this array on startup. You do not need to manage it yourself — but you can inspect it in the console to confirm calls are queued correctly.

Browser support

Voice features rely on the Web Speech API, which Firefox does not implement. Visitors on Firefox receive text-only nudges automatically.

SDK lifecycle

The SDK goes through the following stages from script load to first nudge:

1. load
   Browser fetches and parses sdk.js from the CDN.

2. init
   SDK reads data-site-key from the script tag.
   Establishes a WebSocket connection to wss://relay.elnudge.com.
   Assigns or restores a session ID (ses_01HXXXXX).
   Drains window.__eln.q — replays any queued calls.

3. track
   Begins listening for and firing auto-detected events:
   PAGE_VIEW, SCROLL_DEPTH, ELEMENT_HOVER, CLICK,
   EXIT_INTENT, TAB_SWITCH, IDLE.
   Forwards manual events as they are called.

4. receive instructions
   The platform evaluates intent signals in real time.
   When intent crosses a threshold the relay sends
   a nudge instruction back over the WebSocket.

5. render widget
   The SDK renders the nudge widget in the DOM.
   The visitor sees a chat bubble, a message, or a voice prompt
   depending on the nudge type configured in the dashboard.

Session continuity

A session starts when the SDK initialises and persists until the visitor closes all tabs or the session times out (30 minutes of inactivity by default). Navigating between pages — including SPA route changes — does not reset the session. The same ses_01HXXXXX ID is used throughout.

Security

• The SDK does not read or write cookies by default.
• No PII is collected automatically. You supply PII explicitly via window.__eln('identify', ...).
• All communication with the platform travels over TLS (HTTPS / WSS).
• The site key is a public identifier — it is safe to include in client-side code.