Reference
Embed reference
The snippet, every attribute it takes, where it will and won't run, and what to check when nothing appears.
No build step · No package to install · Works on any page you can paste HTML into
The snippet
Two lines. Anything you don't set falls back to what the widget has saved in your dashboard.
<!-- Paste where you want the widget to appear --> <div data-widget="pk_your_widget_key" data-sg-accent="#ea580c"></div> <script src="https://www.auroradonate.com/embed.js" async></script>
The div, once per widget
It marks the spot. Put it exactly where the widget should appear, in the page's own HTML.data-widgetcarries your widget's public key, which is on the Go live screen in your dashboard — everything else on it is optional.The script tag, once per page
One tag mounts every widget on the page, however many divs you have, so adding a second widget does not mean adding a second tag. Leaveasyncon it. Head or end of body, it makes no difference: it waits for the page's HTML to finish parsing before it mounts anything.
Attributes
All optional except the first. You only need one here when a single page should differ from the rest — otherwise change it in the dashboard once and every embed follows.
| Attribute | Takes | If you leave it off |
|---|---|---|
| data-widget | your widget's public key (pk_…) | required |
| data-sg-accent | a hex color, e.g. #ea580c | the widget's saved accent |
| data-sg-appearance | light / dark | the widget's saved appearance |
| data-sg-radius | sharp / rounded / pill | the widget's saved corner style |
| data-sg-font | a CSS font stack, or auto to match the surrounding page | the widget's saved font |
| data-sg-partner | a partner slug, for attribution only | none |
Where it can and can't go
The widget is an iframe, and the second column is what follows from that.
Fine
- Any page on your own site — homepage, campaign page, blog post, footer.
- A shop's cart page, with the widget set to the compact layout in your dashboard.
- As many widgets on one page as you want. The script finds all of them.
Won't work
- A hosted checkout page. Most platforms run those in a locked-down sandbox that will not host a third-party iframe at all — the cart page is as far as the widget reaches.
- Inside an email. Email clients don't run scripts; use the newsletter block instead.
- A div that only appears after the page has loaded — a tab that renders on click, a route change in a single-page app. The script mounts what it finds once and nothing rescans afterwards.
If it doesn't appear
Five checks, cheapest first. In practice it is almost always one of the first two.
The script tag is present exactly once
Two copies race each other and the second one finds every div already marked as mounted, so it does nothing. One is enough for any number of widgets.The key is the public key from the Go live screen
It starts with pk_. A widget id copied out of a dashboard URL looks similar and is not the same string.The div is in the page's HTML when the page loads
If your page builder or your app renders that part of the page later, the script has already run and moved on.Your theme isn't hiding the div
A container with display:none on mobile, or a zero-height wrapper, hides a widget that mounted perfectly well.Your own Content-Security-Policy allows us
If your site sends one, it has to permit a script and a frame from our domain. This is the check people reach last and it is the one that produces a completely blank space with an error only in your browser's console.
Height, and the one event your page can listen for
The frame opens at a fixed height and then reports its real height to your page, and again every time the content changes, so it grows and shrinks with what is inside it instead of scrolling within itself. You do not have to do anything for that to work.
When a donation completes, the widget tells your page. The script hands that to you as an ordinary DOM event fired on your own div, so a merchant thanking a shopper for also supporting a nonprofit adds one listener to the element they already put on the page. The payload is the amount and how many needs were filled — never a donor's name or email address.
We hand you that event rather than letting you write your own message handler on purpose: the origin and frame checks are easy to get subtly wrong, and getting them wrong on a cart page is a vulnerability rather than a bug. The names are a stable interface we do not change. Ask and we will send them.
Put your first need in front of a donor
Create your account and build a widget for free. Free — Aurora takes nothing from any gift, and we ask your donors for an optional contribution instead — or $0.99 an update, with your donors never asked.