Embeds

What an embed is

The join card

The campaign’s public facts and a Join button. No API key, no server, no website on the critical path: the id is all it needs. Choose Join card above for its snippet.

The certificate badge

One certificate, by its document number, through the public verify route and the holder’s own visibility. No API key and no server. Where the holder has not published it, the frame draws nothing, at zero height. It answers a number never issued the same way.

The status card

One person’s own outcome, read-only. This is the one widget with a server behind it. Your server mints a single-use load code, the loader posts it into the frame, and the frame draws from that code alone. The code never appears in a URL and the frame never holds a session.

curl https://campaign.udao.org/api/v1/embed-codes \
  -H "Authorization: Bearer camp_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
      "campaign_id": "8f2c6a1e-4b7d-4e39-a5c0-3d9e1f6b2a74",
      "email": "ada@example.com",
      "origin": "https://learn.example.ch"
    }'

It answers 200 with a code for every well-formed address, whether or not that person holds a place. The frame decides which card to draw and draws both at one height, so the call never tells you who joined. Each code is a read of your door. It spends one of your 600 reads a minute and writes one row on your Integrations page.

{ "code": "emb_load_...", "expires_in": 600 }

The join card and the badge each have a bare iframe; this widget has none. Its code never travels in a URL, so a script on the page posts it into the frame. An iframe address carrying a load code would put it in your server’s logs, in a referrer and in a reader’s history.

The mint refuses a request that carries a browser Origin. The API key belongs on your server: an API key in a bundle is an API key you have published. A partner with no server cannot ship this widget; the join card and the badge need none.

The origin you name has to be on your Allowed websites list, under Organization, then Integrations. An origin that is not there is answered 422 with the code origin_not_allowed and the list itself. The fix is one press in your dashboard, not a message to us. An API key for trial campaigns only may also name http://localhost with a port of yours, which is the one development address this door takes.

A retry mints a second code rather than replaying the first. The code is never stored, only a digest of it, so there is nothing for an Idempotency-Key to hand back. A code nobody loads is a row that expires in 10 minutes and costs you one read. Send the header if your client sends it everywhere: this endpoint accepts it and does not branch on it.

Single-page apps

The loader adds one global, CampaignEmbed, holding version ('1') and refresh(). It draws the containers on the page once, when it loads; CampaignEmbed.refresh() draws the ones your app has added since.

A container is drawn once: the loader marks it and never reads it again. To show another campaign, layout or code, remove the container and add a new one. The loader empties a container before it draws into it, so put nothing of your app’s inside.

A status container takes a code your server minted for that mount. A second mount of the same code within 60 seconds draws the same card; after that, mint a new one.

var box = document.createElement('div');
box.className = 'campaign-embed';
box.setAttribute('data-widget', 'join');
box.setAttribute('data-campaign', 'YOUR_CAMPAIGN_ID');
document.getElementById('your-sidebar').appendChild(box);
window.CampaignEmbed && window.CampaignEmbed.refresh();

Reference

Inherit is the reader’s setting, not your page’s

A frame is its own document, so inherit resolves to the operating system’s light or dark and cannot see a theme your stylesheet forces. A page that draws itself dark sets data-mode="dark". Reduced motion needs nothing from you: the frame reads it from the reader’s own system.

The height

The frame posts { source: 'campaign-embed', id, height } to the page on load, on resize and on a change of state. The loader sets the height and nothing else. It ignores a message whose origin is not ours or whose id it did not create, and it clamps the height at 1200px. Each layout carries a minimum height so the first paint does not jump: 96px for Row and 180px for Card. Without the loader the frame is a plain iframe and you own the height: its tab prints one. A bare iframe posts the same message and you may listen for it yourself.

The certificate badge’s iframe prints 182px for Row, its tallest reading, at 320 where its first line wraps. It settles at 156px from 400 up, and for Card it prints 226px. A badge that draws nothing is taken to zero by the loader, and under a height of your own it leaves a blank rectangle.

The colour you choose

The frame measures your accent against our surface on each ground it draws. On a ground where it falls under 4.5:1 for text or 3:1 for a control, ours stands in on that ground, silently. Only the configurator above and your dashboard say so, with the nearest shade that passes. Match the reader judges the light and the dark ground each on its own. The label on a filled button is chosen for your colour, white or our charcoal, whichever clears 4.5:1 on it. The mark’s own dot, the focus ring, every state colour and the type are never themeable.

The loader itself

One file at 2 addresses. The first is mutable, so a correction reaches every page carrying it. The second is the same bytes at an address that cannot change under them, for a policy of yours that pins what it loads. This build is 3050 bytes.

https://campaign.udao.org/embed/v1/loader.js

https://campaign.udao.org/embed/v1/loader.813f8b6a71ee7089.js

One file, one global, and our own build checks refuse any version of it that carries fetch, XMLHttpRequest, a cookie or any storage at all.

The load code: 10 minutes, and what it binds

Spent on first use means spent once, with one exception that costs nothing. For 60 seconds after the first load, a second mount of the same frame is answered with the same card. It is the same card and not a second reading, so a state that changed in between draws the join card instead. After those 60 seconds the code is finished, whatever else is true of it.

Where a widget may load

The status frame loads only from the exact origins on your Allowed websites list, under Organization, then Integrations. Each is https, port 443, the host alone, no wildcard and no path. The one exception is localhost, taken only under an API key for trial campaigns only. It lets you exercise the one widget with a server behind it in development. The card drawn there carries Simulated like every other trial. It is one list, shared with the rule that decides where a join link may return a person. Only an owner may change it, under a signature from the last 10 minutes. The join card and the certificate badge load anywhere.

What the frame does when it cannot draw

What we set on every embed route

No cookie, no session, no store. noindex, so a widget of yours never competes with your own page in a search index, and Referrer-Policy: no-referrer. A 60-second edge cache, and one title we write naming the widget, because a frame with no title is announced as "iframe". Inside, one group with a label and no heading of its own, so your page keeps its outline.

Every other page of ours refuses to be framed at all. The default on this deployment is frame-ancestors none, and the widget routes are its only exception. The sample the configurator draws, and the preview of an organization’s own campaign before it is public, are framable by our own pages alone.

If your page sets a Content Security Policy

Admit our origin for the loader and for the frame it creates:

Content-Security-Policy: script-src 'self' https://campaign.udao.org; frame-src https://campaign.udao.org