Nativo Chat Widget Documentation

Technical documentation and live testing environment

Quick Links

Test Configuration

Advertiser:NFL Sports Weekly

Environment:Production

Version:1.0.0

Live Widget Test

This is a live instance of the Nativo Chat Widget. The widget analyzes this documentation page to help answer questions about the widget implementation and usage.

Live Configuration Editor

Advertiser Name

Logo URL

Advertiser URL

Content Selector

Hide Powered By

Show Audio/List UI

Position

Brand ID (Brand Agent)

If set, uses Brand Agent instead of Mastra

Target Element (Optional)

Enter "#custom-target" to test rendering in the blue box below

Current Script Tag:

<script src="/widget.js"
  data-advertiser-name="Nativo"
  data-advertiser-logo="https://sponsoredcontent.com/nativo-logo.png"
  data-advertiser-url="https://sponsoredcontent.com"
  data-brand-id="4001"
  async></script>

Test Target Element (use selector: #custom-target)

Custom target element - widget action will appear here if targeted

Installation

Add the widget script with data attributes to your page. The widget will automatically initialize when the script loads.

<!-- Add this script tag to your page -->
<script src="https://sponsoredcontent.com/widget.js"
  data-advertiser-name="Your Brand"
  data-advertiser-logo="https://your-logo.png"
  data-advertiser-url="https://your-site.com"
  data-content-selector="#article-content"
  data-is-embed="true"
  async></script>

<!-- Optional: Use Brand Agent instead of Mastra -->
<!-- Add data-brand-id to use Brand Agent integration -->
<script src="https://sponsoredcontent.com/widget.js"
  data-advertiser-name="Nitto Tire"
  data-brand-id="4001"
  async></script>

<!-- Optional: Render widget action inside a specific element -->
<!-- Example: data-target-element="#my-custom-container" -->
<!-- The widget action/button will render inside that element -->

Key Points:

The widget auto-initializes when the script loads
All configuration is done via data attributes
Without data-target-element, widget uses default rendering
With data-target-element, widget action renders inside the specified element
Add data-brand-id to use Brand Agent integration (e.g., 4001 for Nitto Tire)
The widget uses Shadow DOM for complete style isolation

Configuration Options

Option	Type	Default	Description
selector	string	required	CSS selector for widget container
advertiserName	string	required	Brand or advertiser name
advertiserLogo	string	null	URL to brand logo image
contentSelector	string	auto	CSS selector for article content
enableSmartSelector	boolean	true	Auto-detect main content area
saveChatMessages	boolean	false	Persist chat history in localStorage
hidePoweredBy	boolean	false	Hide "Powered by Nativo" branding
isEmbed	boolean	false	Render as embedded widget
targetElement	string	""	CSS selector where widget action/content will render
baseUrl	string	auto	API endpoint base URL
position	string	""	Widget position: "bottom" or "top"
brandId	number	undefined	Brand ID for Brand Agent integration (if provided, uses Brand Agent instead of Mastra)

API Reference

NativoChatWidget.init(config)

Initialize the widget with configuration options

Returns: Promise<void>

NativoChatWidget.destroy()

Remove the widget and clean up event listeners

Returns: void

NativoChatWidget.reset()

Clear chat history and reset to initial state

Returns: void

NativoChatWidget.sendMessage(message)

Programmatically send a message to the chat

Returns: Promise<Response>

Events

The widget emits custom events on the window object:

window.addEventListener('nativo:widget:ready', (e) => {
  console.log('Widget initialized');
});

window.addEventListener('nativo:widget:message', (e) => {
  console.log('Message sent:', e.detail.message);
});

window.addEventListener('nativo:widget:response', (e) => {
  console.log('Response received:', e.detail.response);
});

window.addEventListener('nativo:widget:error', (e) => {
  console.error('Widget error:', e.detail.error);
});

Custom Styling

The widget can be customized using CSS variables:

#nativo-chat-widget {
  --nativo-primary-color: #3B82F6;
  --nativo-text-color: #1F2937;
  --nativo-bg-color: #FFFFFF;
  --nativo-border-radius: 8px;
  --nativo-font-family: system-ui, -apple-system, sans-serif;
  --nativo-max-width: 600px;
  --nativo-max-height: 500px;
}

Troubleshooting

Widget not appearing

Ensure the container element exists before initialization
Check browser console for error messages
Verify the script is loaded with correct URL

Content not being analyzed

Verify contentSelector points to correct element
Ensure content is present when widget initializes
Try disabling enableSmartSelector if issues persist

CORS errors

Ensure your domain is whitelisted
Check baseUrl configuration
Contact support for domain approval