# Embed (/share/embed)

The embed script adds the comment toolbar to your own site for reviewers who open an embed link, or for everyone when you [put the key on the script](#skip-the-link). Otherwise visitors see your site unchanged. Reviewers stay on your domain and signed in to your site, so embed works on staging behind a login and on protected preview deploys.

<Callout>Embed comes with the Pro and Team plans.</Callout>

## Install the embed script [#install-the-embed-script]

Add this to every page of the site, once:

```html
<script async src="https://api.annoty.app/embed/embed.js"></script>
```

Put it in your HTML `<head>`, in WordPress's header, or in a Google Tag Manager tag. The script is about 1 KB and does nothing until someone opens an embed link, unless it [carries the key](#skip-the-link). The dashboard shows the same tag under **Share → Embed** on any feedback session, and in the project's **Embed** tab.

### Content Security Policy [#content-security-policy]

If your site sets a `Content-Security-Policy`, in a header or a `<meta http-equiv>` tag, browsers block the toolbar until the policy allows it. Add these sources to its directives:

```http
script-src https://api.annoty.app;
connect-src https://api.annoty.app wss://api.annoty.app;
img-src https://api.annoty.app data: blob:;
style-src 'unsafe-inline';
```

The embed script loads the toolbar from `api.annoty.app` and connects to it there. The images are your team's logo and the screenshot that goes with a comment; the styles are the toolbar's own. A site without a policy needs none of this. If your policy is stricter:

- A directive your policy doesn't list falls back to `default-src`. Add it with `default-src`'s sources, then these.
- With `'strict-dynamic'` in `script-src`, put your page's nonce on the embed script tag instead of adding the source. The toolbar it loads is then allowed too.
- With a nonce or hash in `style-src`, browsers ignore `'unsafe-inline'`, and the toolbar shows unstyled.
- If the toolbar is still blocked, the browser console names the directive in its "Refused to load" message.

The prompt in the **Embed** tab has your coding agent make these changes too, and the dashboard shows the same lines under **Content Security Policy**.

## Share an embed link [#share-an-embed-link]

<Steps>

1. In the dashboard, open a project and click **New feedback session**. Leave **Proxy link** off: the feedback session gets only its embed link, so your site isn't on annoty.site. You can [add one later](/share/proxy/#add-or-remove-a-proxy-link).

2. Open the feedback session and click **Share**. The **Embed** tab has the embed script and the embed link. It looks like this:

   ```text
   https://staging.example.com/#annoty=rk_9x2k4m7q1c8z3v6b0n5l2p4w
   ```

3. Send it to your reviewers.

</Steps>

An embed link works in two places: on the host of the page you entered when you created the feedback session, and on [your dev server](#on-your-dev-server). A leading `www.` and the port don't matter.

### What reviewers see [#what-reviewers-see]

The toolbar appears as soon as the page loads. The embed script takes the key out of the address bar and remembers it in that browser, so reviewers can move between pages and come back later. The toolbar stays until they click **Exit review** in the toolbar's **Preferences**, or until the feedback session ends. It opens in the project's corner of the screen, or the one `data-position` on the embed script names: see [Toolbar position](/share/toolbar-position/).

<Callout title="If your router uses the # part">
  If your app's router reads the part of the address after `#`, put the key in
  the query instead: `https://staging.example.com/?annoty=rk_…`
</Callout>

## Project embed link [#project-embed-link]

One link for every page of your sites, instead of one per feedback session:

```text
https://example.com/#annoty=rp_4m7q1c8z3v6b0n5l2p4w9x2k
```

The embed script decides which feedback session it opens, so every branch or release can get its own without setting anything up in the dashboard.

<Steps>

1. Install the embed script, as above.

2. Open the project in the dashboard, go to the **Embed** tab and add your staging sites and preview deploys under **Allow your sites**. The project's domain works without that.

3. Copy the link under **Share the project embed link**, or add `#annoty=rp_…` to the address of any page on your sites.

</Steps>

### Choose the feedback session [#choose-the-feedback-session]

The project embed link reads two optional attributes on the embed script:

| Attribute      | What it does                                                                                                                                                                                              |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-session` | Names the feedback session the link opens. The first visit creates it; later visits reopen it. Turned into a slug, so `feature/Login` is `feature-login`. Leave it out for one feedback session per host. |
| `data-label`   | Its name in the dashboard, set when the link creates it. Defaults to `data-session`, then to the host. You can rename it later.                                                                           |

Set `data-session` to a release name for one feedback session per release, or to the branch so every preview deploy gets its own:

<Tabs items={["HTML", "Next.js on Vercel", "Vite"]}>
<Tab value="HTML">

```html
<!-- One feedback session per release -->
<script
  async
  src="https://api.annoty.app/embed/embed.js"
  data-session="spring-redesign"
  data-label="Spring redesign"></script>
```

</Tab>
<Tab value="Next.js on Vercel">

```tsx
// app/layout.tsx: Vercel sets VERCEL_GIT_COMMIT_REF to the branch
<head>
  <script
    async
    src="https://api.annoty.app/embed/embed.js"
    data-session={process.env.VERCEL_GIT_COMMIT_REF}
  />
</head>
```

</Tab>
<Tab value="Vite">

Build with `VITE_BRANCH` set to the branch: `VITE_BRANCH=$CF_PAGES_BRANCH npm run build` on Cloudflare Pages, `VITE_BRANCH=$BRANCH npm run build` on Netlify.

```html
<!-- index.html -->
<script
  async
  src="https://api.annoty.app/embed/embed.js"
  data-session="%VITE_BRANCH%"></script>
```

</Tab>
</Tabs>

### Allowed sites [#allowed-sites]

The project embed link works on the project's domain, on [your dev server](#on-your-dev-server) and on up to 3 allowed sites, which you set in the **Embed** tab. Each one is a host, or a pattern with one `*` in its first part for preview deploys:

| Host or pattern                | Matches                          |
| ------------------------------ | -------------------------------- |
| `staging.example.com`          | That host only                   |
| `*.my-app.pages.dev`           | Cloudflare Pages branch previews |
| `*--my-site.netlify.app`       | Netlify deploy previews          |
| `my-app-git-*-team.vercel.app` | Vercel branch previews           |

A `*` matches within one part of the host only, so `*.my-app.pages.dev` doesn't match `a.b.my-app.pages.dev`. Leave out the port: the host matches on every port, and a pasted address keeps only its host.

### On your dev server [#on-your-dev-server]

Every embed link and key also works on `localhost`, on any port, with nothing to set up. To see reviewers' comments on your local build while you fix them, put a feedback session's key on the embed script there:

```html
<script
  async
  src="https://api.annoty.app/embed/embed.js"
  data-key="rk_9x2k4m7q1c8z3v6b0n5l2p4w"></script>
```

Copy the key from the feedback session's **Share → Embed**. It works for every feedback session, the ones reviewers open with a proxy link too.

Open the page at the same path as on your site, `localhost:3000/pricing` for `example.com/pricing`, and its comments are there. Comments belong to a page's path, so the host and port don't change which ones you see.

For a feedback session the project embed link made, the project embed key works too, with `data-session` naming it. The project's **Feedback sessions** tab shows that name under **From project embed link**. A few more things to know on your dev server:

- Names ending in `.localhost`, like `my-app.localhost`, and `127.0.0.1` count as your dev server too.
- With the project embed key, a `data-session` that matches none starts a new feedback session, which counts toward your plan.
- Comments you post from your dev server go to the same feedback session, and your reviewers see them.
- Pins stay on the elements they were placed on. If your local version changed the page, a pin can point at a different element.

### Plans, ending rounds and regenerating the link [#plans-ending-rounds-and-regenerating-the-link]

- Feedback sessions the project embed link creates count toward your plan, like any other. They have no proxy link: [add one](/share/proxy/#add-or-remove-a-proxy-link) under **Share → Proxy** if you want it.
- To end a round, turn its feedback session off in the project's **Feedback sessions** tab. The project embed link then skips it and still opens the others.
- A feedback session's own embed link always opens that feedback session. The attributes don't change it.
- **Regenerate link** in the **Embed** tab ends every copy of the project embed link. Feedback sessions, their comments and their own embed links stay.

## Skip the link [#skip-the-link]

A preview behind a password or a login already keeps strangers out, so a link is one more thing to send. Put the key on the embed script with `data-key`, and everyone who loads the page gets the toolbar:

```html
<script
  async
  src="https://api.annoty.app/embed/embed.js"
  data-key="rp_4m7q1c8z3v6b0n5l2p4w9x2k"></script>
```

`data-key` takes the project embed key, from the project's **Embed** tab, or one feedback session's key, from **Share → Embed**. In the **Embed** tab, check **Include data-key** under **Install the embed script**, and the code for your platform carries the key.

The key works on the same sites as its link, and `data-session` and `data-label` work as they do with the project embed link. Embed links keep working on those pages, and a link opened in the browser takes precedence over `data-key`.

<Callout type="warn" title="The key is public on every page that carries it">
  Anyone who can open the page can read the key in its source and use it like
  the link: read and post comments and, with the project embed key, start
  feedback sessions on your sites. Use `data-key` on previews that a password, a
  login or preview protection already guards. On a public site, every visitor
  gets the toolbar.
</Callout>

To keep it off production, set it from an environment variable only your preview builds have. An empty `data-key` counts as none:

```tsx
// app/layout.tsx: ANNOTY_EMBED_KEY is set for Vercel's Preview environment only
<script
  async
  src="https://api.annoty.app/embed/embed.js"
  data-key={process.env.ANNOTY_EMBED_KEY}
  data-session={process.env.VERCEL_GIT_COMMIT_REF}
/>
```

With `data-key` on the script:

- **Exit review** hides the toolbar in that tab. A new tab brings it back.
- When the key stops working, because it was regenerated, its feedback session ended or the site isn't allowed, the toolbar doesn't show for the rest of the tab.
- **Regenerate link** in the **Embed** tab turns `data-key` off too, until you deploy the new key.

## Team members [#team-members]

Reviewers can resolve, reopen and delete only their own comments. To comment with your account and resolve anyone's threads, open the toolbar's **Preferences** and click **Sign in** next to **Team member?**. A dashboard window opens for a moment, so allow pop-ups for the site. You stay signed in on that site for 7 days. Signing in through a project embed link covers every feedback session of the project.

## Who can use an embed link, and what it stores [#who-can-use-an-embed-link-and-what-it-stores]

- Anyone with an embed link can read and post comments. Anyone with the project embed link can also start new feedback sessions on your allowed sites.
- Embed links work on `localhost`, so anyone with one can also open it from a page on their own computer.
- The key sits after the `#`, which browsers never send to your server, so it stays out of your server logs. With `data-key`, it's in your page's source instead, for anyone who can open the page.
- To stop an embed link, turn its feedback session off. To stop the project embed link, regenerate it.
- The toolbar keeps the reviewer's name and sign-in in your site's `localStorage`, where your site's own scripts can read them. A member's sign-in there covers one feedback session, or one project. For as long as the tab stays open, it also keeps the comments of the pages the reviewer visited in `sessionStorage`, so the next page shows them right away.
