Document360 has rolled out an updated architecture for the Knowledge base widget, referred to as Widget V2. This article explains what's changed, what action you may need to take, and how to get support during the transition.
The Widget V2 rollout is being performed in phases across environments. If your widget has not yet migrated to V2, this article will not yet apply to your implementation. Contact Document360 support if you're unsure which version your widget is currently running.
What's changing in widget V2
The Knowledge base widget has been modernized from a vanilla JavaScript implementation to an Angular-based application, delivered through a secure, cross-origin iframe hosted by Document360.
Your existing embed snippet and widget.js URL remains unchanged; most customers will not need to update their embed code. However, the underlying way the widget renders and communicates with your page has changed:
The widget content now loads inside a dedicated iframe (
#document360-widget-iframe) instead of rendering directly within your host page.Direct access to the widget's internal DOM (for example, via
iframe.contentDocument) is no longer supported, due to standard browser same-origin restrictions.Widget interactions (opening, closing, toggling) must now go through a supported
postMessage APIinstead of direct script manipulation.
This change was introduced as part of our Widget V2 modernization effort to provide:
Improved security isolation
Better maintainability and scalability
Alignment with modern widget embedding practices
Reduced CSP requirements over time
Do I need to make any changes?
Your current setup | Action needed |
|---|---|
Standard embed using the default Document360 script, no custom DOM manipulation | No action needed. Your widget will continue to work as-is |
You use a custom button/trigger to open or close the widget via direct DOM access or custom JavaScript | Update to the |
You customized widget appearance via host-page CSS or JavaScript targeting widget internals | Move customizations to the widget's built-in Custom CSS / Custom JavaScript settings in Document360 |
Your Content Security Policy (CSP) restricts | Update your CSP to allow the Document360 widget domain (see below) |
Updating custom triggers to use the postMessage API
If you previously opened or closed the widget using a custom button and direct script access, update your implementation as follows:
<button type="button" id="d360-toggle">Help</button>
<!-- Document360 knowledge base widget start -->
<script>
(function (w,d,s,o,f,js,fjs) {
w['JS-Widget']=o;w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments) };
js = d.createElement(s), fjs = d.getElementsByTagName(s)[0];
js.id = o; js.src = f; js.async = 1; fjs.parentNode.insertBefore(js, fjs);
}(window, document, 'script', 'mw', '<Your CDN URL>'));
mw('init', { apiKey: '<Your API Key>' });
</script>
<!-- Document360 knowledge base widget end -->
<script>
document.getElementById('d360-toggle').addEventListener('click', function () {
var widgetIframe = document.getElementById('document360-widget-iframe');
if (widgetIframe && widgetIframe.contentWindow) {
widgetIframe.contentWindow.postMessage(
{ type: 'd360:api', method: 'show', params: {} },
'*'
);
}
});
</script>Supported method values:
Method | Behavior |
|---|---|
| Opens the widget |
| Closes the widget |
| Opens if closed, closes if open |
Note
Replace d360-toggle with the ID of your own trigger element.
The iframe ID document360-widget-iframe is fixed and must not be renamed — it's the supported integration point.
The widget automatically manages its own size and visibility. Do not attempt to manipulate the iframe directly.
Alternative: using the mw() command directly
As a simpler alternative to the postMessage approach above, you can call the public mw() command directly. The loader handles the iframe communication internally, so you don't need to reference document360-widget-iframe or construct a postMessage payload yourself.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document360 Knowledge Base Widget V2 — Host Page Sample</title>
</head>
<body>
<p>Control the widget with the public <code>mw()</code> API:</p>
<p>
<button onclick="mw('show')">Show</button>
<button onclick="mw('hide')">Hide</button>
<button onclick="mw('toggle')">Toggle</button>
</p>
<!-- Document360 knowledge base widget start -->
<script>
(function (w, d, s, o, f, js, fjs) {
w['JS-Widget'] = o;
w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments); };
js = d.createElement(s); fjs = d.getElementsByTagName(s)[0];
js.id = o; js.src = f; js.async = 1;
fjs.parentNode.insertBefore(js, fjs);
}(window, document, 'script', 'mw', '<Your CDN URL>'));
mw('init', {
apiKey: '<Your API Key>',
});
</script>
<!-- Document360 knowledge base widget end -->
</body>
</html>Supported mw() commands: mw('show'), mw('hide'), mw('toggle') — these correspond to the same show/hide/toggle behavior as the postMessage method above.
Use the CDN URL and API key shown in your own widget's embed code (Connections > Knowledge base widget > Edit > Configure & connect) rather than the placeholder values shown here.
Content Security Policy (CSP) requirements
These CSP requirements apply only if your site already enforces a Content Security Policy. If your site does not have a CSP configured, no additional configuration is needed for the widget to function.
Since the widget now loads inside an iframe, your CSP must explicitly allow the Document360 widget domain as a frame source:
frame-src Domain in your CDN URL
eg: https://cdn.us.document360.io
Widget V1 is required
unsafe-evalin yourscript-srcdirective. This is no longer required under Widget V2 — you can remove it if it was added solely for the widget.style-src 'unsafe-inline'is still required.
If your CSP does not allow this, the widget icon or content will fail to load, and you may see errors in the browser console referencing blocked frame sources or failed widget API requests.
For region-specific domains, refer to CSP and Whitelisting guidelines for the Document360 widget.
Migrating host-page customizations
If you previously customized the widget's appearance using CSS or JavaScript on your own webpage (targeting widget elements directly), this approach is no longer reliable under Widget V2, since widget content is isolated inside a cross-origin iframe.
Instead, configure equivalent customizations directly within Document360:
Navigate to Connections > Knowledge base widget.
Hover over the desired widget and click Edit.
Use the Custom CSS and Custom JavaScript tabs to apply your styling and behavior changes.
JWT authentication and Widget V2
If your widget uses JWT authentication, the authUrl integration and your existing JWT configuration remain unchanged under Widget V2. No changes are required to your authentication endpoint or client secret as a result of this migration.
Widget V2 migration and JWT authentication failures are separate, unrelated issues. If your widget is failing to authenticate (for example, errors at the token endpoint, or articles failing to load with 401/404 responses), this is typically caused by a JWT configuration issue, most commonly, a client secret mismatch — and not by the V2 architecture change. See Configuring JWT for the knowledge base widget or authentication-specific troubleshooting before assuming it's related to this migration.
Requesting a temporary rollback
If you need more time to update your implementation, you can request a temporary rollback to the previous widget version while you complete your migration.
To request a rollback:
Contact Document360 support through email support@document360.com with your Project ID and the names of the widgets you'd like reverted.
Confirm whether you'd like all widgets in the project rolled back, or specific ones only.
Once completed, your widget(s) will resume functioning on the previous version immediately, without requiring any changes on your end.
If your project has multiple widgets (for example, a live widget and a separate test widget), you can choose to keep one on Widget V2 for testing while rolling back the other, these are independent per widget.
Troubleshooting
Symptom | Likely cause | What to do |
|---|---|---|
The widget icon does not appear on the page | CSP is blocking the widget iframe | Update your CSP to allow |
Custom open/close button no longer works | Custom trigger uses direct DOM access instead of the postMessage API | Update your trigger to use |
Widget loads, but previous CSS customizations no longer apply | Host-page CSS can no longer target widget internals | Move customizations to the widget's Custom CSS settings in Document360 |
Console shows | Code attempting to access the widget iframe's DOM directly | Remove direct DOM access; use the postMessage API instead |
Widget fails to load articles (404 errors from widget APIs) | Typically unrelated to V2 — check JWT/authentication configuration |
Next steps
Review your current widget implementation for any custom JavaScript that directly accesses widget internals.
Update your CSP if required.
Move host-page customizations into the widget's Custom CSS/JS settings.
Contact Document360 support if you need a temporary rollback or have questions about your specific implementation.