Custom websites and frontend applications

Install once in the shared layout#

Copy the complete generated tag from the website's Installation view and publish it before the closing </body> in each intended shared document layout. For a client application, install it once in the persistent shell rather than on every route-component mount.

The loader reads its own executing tag and data attributes. Bundling its bytes into your app, rewriting those attributes or evaluating it as an inline module is not the same supported installation. Use the official versioned CDN tag and public hooks. The one-widget guard avoids duplicate visible elements but cannot choose the intended credential between competing tags.

Plan coverage deliberately#

List the intended routes and their document shells: homepage, product or service, policy, contact and any application entry. Decide sensitive-route coverage deliberately. A marketing footer may not belong to a separate account app, and support inherited during navigation may still be absent on a direct deep link.

The widget sends the current pathname and query with each message, so use meaningful ordinary URLs where possible. Views sharing one unchanged URL need a separately configured public hint if appropriate. Browser context has first-bootstrap timing; a loader on a private page does not automatically make its content available as Knowledge or authorize its records.

Check site security and delivery policies#

The browser must load https://cdn.reesponder.com/widget/v1/reesponder.js and connect to https://api.reesponder.com. If either is blocked, inspect the actual browser directive, script rule, extension or consent-manager condition instead of broadly disabling site security.

The runtime uses closed Shadow DOM, not an iframe, and inserts an inline style element and dynamic inline style values. A CDN allowlist alone therefore does not establish compatibility with every restrictive CSP. There is no documented nonce pass-through hook. A custom avatar can require its own image origin. Have the developer review these behaviors against your real policy; adding an irrelevant frame permission cannot repair an inline-style restriction.

Separate public hints from private facts#

Public hints can be supplied through window.reesponderContext before the loader or Reesponder.setContext() before first bootstrap, using configured website-scoped field definitions. They are untrusted browser values and must not contain provider tokens, passwords or trusted-context credentials.

Later setContext calls change the local map but do not update an already bootstrapped conversation. clearContext also does not erase server context or switch verified identity. Private data needs an authenticated backend integration. The stock widget has no public conversation-ID callback or sign-in bridge; agree the complete lifecycle with Reesponder before implementing a trusted-context requirement.

Verify the installation as a visitor#

Test final production HTTPS routes directly and through normal navigation, on desktop and an actual narrow phone. Ask a page-specific question and a deliberately missing-detail question. Check the keyboard, close control and collisions with fixed storefront controls.

Use both a fresh profile and a returning tab. Development extensions and stored conversations can obscure the first failing layer. Test the cookie choices and policy configuration you ship, and verify preview-domain authorization separately. Keep hostname, layout, release time and fresh detection in the release record; the detailed checklist below adds source and private-data checks.

Worked example: marketing site plus a separate application shell#

A business has public marketing pages under one shared server template and an account application with its own document shell. Adding the script to the marketing footer covers the pages inheriting that template. It does not guarantee that a direct account-app URL contains the loader. Decide explicitly where support belongs, then inspect each intended document shell rather than assuming all routes share one footer.

For a single-page application, keep the widget’s loader in a persistent shell. Test a direct deep link and navigation from the homepage. Do not inject a new script from every route component or call undocumented open/reset methods. If your application displays different content under one fixed URL, document what page context can identify and arrange a configured hint or authorized Action only when it serves a concrete requirement.

A release checklist your developer can execute#

Verify one loader per intended document, current attributes, the final hostname, a successful fresh detection request and a representative answer. Cover direct homepage, product and policy entry, client-side navigation, a returning tab and a fresh browser profile. Test a narrow phone with the keyboard open and confirm that fixed page controls and the chat close action remain usable.

Check the site’s consent choices and browser policy in the configuration you actually ship. Review the information carried in page queries and configured browser hints. Test unauthorized private-data access separately when Actions or trusted context are commissioned. Keep customer passwords, provider secrets, private context credentials and unnecessary personal information out of browser code. A successful build is not visitor-experience verification.

Place the complete tag at the document boundary#

For a traditional server-rendered website, locate the shared template that closes the body. Add the generated script immediately before that closing tag and publish through your normal release process. The snippet should not be pasted into visible page content, a rich-text block or a per-product description. Those locations can render text instead of executing a script or cover only one page.

For a frontend framework, use its documented mechanism to include an unchanged external script once at the shared document or application boundary. The exact framework component varies; this guide does not provide an untested framework wrapper. What must remain true is that the executing script carries the correct data attributes, loads from the official CDN and appears on direct entry to each supported route.

Use a reserved example or placeholders only during code review. Before production, replace the entire example with the tag generated for your actual website. The public site ID and current token must belong together. Do not move a private backend credential into the tag to solve an authorization failure.

Read the network trace in installation order#

First check the document and https://cdn.reesponder.com/widget/v1/reesponder.js. If the script is absent, investigate your deployment or layout. If it is present but blocked, read the browser’s exact security-policy or extension error. Then check POST /v1/widget/installations/detect to the API. This verifies the current public site ID, installation credential and request hostname.

A successful detection supplies website identity, supported appearance and human-support availability. It does not open a billable chat conversation just because a greeting is shown. The first customer submission performs bootstrap and then a message request. A failed first answer can therefore arise from access, capacity, stale conversation or service availability even when installation was detected.

Keep request status and safe error code as diagnostics. Do not paste full request bodies, tab tokens or customer queries into a public support message. Identify the first failing layer before changing credentials; a new token cannot fix a missing template or a blocked connect-src policy.

Account for caches, optimizers and consent managers#

A new deployment can coexist with stale documents served by a page cache, CDN or browser cache. Compare the HTML a visitor receives with the tag in your source repository. Purge only the relevant delivery layer using your normal deployment controls. After replacing a credential, all active cached documents must receive its current tag; preserving the old green detection label is not enough.

An optimizer may combine or delay external scripts. Because the loader depends on the currently executing tag and its attributes, exclude it from rewriting that changes those conditions. If a consent manager controls its execution, test the actual accepted and rejected visitor paths. Installing the widget does not automatically configure your site’s legal classification or optional analytics setup.

Do not broadly disable site security to make a script run. Have the developer review the actual policy directive, required origins and inline-style behavior. Keep any new exception specific, documented and verified on production pages. Re-test after optimizer, CMP or hosting updates that can alter script delivery.

Hand over the supported contract#

A useful developer handover names the public website record, final host, shared installation location, route scope and cache procedure. It lists the supported browser hints, their field definitions and the first-bootstrap timing. It separates these public details from any server-side Action or trusted-context credentials.

List unsupported requirements before implementation: general panel opening from custom buttons, transcript extraction, conversation reset, a stock conversation-ID callback and a signed browser identity bridge are not exposed by the current public hooks. If your product needs one of those capabilities, agree a complete lifecycle integration with Reesponder instead of depending on internal markup or storage keys.

For a custom live-data task, build a narrow authorized HTTP Action adapter with a fixed endpoint and mapped safe results. The assistant should not receive arbitrary destinations, headers or provider credentials from the visitor. Treat the widget, your application session and the business data system as separate components with explicit responsibilities.