Embedding Widget Production QA and Security

Use this checklist before moving a Ringg AI widget from staging to production. The main risks are public browser credentials, domain allowlisting, CSP, CDN version drift, and browser-specific call behavior.

Security controls

Use the dashboard-generated widget key for the web-call assistant, not a broad backend integration key.

Add every allowed staging and production host to the assistant’s Whitelist Domains list.

Keep variables free of secrets, internal tokens, and sensitive data that should not be visible in browser dev tools.

Pin a tested CDN version in production instead of loading latest.

Review analytics and event listeners so user identifiers are handled according to your privacy policy.

Anything in the embed snippet can be viewed by a site visitor. Treat the authorization Bearer key, variables, and custom widget metadata as browser-visible configuration. The webcall public key is scoped to the assistant and its whitelisted domains — rotate it from the dashboard if it ever leaks beyond those.

Domain whitelist

Add each domain where the widget is allowed to run in the assistant WebCall settings.

Environment	Example domain
Local development	`localhost` if your dashboard setup allows it.
Staging	`staging.example.com`
Production	`www.example.com`

Whitelist staging separately from production so you can test CDN version pins, CSP changes, and assistant changes before launch.

CSP setup

If your site uses Content Security Policy, allow the Ringg widget CDN for scripts and styles.

script-src 'self' https://cdn.jsdelivr.net;
style-src 'self' https://cdn.jsdelivr.net;

If your policy pins exact asset paths, match the CDN version and the bundle filename used by the loader. The widget ships an ES build for module-aware setups and a UMD build for jQuery and legacy pages, so the pinned path differs between integrations.

ES build
UMD build

script-src 'self' https://cdn.jsdelivr.net/npm/@desivocal/agents-cdn@1.0.19/dist/dv-agent.es.js;
style-src 'self' https://cdn.jsdelivr.net/npm/@desivocal/agents-cdn@1.0.19/dist/style.css;

script-src 'self' https://cdn.jsdelivr.net/npm/@desivocal/agents-cdn@1.0.19/dist/dv-agent.umd.js;
style-src 'self' https://cdn.jsdelivr.net/npm/@desivocal/agents-cdn@1.0.19/dist/style.css;

Keep the loader version, the bundle filename, CSP entries, and release notes for your deployment in sync. A mismatch can make the widget work in staging and fail in production.

CDN version pinning

During development:

loadAgentsCdn("latest", function () {
  loadAgent({
    agentId: "your-agent-id",
    authorization: "Bearer your-webcall-public-key",
  });
});

For production, replace latest with the tested version.

loadAgentsCdn("1.0.19", function () {
  loadAgent({
    agentId: "your-agent-id",
    authorization: "Bearer your-webcall-public-key",
  });
});

Browser QA checklist

The widget appears in the expected position at desktop, tablet, and mobile widths.

Voice mode requests microphone permission and handles both allow and deny paths.

A test call can start, receive audio, and end cleanly.

Chat mode sends and receives messages if defaultTab is "text".

Calendar widgets hide past slots and return the selected date, time, and timezone.

Form widgets validate required fields and submit the expected field keys.

Widget events fire once per action and do not duplicate after client-side navigation.

Console and network panels have no blocked CDN, CSP, or mixed-content errors.

Launch checks

Verify dashboard settings

Confirm the assistant is configured for Webcall, the correct agentId is used, and all production domains are whitelisted.

Verify the embed snippet

Confirm the deployed page uses the production key, the pinned CDN version, and the expected defaultTab, variables, and styling options.

Verify security policy

Confirm CSP allows the pinned CDN script and stylesheet. If your site has stricter policies, test the deployed production headers directly.

Run an end-to-end conversation

Start and end one voice call or chat session, submit feedback if enabled, and confirm any configured analytics or widget event handlers receive the expected payload.

Troubleshooting

Symptom	Check
Trigger button does not appear	Confirm the CDN script loaded, CSP is not blocking assets, and `loadAgent` runs after the CDN callback.
Widget appears on staging but not production	Confirm the production domain is in Whitelist Domains and CSP uses the same pinned CDN version.
jQuery `$` is undefined or host page globals are clobbered after the widget loads	The page is loading `dv-agent.es.js` as a plain `<script>`. Swap the loader to `dv-agent.umd.js` and update the pinned CSP path to match.
Voice call cannot start	Confirm microphone permission, browser support, and that the assistant is configured for Webcall.
Chat opens in the wrong mode	Confirm `defaultTab` and `hideTabSelector` in the deployed `loadAgent` config.
Analytics fire twice	Remove duplicate event listeners during single-page app navigation.

Get Started

API Reference

Webhooks Setup

Telephony Integration

External Integrations

Embedding Widget Production QA and Security

Security controls

Domain whitelist

CSP setup

CDN version pinning

Browser QA checklist

Launch checks

Troubleshooting

​Security controls

​Domain whitelist

​CSP setup

​CDN version pinning

​Browser QA checklist

​Launch checks

​Troubleshooting

Security controls

Domain whitelist

CSP setup

CDN version pinning

Browser QA checklist

Launch checks

Troubleshooting