Widget script tag

The Ask2Do widget is a self-contained JavaScript bundle that adds a floating chat-bubble button to your admin panel. One <script> tag is the entire install — no npm package, no build-time wiring, no React/Vue/Angular adapters.

At a glance

Quick start

Paste this immediately before </body> on every page that should expose the assistant:

<script
  src="https://cdn.ask2do.com/widget.js"
  data-cloud-url="wss://cloud.ask2do.com"
  data-panel-role="admin"
  defer
></script>

For any real integration plug in your own token resolver and user context — see Authentication and Panel user context below.

Versioning & cache behaviour

The CDN serves whatever the latest published release is. Every response carries Cache-Control: public, max-age=60, must-revalidate, so customer browsers revalidate within ~60 seconds. You do not pin a version in the script tag.

Check the running version

1. Open DevTools → Console. The widget logs a brand chip: Ask2Dov0.2.10 — the latest release is v0.2.10.
2. window.Ask2Do.version in the console.
3. curl -s https://cdn.ask2do.com/widget.js | grep -oE '"[0-9]+\.[0-9]+\.[0-9]+"' | head -1

Force a fresh fetch (rarely needed)

Option A — one-time bust. Append a date/build stamp to the script src after a release you want customers to pick up immediately:

<script src="https://cdn.ask2do.com/widget.js?v=YYYYMMDD" ...></script>

Bump the value any time you want browsers to re-fetch. The CDN ignores the query string (R2 serves the same object regardless) — it's purely a browser-side cache buster.

Option B — always fresh, on every page load. If your panel is split across multiple subdomains or sub-apps and you've seen them diverge on cached widget versions, drop the static <script> tag entirely and inline this IIFE loader instead. The Date.now() stamp guarantees every page load fetches a fresh copy from the CDN:

<script>
  (function () {
    var s = document.createElement('script');
    s.src = 'https://cdn.ask2do.com/widget.js?t=' + Date.now();
    s.defer = true;
    s.setAttribute('data-cloud-url', 'wss://cloud.ask2do.com');
    s.setAttribute('data-panel-role', 'admin');
    document.head.appendChild(s);
  })();
</script>

Trade-off: every page load re-downloads widget.js (~325 KB) instead of using the browser cache, so first paint is slightly slower and your customer's users pay a bit more bandwidth. Worth it only when you specifically need every panel to converge on the very latest deploy within seconds — otherwise the default max-age=60 revalidation handles it.

Authentication

The widget needs a short-lived JWT signed by cloud.ask2do.com/auth/token. Your panel mints that JWT server-side from your tenant key — never expose the tenant key to the browser. Three integration patterns, pick whichever fits:

1. Endpoint convention (simplest)

<script
  src="https://cdn.ask2do.com/widget.js"
  data-cloud-url="wss://cloud.ask2do.com"
  data-token-endpoint="/api/ask2do/token"
  data-panel-role="admin"
  defer
></script>

Default contract: GET, returns { "token": "<jwt>" }, cookies forwarded via credentials: "include".

2. Custom token resolver (most flexible)

<script>
  window.Ask2DoGetToken = async () => {
    const r = await fetch("/api/ask2do/token", {
      method: "POST",
      credentials: "include",
    });
    if (!r.ok) throw new Error("Ask2Do auth failed");
    const { token } = await r.json();
    return token;
  };
</script>
<script
  src="https://cdn.ask2do.com/widget.js"
  data-cloud-url="wss://cloud.ask2do.com"
  data-panel-role="admin"
  defer
></script>

3. Imperative mount (advanced)

window.Ask2Do.mount({
  cloudUrl: "wss://cloud.ask2do.com",
  getToken: async () => (await fetch("/api/ask2do/token")).json().then(r => r.token),
  panelUser: { id: "42", role: "admin" },
});

Panel user context

The widget shows a button only to users in the admin or owner role. Three ways to declare the current user (priority order):

1. window.Ask2DoUser = { id, role } set before the widget script (best for SPAs).
2. data-panel-user + data-panel-role attributes (best for server-rendered HTML).
3. Just data-panel-role="admin" — if the entire panel is admin-only (your auth gate enforces it), this silences the pre-login console warning.

Security note: client-side role is a UX hint only. The cloud independently enforces role via the JWT's signed claim — a tampered widget cannot exceed the role baked into its JWT.

Configuration reference

Script-tag data-* attributes

Window globals

Built-in features

Everything below ships with the bundle. No flags, no config.

Customization

Brand colour

.ask2do-button,
.ask2do-overlay {
  --ask2do-brand: #6d28d9;        /* button bg + accents */
  --ask2do-brand-hover: #5b21b6;  /* hover state */
  --ask2do-brand-50: #f5f3ff;     /* light backgrounds */
  --ask2do-brand-700: #5b21b6;    /* deeper accents */
}

Position

Default position is bottom: 24px; right: 24px. Move with regular CSS:

.ask2do-button {
  bottom: 16px !important;
  right: auto !important;
  left: 16px !important;       /* flip to bottom-left */
}

Framework examples

Pick your stack. Each tab shows a complete copy-paste recipe.

<!-- app/layout.tsx (Next.js App Router) -->
<html lang="en">
  <body>
    {children}
    <Script id="ask2do-dispatcher" strategy="beforeInteractive">
      {`window.Ask2DoGetToken = async function () {
        if (typeof window.__ask2DoFetchToken === 'function') {
          return await window.__ask2DoFetchToken();
        }
        throw new Error('Ask2Do not ready: please sign in first');
      };`}
    </Script>
    <Script
      src="https://cdn.ask2do.com/widget.js"
      data-cloud-url="wss://cloud.ask2do.com"
      data-panel-role="admin"
      strategy="afterInteractive"
    />
  </body>
</html>

// After successful login:
window.Ask2DoUser = { id: user.id, role: 'admin' };
window.__ask2DoFetchToken = async () => {
  const r = await fetch('/api/ask2do/token', { method: 'POST' });
  return (await r.json()).token;
};

// On logout, wipe the dispatcher so the widget can't reuse stale auth:
delete window.Ask2DoUser;
delete window.__ask2DoFetchToken;

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          innerHTML: `window.Ask2DoGetToken = async function () {
            if (typeof window.__ask2DoFetchToken === 'function') {
              return await window.__ask2DoFetchToken();
            }
            throw new Error('Ask2Do not ready');
          };`,
          tagPosition: 'head',
        },
        {
          src: 'https://cdn.ask2do.com/widget.js',
          'data-cloud-url': 'wss://cloud.ask2do.com',
          'data-panel-role': 'admin',
          defer: true,
          tagPosition: 'bodyClose',
        },
      ],
    },
  },
});

<!doctype html>
<html>
  <body>
    <!-- ...your panel UI... -->

    <script>
      // Render this from your template engine with the current user.
      window.Ask2DoUser = { id: "{{ user.id }}", role: "{{ user.role }}" };
    </script>
    <script
      src="https://cdn.ask2do.com/widget.js"
      data-cloud-url="wss://cloud.ask2do.com"
      data-token-endpoint="/api/ask2do/token"
      defer
    ></script>
  </body>
</html>

<!-- index.html — inline loader, never needs to change -->
<script>
  (function () {
    var s = document.createElement('script');
    s.src = '/ask2do-bootstrap.js?t=' + Date.now();
    document.head.appendChild(s);
  })();
</script>

// public/ask2do-bootstrap.js — edit + redeploy WITHOUT rebuilding
(function () {
  if (window.__ask2DoBootstrapped) return;
  window.__ask2DoBootstrapped = true;

  window.Ask2DoGetToken = async function () {
    if (typeof window.__ask2DoFetchToken === 'function') {
      return await window.__ask2DoFetchToken();
    }
    throw new Error('Ask2Do not ready: please sign in first');
  };

  var s = document.createElement('script');
  s.src = 'https://cdn.ask2do.com/widget.js';
  s.defer = true;
  s.setAttribute('data-cloud-url', 'wss://cloud.ask2do.com');
  s.setAttribute('data-panel-role', 'admin');
  document.head.appendChild(s);
})();

Troubleshooting

Security model

Two independent gates:

• UI gate (advisory) — widget hides the button for non-admin/owner roles based on client-side panelUser.
• JWT gate (authoritative) — cloud checks the signed role claim on every WebSocket message. A tampered widget cannot escalate beyond the role its token endpoint baked in.

Audit log is hash-chained per tenant; see audit log schema. Tenant DB credentials never leave your sidecar (self-hosted) or our NaCl secretbox vault (cloud-hosted) — the widget bundle has zero access to them. Data-protection details →

Next steps

• Backend integration — minting JWTs from your tenant key.
• Install the sidecar — for self-hosted deployments.
• Audit log schema — what every approved write writes.
• Security architecture — the full threat model.