Widget installation

This page describes the supported way to embed the widget in production: versioned CDN with Subresource Integrity (SRI), Content-Security-Policy policy and fallback to a pinned version when @latest moves.

Shortcut: Snippet Builder

Prefer building your <script> with a form and seeing it live? Go to the Snippet Builder — colors, locale, theme, features, all on one page with a real preview.

Prerequisites

• A Widget Token (header X-Widget-Token). If you don't have one yet, follow Authentication → Widget Token.
• A container in your template, typically a <div id="neuroon-search"></div>.
• Permission to add a <script> in <head> or before </body>.

Base snippet

index.html

<div id="neuroon-search"></div>
<script
  src="https://cdn.neuroon.ai/widget/widget.js"
  data-token="YOUR_WIDGET_TOKEN"
  data-container="#neuroon-search"
  data-theme="auto"
  data-locale="es"
></script>

<div id="neuroon-search"></div>
<script
  src="https://cdn.neuroon.ai/widget@0.9.27/widget.js"
  data-token="WIDGET_TOKEN_HERE"
  data-container="#neuroon-search"
  data-theme="auto"
  data-locale="es"
  data-api-url="https://api.neuroon.ai"
  async
></script>

The script auto-initializes: it detects data-token, mounts the Shadow DOM in the data-container and renders the UI. You don't have to call any extra JavaScript API for the standard flow.

Do not use `@latest` in production

@latest is convenient in development but breaks browser caching and opens the door to silent regressions. Pin the exact version (widget@0.9.27/widget.js) and bump it once you have validated the new one in dev.neuroon.ai.

Subresource Integrity (SRI)

Each widget release publishes an SRI manifest with the SHA-384 hash of the bundle:

https://cdn.neuroon.ai/widget@0.9.27/integrity.json

Add it to the <script> so the browser rejects any CDN tampering:

<script
  src="https://cdn.neuroon.ai/widget@0.9.27/widget.js"
  integrity="sha384-AbCdEf123…"     crossorigin="anonymous"
  data-token="WIDGET_TOKEN_HERE"
  data-container="#neuroon-search"
  async
></script>

SRI hash

The hash is specific to the file served by the CDN. If we re-publish a patch under the same 0.9.27 version (which we don't do in production except for security emergencies), the manifest is updated and we publish an advisory.

data-* attributes

Attribute	Required	Value
data-token	yes	24 h Widget Token signed by your own server with the API Key (HMAC).
data-container	no	CSS selector of the container. Default #neuroon-search if omitted.
data-theme	no	auto (default), light, dark.
data-locale	no	ISO code from the 9 supported locales. Default es.
data-api-url	no	API base URL override. Default https://api.neuroon.ai. Available since v0.9.19.
data-primary-color	no	Does nothing — the CSS mapping is empty. Use styles.primary via init().
data-placeholder	no	Empty-input text.
data-suggestions, data-filters	no	false to disable the feature.

See Configuration → data-* attributes for the fully verified reference.

Content-Security-Policy

If your host enforces strict CSP, the widget needs these directives:

script-src   'self' https://cdn.neuroon.ai;
connect-src  'self' https://api.neuroon.ai ;
img-src      'self' data: https:;
font-src     'self' https://rsms.me;
style-src    'self' 'unsafe-inline';

• connect-src — the widget calls the API and, if monitoring is enabled, reports to browser-intake-datadoghq.eu.
• font-src https://rsms.me — the widget preconnects and loads the Inter family from rsms.me.
• style-src 'unsafe-inline' — required because the widget injects <style> inside the Shadow DOM. Shadow DOM isolates that stylesheet from the host document.

Environments

By default the widget points to production (https://api.neuroon.ai). With auto-init, add data-api-url="https://dev-api.neuroon.ai" to the <script> to point to development. For programmatic control (SPA, runtime environment switching), use init() with the URL shown in the navbar environment selector:

window.NeuroonWidget.init({
container: '#neuroon-search',
token: 'YOUR_DEVELOPMENT_TOKEN',
apiUrl: 'https://api.neuroon.ai',
theme: 'auto',
locale: 'en',
})

Select Development in the navbar and the apiUrl will update automatically.

Programmatic initialization (optional)

Auto-init covers most integrations. If you need fine-grained control (lazy-load, multiple instances, dynamic server-side configuration), use the JavaScript API:

const widget = window.NeuroonWidget.init({
  container: '#neuroon-search',
  token: 'WIDGET_TOKEN_HERE',
  apiUrl: 'https://api.neuroon.ai',
  theme: 'auto',
  locale: 'es',
})

// Methods available on the instance
widget.setTheme('dark')
widget.setStyles({ primary: '#06b6d4' })
widget.destroy()

JavaScript API: scope

The instance returned by init()/getInstance() only exposes destroy, setTheme and setStyles — there's no imperative search()/setFilters(). Config-time callbacks genuinely support onSearch, onResultClick, onFilterChange, onError, onTokenExpiring and onTokenRefreshed (verified in the widget's source) — see Configuration → callbacks for the full, correct list.

Further reading

• Snippet Builder — generate the snippet from a form, in 2 minutes.
• Configuration — full NeuroonWidgetConfig.
• Theming — --nrn-* variables and per-theme overrides.
• Authentication → Widget Token — issuance and rotation.