Skip to main content

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.

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.

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>

data-* attributes​

AttributeRequiredValue
data-tokenyes24 h Widget Token signed by your own server with the API Key (HMAC).
data-containernoCSS selector of the container. Default #neuroon-search if omitted.
data-themenoauto (default), light, dark.
data-localenoISO code from the 9 supported locales. Default es.
data-api-urlnoAPI base URL override. Default https://api.neuroon.ai. Available since v0.9.19.
data-primary-colornoDoes nothing — the CSS mapping is empty. Use styles.primary via init().
data-placeholdernoEmpty-input text.
data-suggestions, data-filtersnofalse 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()

Further reading​

Last updated on