> ## Documentation Index
> Fetch the complete documentation index at: https://help.draftable.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Embedding comparisons in your app
> How to embed the Draftable comparison viewer directly into your own application with an iframe, and what the viewer does while it loads or fails.
You do not have to send users away to a Draftable URL to show them a comparison. The viewer can be embedded directly in your own application with an `iframe`, so the comparison appears as part of your interface.
## The basic embed
```html theme={null}
```
That is the whole integration. The viewer handles rendering, navigation between changes, and the side-by-side layout.
`allowfullscreen` lets users expand the comparison to fill their screen in most browsers. It is worth including: comparisons are detail-heavy, and a viewer confined to a small panel is hard to read.
## Embedding a private comparison
Comparisons are private by default, so in production your `src` will usually be a **signed** URL:
```html theme={null}
```
Generate the signed URL **on your server** and pass the finished URL to the page. Never ship your auth token to the browser to sign URLs client side, because anything your front end can read, your users can read.
See [Private and public comparisons](/hc/en-us/articles/Draftable-API-private-comparisons) for how signing works and how to choose an expiry.
## Sizing the iframe
An `iframe` will not size itself to its content. Give it an explicit height, or the viewer ends up in a short, unusable strip.
```html theme={null}
```
A viewport-relative height such as `85vh` with a sensible `min-height` works well, because it adapts to the user's screen while guaranteeing a usable size on small displays. Comparisons need vertical space more than anything else.
## What the viewer does on its own
The embedded viewer handles its own states, so you do not need to build loading or error handling around it.
| State | What the user sees |
| :-------------- | :----------------------------------------------------------------------------------------------------- |
| **Pre-loading** | With `wait` in the URL, a loading animation while the comparison has not been created yet |
| **Loading** | A loading animation while the comparison is being processed, and while the documents download |
| **Error** | A short error message on the page, with a fuller developer message in the browser's JavaScript console |
| **Ready** | The comparison itself |
### Comparison does not exist yet
By default the viewer returns **404** if no comparison exists with that identifier. If you create comparisons in a background job and want to embed the viewer immediately, add `wait` and the viewer shows a loading state until the comparison appears:
```
https://api.draftable.com/v1/comparisons/viewer/{account_id}/{identifier}?wait
```
This lets you render the page instantly rather than blocking on comparison creation. See [Creating a comparison](/hc/en-us/articles/Draftable-API-creating-a-comparison) for the rules on choosing your own identifiers.
### When a comparison fails
If a comparison is ready but failed, the viewer displays a brief message to the user and writes a more descriptive one to the **JavaScript console**.
That console message is the fastest way to diagnose an embed that is not working. It is usually specific enough to identify common mistakes, such as declaring the wrong `file_type` when the comparison was created. Check the console before anything else.
## Practical checklist
Build the signed viewer URL in your backend and pass it to the template. The auth token must never reach the browser.
Use a viewport-relative height with a minimum, not a fixed small pixel value.
Users will want it for dense documents.
A signed URL that expires while someone is still reading is fine, since an open viewer keeps working until refresh. One that expires before the page loads is not.
Otherwise the embed 404s for comparisons that have not been created yet.
## Related articles