Skip to main content
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

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:
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 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.
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.

​
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:
This lets you render the page instantly rather than blocking on comparison creation. See 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

1

Sign URLs server side

Build the signed viewer URL in your backend and pass it to the template. The auth token must never reach the browser.
2

Give the iframe a real height

Use a viewport-relative height with a minimum, not a fixed small pixel value.
3

Include allowfullscreen

Users will want it for dense documents.
4

Match the expiry to the page

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.
5

Use wait if you create comparisons asynchronously

Otherwise the embed 404s for comparisons that have not been created yet.

Private and public comparisons

Viewing and sharing results

Customizing your account and viewer

Handling errors and failures