Back

Guide

How to Embed a Third-Party Widget in Your SaaS

November 8, 20268 min read

Short answer: embed it as an iframe, put it where your user is already doing the job it helps with, let it report its own height, and theme it from the outside with your colours and fonts. Check the origin of every message, keep secrets out of the URL, and decide up front who signs the user in and who charges them. Done that way, a third-party widget reads as a feature of your product, not a stranger's page glued into it.

This is the host's side of a widget integration: you are adding someone else's capability to your product so your users can use it, and buy it, without leaving. The owner's side, packaging a feature so others can embed it, is in how to build an embeddable widget.

What are the three ways to embed a third-party widget?

  • An iframe. The widget runs on its owner's origin inside a frame on your page. Its code, styles and crashes stay in the frame. The trade: you can't restyle the inside, and the two sides talk only through postMessage.
  • A script tag. The owner's JavaScript runs in your page and draws into a div you provide. It can match your layout perfectly, and it can also read your DOM, collide with your CSS and slow your page. You are trusting it with everything your own code can do.
  • An SDK or API. You build the screen yourself and call the owner's endpoints. Full control, and full maintenance: every change on their side is work on yours. That is a different decision, covered in widget vs API integration.

For a feature dropped into a SaaS screen, the iframe is the right default. The honest exception: if the widget must react to things on your page that you can't hand it as data (a cursor, a selection, a live editor), a script or an SDK is the better tool, and you should accept the access that comes with it.

Where should the widget sit in your product?

Where the job happens. A widget that sits on a settings page nobody visits is an integration nobody uses. Most embeddable widgets support three placements, and Ordana's embed contract names them with one mode parameter:

  • card — inside one of your existing screens, next to the work. It should work from about 280px wide, so it fits a sidebar as well as a main column.
  • page — its own full page in your navigation, for a feature big enough to be a destination.
  • modal — opened from your own button, for something users need now and then, at a specific moment.

Placement is a product decision, not a technical one. Ask what the user was doing a second before they would need this, and put it there.

How do you size an iframe widget so it never scrolls inside itself?

A fixed-height iframe either clips its content or leaves a gap. The fix is to let the widget tell you its height. On Ordana every embed posts an ordana-widget:resize message whenever its content height changes, and the host adds one listener, once:

<iframe
  src="https://widget.example.com/embed?key=wak_YOUR_KEY&mode=card&accent=%230f766e&radius=12"
  title="Invoice check"
  style="width:100%;height:420px;border:0;display:block"
  loading="lazy"
  allow="clipboard-write"></iframe>

<script>
  window.addEventListener("message", (e) => {
    if (e.data?.type !== "ordana-widget:resize") return;
    document.querySelectorAll("iframe").forEach((f) => {
      if (f.contentWindow === e.source) f.style.height = e.data.height + "px";
    });
  });
</script>

The key is your product's attachment key. It is public, not a secret: it only tells the widget which product it is in. If you would rather size a box yourself, pass fit=fill and the widget fills it and scrolls inside, instead of reporting its height.

How do you make a third-party widget look like your product?

Through its URL, not your stylesheet. A widget worth embedding takes design settings as parameters. Ordana's are the same for every widget:

  • theme (light or dark), accent and accent_text for buttons and links.
  • bg, surface, text, muted and border to match your card's colours.
  • radius (0 to 24px), font and heading_font (Google Fonts, loaded on demand), and font_size (12 to 18px).
  • density (compact, comfortable or spacious) and button (solid or outline).
  • frame=none when your own card already frames it, and chrome=host when you want to draw the widget's header with your own components.

Pass your real tokens, not approximations. The difference between "an embed" and "a feature" is mostly the last 10% of spacing, font and colour.

How do you embed a widget securely?

  1. Check the origin of every message. In each listener, compare event.origin with the widget's origin before you trust event.data.
  2. Post to the exact origin, never "*". Anything you send into the frame goes to the embed's origin, so it can't be read by a page that replaced it.
  3. Allow the origin in your CSP. Add the widget's origin to frame-src, and only that origin.
  4. Sandbox it if you sandbox at all, with what it needs. A widget that signs people in and takes payment opens a popup, so it needs allow-scripts, allow-forms, allow-popups and allow-popups-to-escape-sandbox. allow-same-origin is only safe because the widget is on a different origin from your app.
  5. Keep secrets out of the URL. A public key is fine. An API secret in an iframe src is a leaked secret.

Who handles sign-in and payment inside the widget?

This is the question most embeds skip, and it decides whether the widget earns anything. There are two setups on Ordana:

  • Your accounts, your checkout. If your product has its own sign-in, your server signs a short-lived token and posts it into the widget (ordana-widget:identity, in answer to ordana-widget:signin). The widget knows the user without a second login. If you also run your own checkout, you can charge your users yourself and buy each user's seat from Ordana at the widget's wholesale price, which is the offer price less the host's share.
  • Continue with Ordana. If you don't have accounts or a checkout, the user signs in with one Ordana account and pays from one wallet, inside the widget. Ordana takes the payment and pays your share automatically.

Either way, the user signs up and pays inside the widget and it updates in place. No redirect to a stranger's site, which is the whole point: while one of our own offers lived inside a partner's product, 32% of the founders who clicked through signed up; once it was one link among several, 7% (the full story).

How do you pass data between your product and the widget?

Some widgets declare fields they can take from you and results they can hand back. On Ordana the widget posts ordana-widget:ready on every load, and you answer with ordana-widget:context, even with empty fields. What you pass in shows up as a visible prefill the user can change. It never starts a use or an AI call by itself.

Results come back as ordana-widget:result, and only after the user has said yes to keeping your product updated. Accept them only from the embed's origin and keep only the keys the widget declared. All of it moves in the user's browser; none of it goes through Ordana.

What does embedding a widget look like on Ordana?

  1. Pick a widget from the widget directory. Adding a listed one needs no application and no approval.
  2. Copy one prompt into your own coding agent. It asks you where the widget should sit and how it should look, builds it, wires the tracking and ships it. Ordana never reads your repository.
  3. Paste back the JSON report the agent ends with. The integration goes live.

The terms were set before you arrived: the owner chose the price, the free uses and the share you keep (between 10% and 90%), and has to give hosts 30 days' notice before changing them. Free uses are capped per host, so an expensive feature can't run up the owner's bill through your product.

When should you not embed a widget?

When the capability is your product. If users pay you for this exact thing, embedding someone else's version hands away the part you should own. And if you need the data more than the screen, a sync into your own model and your own UI, you want their API, not their widget. The rest of the time, the question isn't whether you could build it. It's whether building it is the best use of your next month.

Frequently asked questions

Should I embed a third-party widget with an iframe or a script tag?

An iframe, unless the widget genuinely needs to read or change your page. An iframe keeps the widget's code, styles and failures out of your app; a script tag runs inside your page with the same access as your own code. Most widgets a SaaS adds into a screen only need an iframe plus a few postMessage events.

Can I change how an embedded widget looks?

From the outside, yes: a well-built widget takes theme settings in its URL, such as your accent colour, background, corner radius, font, spacing density and button style, so it matches the screen around it. You cannot restyle the inside with your own CSS, and that is on purpose: the owner has to be able to ship fixes without breaking your copy of it.

Is it safe to embed a third-party widget in my app?

It is safe when you treat the frame as another origin. Check event.origin on every message you receive, post your own messages to the widget's exact origin and never to "*", add the widget's origin to your Content-Security-Policy frame-src, and keep secrets out of the embed URL. A public attachment key in the URL is fine; an API secret is not.

Do my users need a separate account to use an embedded widget?

Not if your product has its own accounts. On Ordana, a host with its own sign-in signs a short-lived token on its server and the widget recognises the user without a second login; a host that also runs its own checkout can bill its users itself. Hosts without their own accounts use Continue with Ordana: one Ordana account and one wallet, used across every widget.

Does the data I pass to an embedded widget go through Ordana?

No. Shared-context fields move between your page and the widget in the user's browser with postMessage. Anything you pass in is shown as a prefill the user can change and never starts a use on its own, and results come back only after the user agrees to keep your product updated.

On Ordana, startups list features as widgets with their terms already set, and other startups embed them with one prompt in their own coding agent. Browse the widgets worth adding to your product, or list your own.

Related reading: