Provide browser context

Configure the field definitions first#

The service only attaches enabled fields defined for the website, and their value types must match. A key in JavaScript does not create a server-side field definition automatically. Arrange the field configuration with Reesponder before building a production integration; the current portal does not include a general context-field editor.

Choose a small set of useful non-sensitive hints, such as a product category or the language your application is displaying. Do not use browser-supplied values as proof of a customer account, order ownership, payment status or permission to execute an Action.

Write down the business purpose, source and lifetime of each proposed hint. A product category helps relevance; a browser flag such as owns_order: true cannot safely establish ownership.

Set initial values before the loader#

Put window.reesponderContext before the official deferred script. This example assumes the website has enabled matching string fields named product_category and display_language.

<script>
  window.reesponderContext = {
    product_category: "Bags",
    display_language: "en"
  };
</script>
<script
  src="https://cdn.reesponder.com/widget/v1/reesponder.js"
  data-site-id="YOUR_PUBLIC_SITE_ID"
  data-installation-token="YOUR_INSTALLATION_TOKEN"
  defer></script>

Replace the two installation placeholders with the full code generated for your website. Escape any dynamic server-rendered value safely rather than concatenating untrusted text into a script block.

If your website has an inline-script policy, use its existing safe rendering and policy mechanism. This example does not configure a nonce for the widget or justify weakening your site’s policy.

Use the supported browser hooks#

The loader exposes window.Reesponder.setContext(values) and window.Reesponder.clearContext(). It dispatches reesponder:ready after defining those hooks. The event signals that the browser context API exists; it does not confirm installation verification, Knowledge readiness or API availability.

function provideSupportContext() {
  window.Reesponder.setContext({
    product_category: "Bags",
    display_language: "en"
  });
}

if (window.Reesponder) {
  provideSupportContext();
} else {
  window.addEventListener(
    "reesponder:ready",
    provideSupportContext,
    { once: true }
  );
}

Load this integration only alongside the actual widget; unrelated scripts must not create or overwrite a conflicting window.Reesponder object.

Register a ready listener before the loader can dispatch the event, or use the existing-object check shown here. Event timing is a browser-hook check, not a green installation or conversation status.

Respect the first-bootstrap boundary#

The stock widget submits the context map when it first bootstraps the conversation. Later message requests send the current page path but not a fresh context object. Calling setContext() after bootstrap therefore does not update that conversation's server context.

setContext() merges accepted keys into the current in-memory map. clearContext() clears that map only. It does not delete previously attached service data or reset the conversation ID. Reloading can reuse a session-stored conversation, so a reload is not a reliable way to force new context attachment either.

This matters during sign-out or route changes: clearing local hints does not clear a previously attached server fact. Treat any required mid-conversation identity or data update as a separate commissioned lifecycle requirement.

Validate a bounded map#

Use at most 20 total keys. Names must match ^[a-z][a-z0-9_]{0,63}$. Values can be strings up to 500 characters, finite numbers or booleans; arrays, nested objects, null and non-finite numbers are not supported. The browser setter filters invalid entries, while the bootstrap endpoint validates the final complete map.

A field that is undefined, disabled or the wrong type is not attached. The server marks attached browser values untrusted, and they cannot overwrite an existing trusted value. For private backend facts, use the separately commissioned trusted context integration.

Repeated merging should still keep the final map at twenty total keys. The setter filters each call, but the server validates the complete map on bootstrap; many individually valid calls can exceed the final limit.

Worked example: a product category and display language#

Define product_category and display_language as enabled string fields for the website. Supply Bags and en before the official loader, or through setContext before the customer starts a conversation. Ask a safe question whose answer can use that public subject, then compare it with enabled Knowledge. The hint should improve relevance; it should not create a fact absent from your business sources.

In a controlled test, supply product_category as an object rather than a string and verify that it does not become accepted scalar context. Supply an undefined field such as experimental_hint and compare the behavior. A key present in page source does not establish a configured server definition.

Finally, change the map after the first question. The stock message request carries the current page path but no fresh context map, so do not expect a mid-conversation update. Use this test to make timing visible to the developer rather than treating setContext as a realtime server synchronization method.

Acceptance cases for a bounded browser-context integration#

Test initial values, ready-listener timing, supported types, missing definitions, disabled fields, too-long strings and the final map size. Distinguish browser filtering from server attachment: the loader can accept a scalar into memory while the server ignores it because its definition is absent or its declared type differs. Record field names and safe types in the test notes, with values redacted when appropriate.

Use a fresh commissioned test lifecycle when assessing first-bootstrap attachment. A page reload can reuse a session-stored conversation and skip new bootstrap. Do not create an unsupported reset flow by editing internal storage keys. Test a returning tab separately so its behavior is understood.

Review the unauthorized scenario as well: a browser can change any public hint. An altered account label must not reveal a private record or bypass Action email verification. Keep the implementation limited to the two public context methods and the ready event, and document which mid-conversation requirements remain outside that stock contract.

Decide whether a value belongs in browser context#

Use browser context when the value is a small visitor-facing hint, can safely be changed by the browser user and is useful at the beginning of the conversation. Examples include a public product category, a display language or a non-sensitive view label. Its field must be commissioned with a compatible type for this website.

Do not put a full customer record, access token or provider response into the map. Arrays and nested objects are outside the contract, but flattening an entire private record into twenty strings does not make it appropriate. Choose the minimum fact needed for a useful explanation and identify where that fact comes from.

If a value asserts a private entitlement or authenticated account state, your server must authenticate and authorize it before using the trusted integration. If a value is a live operational answer such as order status or current stock, an authorized Action may be the right source. Browser context supplies relevance data; it is not a generic way to install new tools, retrieve records or change service policy.

Diagnose ignored context without adding more data#

Start with the field definition: the exact lowercase key, website association, enabled state and value type. Then inspect what the application supplied before the first conversation bootstrap. Check whether the initial object was assigned before the loader executed or the supported setter ran before interaction. A later setter call is not retroactive.

Validate the values locally against the documented limits. A string longer than five hundred characters or a non-finite number is not a supported hint. If the final map has more than twenty keys, reduce it rather than relying on silent truncation. Unknown fields and type mismatches can be ignored even when a request is structurally valid.

Keep diagnostics to field names, types, timing and safe request status. Do not share the full customer state object or the page’s installation credential. If the integration needs continuous updates, authenticated identity changes or the current public conversation ID, define those requirements with Reesponder; adding more keys to the public map cannot create missing lifecycle hooks.