Build your own embed SDK: a chat widget in 6 decisions

Across this series I took five products apart. Here I put one back together. The target is a minimal SDK: the customer pastes one <script> line into their site and a chat widget floats in the bottom-right corner. I’ll make each of the six decisions the teardowns surfaced, explicitly, in code.

Requirements

• It works when the customer site (example.com) pastes one line: <script src="https://sdk.myapp.com/v1/latest/">
• A chat button floats in the bottom-right corner; clicking it opens a conversation window
• It doesn’t interfere with the customer site’s CSS, JS or cookies
• It sends and receives the conversation log with our own server (api.myapp.com)
• Encrypting chat history is out of scope (about as sensitive as video metadata)

Decision 1: iframe or DOM injection

The requirement not to interfere with the customer’s CSS and JS points to an iframe. Even if the customer mixes Tailwind and Bootstrap, our UI is unaffected. As a side benefit, the auth cookie stays confined to the myapp.com origin. The alternative, injecting into the DOM (Web Components), isolates CSS through shadow DOM but still shares window on the JS side. If the customer site has rewritten window.fetch, the side effects are hard to predict. A chat widget has a closed set of requirements, so the simple move is to pick an iframe and isolate the whole thing.

Decision 2: split the loader from the body

Do you keep the loader small to start fast, or ship a single file? I’ll split them this time.

• Loader (https://sdk.myapp.com/v1/latest/): around 5 KB; it creates the iframe and bridges postMessage, nothing more
• Body (the real code the loader pulls in, starting from https://sdk.myapp.com/v1/lib/iframe.html): the whole UI, ~300 KB

The main reason to split is the cache-control strategy (Decision 5). The loader is refetched every time so the version can be switched; the body lives at a hash URL and is cached for a long time. A single file can’t be split that way.

Decision 3: CSP and isolation inside the iframe

Response headers for iframe.html:

content-security-policy:
  default-src 'self';
  script-src 'self' 'nonce-<per-request-random>';
  style-src  'self' 'nonce-<per-request-random>';
  connect-src 'self' https://api.myapp.com wss://api.myapp.com;
  img-src    'self' data: blob:;

• script-src 'self' 'nonce-...': the server that delivers iframe.html issues a per-request nonce, and only <script nonce="..."> tags inside the iframe that match it execute
• connect-src limited to api.myapp.com: even if an XSS lands, data can’t be carried off to another domain
• No frame-ancestors (the whole point is to be embedded by customer sites)

A per-request nonce needs a server that delivers iframe.html dynamically with that header. Static hosting alone (S3 + CloudFront) can’t do it. You end up putting Cloudflare Workers or a CDN’s edge functions in front.

Decision 4: the postMessage contract

Parent and child share no state (the loader only creates the iframe and sets up the postMessage bridge; state lives in the iframe). A one-sided “ready” notification is enough of a handshake.

Protocol:

// child → parent (iframe finished loading)
{ type: "ready" }

// parent → child (the customer calls an SDK method)
{ type: "cmd", method: "open", params: {}, id: <number> }

// child → parent (method result)
{ type: "res", id: <number>, result: any, error: string | null }

// child → parent (state change notification)
{ type: "event", name: "message-received", data: {...} }

Check origin by exact match, and the sender with event.source:

// iframe side
window.addEventListener("message", (event) => {
  if (event.origin !== "https://example.com") return; // the customer site's origin (passed in by the loader)
  if (event.source !== window.parent) return;         // is the sender the parent that embedded us?
  // handle the payload
});

When two widgets are embedded on the same page, both iframes have the origin https://sdk.myapp.com, and origin alone can’t tell whether a reply came from your own iframe. So the loader side also checks event.source === iframe.contentWindow on top of the origin.

The loader tells the iframe the customer site’s origin. Concretely, it embeds the origin in the hash as iframe.src = ".../iframe.html#" + encodeURIComponent(location.origin), and the iframe’s JS parses location.hash on startup.

I don’t choose first-message trust. It leaves room for an attacker’s iframe to speak first, so while the implementation is young I’ll stay with the stricter exact-match design.

No encryption needed: the loader sends straight to the iframe’s window with a targetOrigin, so messages don’t reach sibling iframes or other tabs. They could be read if another script running on the customer’s page added a listener to the parent’s window, but that script could also rewrite postMessage or crypto.subtle itself, so I think in-page encryption would struggle to hold that line (this is reasoning; I haven’t tried it). I judged chat history to be about as sensitive as a video player’s data and left encryption out.

Decision 5: cache-control strategy

The loader is the “versioning contract”, so it is refetched every time. The body lives at a hash URL and is cached for a year.

Customers don’t choose a version. The loader is refetched every time, and on our side it always emits the latest body hash. Part 4 covers why this strategy follows naturally once you’ve chosen an iframe.

Decision 6: initialization style

I’ll make it imperative.

<!-- the code the customer writes -->
<script src="https://sdk.myapp.com/v1/latest/" async></script>
<script>
  window.MyAppChat = window.MyAppChat || [];
  window.MyAppChat.push(["init", { apiKey: "..." }]);
  window.MyAppChat.push(["setUser", { id: "user123" }]);
</script>

This is the deferred command queue pattern. Commands called before the SDK finishes loading are stored in an array (MyAppChat), and once the SDK has loaded it replays the array in order. Since customers don’t have to write callbacks, their code reads synchronously. Google Analytics’ gtag and others use this pattern, and it works in single-page apps and static HTML alike.

I’m not choosing Web Components (<my-chat>) here. With an iframe already in place, stacking Web Components’ isolation benefit (shadow DOM) on top adds little, and there’s no need to cut off environments that lack Web Components support.

Guarding against double load:

// at the top of the loader (put it inside an IIFE as in the skeleton below; a return outside a function is a syntax error)
if (window.__MyAppChatLoaded) return;
window.__MyAppChatLoaded = true;

Now if a customer accidentally writes the <script> twice, the second copy returns immediately. What this stops is only the SDK definition (replacing window.MyAppChat) running twice; the loader still creates one widget per init. To put two on the same page, write init twice (see the skeleton below).

Skeleton implementation

Loader (pseudocode):

(function() {
  // Only the SDK definition runs once. A widget is created per init
  if (window.__MyAppChatLoaded) return;
  window.__MyAppChatLoaded = true;

  const parentOrigin = location.origin;
  const targetOrigin = "https://sdk.myapp.com";
  let nextId = 0; // res comes back with the same id, so we can match it to its cmd

  // One widget: its iframe, its ready state, and the commands queued before ready
  function createWidget() {
    const iframe = document.createElement("iframe");
    iframe.src = "https://sdk.myapp.com/v1/lib/iframe.html#" +
      encodeURIComponent(parentOrigin);
    iframe.style.cssText = "position:fixed;bottom:20px;right:20px;" +
      "border:none;width:60px;height:60px;z-index:2147483647";
    // A visible iframe goes in body. If the loader runs in <head> before body exists, wait
    const mount = () => document.body.appendChild(iframe);
    if (document.body) mount();
    else document.addEventListener("DOMContentLoaded", mount);

    let ready = false;
    const queue = [];
    const send = (cmd) => iframe.contentWindow.postMessage(
      { type: "cmd", method: cmd[0], params: cmd[1], id: ++nextId },
      targetOrigin
    );

    window.addEventListener("message", (event) => {
      if (event.origin !== targetOrigin) return;
      if (event.source !== iframe.contentWindow) return; // tell it apart from other widgets on the same page
      if (event.data.type === "ready") {
        ready = true;
        queue.forEach(send); // replay the queued commands
      }
      // res / event handling omitted
    });

    return { push: (cmd) => (ready ? send(cmd) : queue.push(cmd)) };
  }

  // init creates a widget; later commands go to the most recently initialized widget
  let current = null;
  const push = (cmd) => {
    if (cmd[0] === "init") current = createWidget();
    if (current) current.push(cmd);
  };

  // Flush commands queued before the SDK arrived, then intercept window.MyAppChat.push
  const early = window.MyAppChat || [];
  window.MyAppChat = { push };
  early.forEach(push);
})();

iframe body (pseudocode):

const parentOrigin = decodeURIComponent(location.hash.slice(1));

window.addEventListener("message", (event) => {
  if (event.origin !== parentOrigin) return;
  if (event.source !== window.parent) return;
  const { type, method, params, id } = event.data;
  if (type !== "cmd") return;
  handleCommand(method, params).then(
    (result) => event.source.postMessage(
      { type: "res", id, result, error: null }, parentOrigin
    ),
    (error) => event.source.postMessage(
      { type: "res", id, result: null, error: String(error) }, parentOrigin
    )
  );
});

// signal that loading has finished
window.parent.postMessage({ type: "ready" }, parentOrigin);

That gives you the skeleton of the minimal build. On top of it you’ll need documentation for the imperative API, error handling, retries, accessibility (ARIA), internationalization, telemetry, CI/CD and CDN configuration. What’s written here is only the bones of the decisions; a production SDK puts flesh on them.

The six decisions at a glance

Mapped onto the five products covered across the series, this minimal SDK is a hybrid: Safie’s isolation approach, YouTube-style origin checks and a Google Analytics-style initialization queue. Each of those designs came out of its product’s economic and technical constraints. Recombining them to fit your own requirements is how I’d suggest using this series once you’ve read it.

Which one would you choose

The chat widget in this part falls into four of the situations in the table below: “must not interfere”, “may be embedded two or more times on the same page”, “customers split between static HTML and single-page apps” and “any shape”. When requirements change, so do the choices, so here is how to choose by situation. It’s the same table as on the series landing page.

Once the top two rows settle the shape, the versioning policy is settled with it.

I put a per-request nonce CSP in Decision 3 because, while the conversation log isn’t as sensitive as the “would hurt to leak” row, I still didn’t want it carried off. If you’re handling auth tokens or recorded footage and considering encryption, then as I wrote in Decision 4, in-page scripts can’t be fully kept out, so I expect you’d start from a design that at least never puts the key on the same postMessage channel (this is reasoning; I haven’t tried it).

Wrap-up and where to go next

An SDK where pasting one script line makes something work has quietly settled all six decisions behind the scenes. Actually reading the five products’ bundles showed that their answers branch cleanly, each worked backward from economic and technical constraints. When you build your own, get the requirements clear first, then choose decision by decision. That is the series’ argument as a whole.

Directions to go deeper:

• Observability: a design that catches errors inside the iframe and sends them to your own server, so window.onerror on the customer site stays clean
• A/B testing: switching the variant shown inside the iframe from your own side
• Privacy: using the fact that the iframe can’t access the customer site’s cookies to simplify GDPR/CCPA compliance
• Binary transport: carrying Protocol Buffers or Cap’n Proto over postMessage to cut JSON serialization cost

Your own SDK will need these one by one as it gets closer to production. Once the skeleton is built, I hope this series serves as a reference point as you extend it in each direction.

Measured 2026-08-08. The five products’ bundle IDs, keys and URLs will change, but these six decision axes won’t. Tear them apart again a year from now and the same framework should still read them.