# SiteList embeds — how to put your verified reviews on your own site

Every widget is a sandboxed iframe: no cookies, no localStorage, no scripts in
your page's DOM, GDPR-clean by construction. Your visitors' browsers talk only
to `sitelist.co`. Content is served CDN-cached and auto-resizes in place.

## Inline widget

Create a widget in your dashboard (Site → Widget), pick a variant, then copy
its snippet:

```html
<script async src="https://www.sitelist.co/embed.js"
        data-widget="wgt_XXXXXXXXXXXXXXXX"></script>
<div id="sitelist-reviews"></div>
```

The variant, theme, and all options live in the widget's dashboard config —
editing them updates every page the snippet is already on. (Legacy
`data-site="pub_…"` snippets keep working and render your default widget.)

Optional attributes: `data-mount="#my-container"` to control placement.

## Popup (floating) widget

Pro plans can run any widget as a floating popup instead of an inline block:

```html
<script async src="https://www.sitelist.co/embed.js"
        data-widget="wgt_XXXXXXXXXXXXXXXX"
        data-mode="popup" data-position="right"
        data-delay="3" data-hide-mobile="true"></script>
```

| Attribute | Values | Default |
|---|---|---|
| `data-position` | `left` \| `right` | `right` |
| `data-delay` | seconds before it appears | `3` |
| `data-hide-mobile` | `true` skips small screens | off |

Visitors can dismiss it; the dismissal holds for their browser session.

## Variants

Score: **badge** (200×64), **ring** (gauge), **summary** · Reviews:
**carousel**, **stack**, **grid** (masonry/uniform/quote, optional
screenshots), **marquee**, **hero**, **avatars** · Actions: **collect** ·
Web mentions (paid): **mentions** · Video (Pro): **video**, **multiclip** ·
Plus the hosted **Wall of Love** at `sitelist.co/wall/<your widget id>`.

Scores always link to their evidence — the full SiteList review. Stale scores
(no fresh crawl in 30 days) show "Fresh review pending" instead of a number, so an
embedded score is always a current one.

### Around the web (`mentions`)

A card list of public web posts, comments, articles, and videos about your
product — the ones **you** picked in your dashboard's Mentions tab. Each card
carries its platform, the title as a link back to the source, an optional short
excerpt, the author, and the age. Any paid plan can embed it; Starter can
feature 3 mentions at a time, Pro 10.

Two things this widget deliberately does not do:

- **It shows no star rating.** These are citations, not verified reviews — most
  carry no rating their author ever gave — so they never enter your SiteList
  rating and the widget renders no stars.
- **It always carries the disclosure line** "Selected by the site owner ·
  sourced from the web", which cannot be hidden. You choose what appears; the
  widget says so.

| Option | Values | Default |
|---|---|---|
| `max_mentions` | `1`–`8` cards shown | `8` |

Unfeaturing a mention (or a source link going dead) drops it from every embed
on the next cache refresh.

## Images for email, READMEs, and social

JavaScript widgets cannot run inside email. Use the image exports from your
dashboard's Share tab instead, always wrapped in their evidence link:

```markdown
[![SiteList rating](https://www.sitelist.co/api/widget/wgt_XXXX/image?kind=badge)](https://www.sitelist.co/sites/your-site/review)
```

In email HTML, wrap the `<img>` in an `<a>` to the same review URL. Never
embed a bare score image without its link.

## Restricting where your widget renders

Set **allowed domains** on a widget to stop other sites from embedding it.
Restricted widgets are never shared across CDN caches.

Questions: the full contract lives in this repo's `specs/ARCHITECTURE.md` §3.

---

*Maintainers: everything under `public/embed*` is generated by
`packages/widget/build.mjs` (`npm run build -w @sitelist/widget`); the build
fails hard past 2 KB gz (loader) / 50 KB gz (frame) and keeps the 5 newest
previous frame bundles for CDN-stale HTML. `manifest.json` is read by
`/embed/frame/[publicId]` at runtime.*