Search app types, installation, configuration, API endpoints, and troubleshooting.
brng.ai ships two self-contained JavaScript search apps. Each runs inside a shadow DOM — fully isolated from your site's styles. No build tools or dependencies required.
| Search App | Use Case |
|---|---|
| Standard | Content sites, blogs, docs, knowledge bases — conversational AI search with streaming responses |
| Cart | E-commerce — product cards with images, prices, and stock labels, add-to-cart (Shopify & Magento), product comparison, cart panel, stock checking, and conversion tracking |
Both search apps share these features: dark/light/auto themes, chat history with session persistence, suggested questions, streaming AI responses, accessibility (WCAG 2.0 AA), and reduced-motion support.
Go to Settings > Integration in your dashboard. A ready-to-use embed code is generated for you — pre-configured with your domain's unique ID and the correct search app type. Copy it and paste it into your site's HTML (in the <head> or before </body>).
The search app automatically fetches all configuration (colors, fonts, suggestions, collections, kill switch) from the dashboard on page load. No additional setup needed.
All search app settings are managed through the dashboard. The search app fetches its configuration from the dashboard API on page load and cached it in sessionStorage for 5 minutes.
| Setting | Where to Configure | Description |
|---|---|---|
| Theme color | Customization page | Primary accent color for buttons, links, and the floating search bar |
| Font size | Customization page | Adjustable from Smallest to Largest (5 levels) |
| Suggested questions | Customization page | Up to 4 questions shown when the search app opens. Can be auto-generated by AI. |
| Search app type | Settings > Integration | Standard or Cart |
| Website type | Settings > General | E-commerce or Content — determines default search app and features |
| Kill switch | Customization page | Remotely disable the search app without removing the script tag |
| Logo | Customization page | Custom logo displayed in the search app header |
| Theme mode | Customization page | dark, light, or auto (matches visitor's OS preference) |
The search app supports three theme modes:
| Mode | Behavior |
|---|---|
light |
White backgrounds, dark text — always |
dark |
Dark backgrounds, light text — always |
auto |
Follows the visitor's OS preference via prefers-color-scheme (default) |
The accent color controls the floating search bar border, active states, buttons, and links. All styling is encapsulated within the shadow DOM — the search app won't affect or be affected by your site's CSS.
Both search apps persist conversations in localStorage (up to 20 chats per domain). Visitors can switch between past conversations using the history panel. Sessions expire after 30 minutes of inactivity.
The Cart search app displays product cards with images, titles, prices (with currency symbols for 36+ currencies), stock status labels, and direct links to product pages. Products are reordered based on how the AI mentions them in its summary.
The Cart search app supports platform-native add-to-cart for Shopify and Magento. Products are added via the platform's AJAX API so the website cart stays in sync. Multi-variant products show a "Select Options" button that opens the product page. Stock is verified in real time before adding.
Visitors can select two products to compare side by side. The comparison view shows aligned specifications, images, prices, and descriptions.
The Cart search app automatically tracks product views, add-to-cart events, checkout clicks, and order completions. Order detection works for Shopify (including webhook-based tracking) and Magento. All events appear in the Insights section of your dashboard.
POST https://dashboard.brng.ai/api/chat
Send a question and receive an AI-generated answer grounded in your indexed data. All chat requests are proxied through the dashboard — the AI server is never exposed directly.
The search app authenticates automatically using a session token issued during config fetch. For custom integrations, obtain a session token from the config endpoint first.
Compatible with the OpenAI chat completions format:
| Field | Type | Required | Description |
|---|---|---|---|
model |
string | Yes | Use "rag-local" |
messages |
array | Yes | Array of {role, content} message objects |
stream |
boolean | No | true for Server-Sent Events streaming (default: false) |
When stream: true, the server returns SSE events. The stream includes status updates (type: "status") at each processing phase (searching, ranking, generating), followed by content tokens (choices[0].delta.content), and ends with data: [DONE]. For e-commerce queries, product data is included as a separate SSE event before the text stream begins.
The embedded search app handles all API communication automatically — including session tokens, collections, streaming, and product rendering. You only need the Chat API for custom integrations.
GET https://dashboard.brng.ai/api/config/:clientId
Public endpoint. Returns search app appearance settings (colors, fonts, suggestions), search app type, collection names, platform type, kill switch state, and a session token for chat authentication. Cached for 5 minutes.
POST https://dashboard.brng.ai/api/analytics/events
Public endpoint. Submits search event data for analytics tracking. Required: clientId, query. Optional: deviceType, category, productsFound.
POST https://dashboard.brng.ai/api/analytics/cart-events
Public endpoint. Submits cart interaction events (add-to-cart, remove, checkout click, order complete). Required: clientId, action. Used by the Cart search app for conversion tracking.
Both analytics endpoints are called automatically by the search app. These are only needed for custom integrations.
All endpoints enforce rate limiting (per-IP and per-client). Exceeding limits returns 429 Too Many Requests with a Retry-After header (max 30 seconds).
| Status | Meaning |
|---|---|
| 200 / 201 | Success / Created |
| 400 | Missing or invalid fields |
| 401 | Missing or invalid authentication |
| 403 | Insufficient permissions |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Server error |
If your site uses a Content Security Policy, add these directives for the search app to function correctly:
| Directive | Value | Purpose |
|---|---|---|
script-src |
https://dashboard.brng.ai |
Search app JavaScript file |
connect-src |
https://dashboard.brng.ai |
Config, chat, and analytics API calls |
style-src |
'unsafe-inline' |
Search app injects styles into its shadow DOM |
font-src |
https://fonts.gstatic.com |
Google Fonts loaded by the search app |
img-src |
https: data: |
Product images and logos |
Magento requires a CSP whitelist XML file. Create or update etc/csp_whitelist.xml in your custom module:
<csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
<policies>
<policy id="script-src">
<values><value id="brng" type="host">dashboard.brng.ai</value></values>
</policy>
<policy id="connect-src">
<values><value id="brng" type="host">dashboard.brng.ai</value></values>
</policy>
<policy id="style-src">
<values><value id="brng_inline" type="host">'unsafe-inline'</value></values>
</policy>
<policy id="font-src">
<values><value id="brng_fonts" type="host">fonts.gstatic.com</value></values>
</policy>
<policy id="img-src">
<values><value id="brng_img" type="host">dashboard.brng.ai</value></values>
</policy>
</policies>
</csp_whitelist>After adding the file, flush the Magento cache: bin/magento cache:flush
csp_whitelist.xml and flush cachesessionStorage — clear it or wait for expiry