For the complete documentation index, see llms.txt. This page is also available as Markdown.

Upload an HTML prototype to a study

Study type
Availability

Usability tests

Intercept studies

AI moderated studies

Not every prototype lives in Figma, and not every prototype is ready to be published to a public URL. If you've got an HTML prototype—something you've built with AI or something that lives on your own computer—you can upload it to your study for use in task questions. Dscout hosts the file for you, so there's nothing to deploy and no share link to manage.

Uploads sit alongside the other two task stimulus options: Website and Figma prototype. A single task question can use one of the three, not a combination.

Supported file types

You can upload either a single .html file or a .zip containing a whole static site.

Requirement
Limit

File types

.html, .htm, or .zip

File size

25 MB or smaller

Unzipped size

100 MB or smaller

Files in a zip

500 or fewer

Inside a zip file, you can include pages (.html, .htm), stylesheets (.css), images (.png, .jpg, .jpeg, .gif, .webp, .avif, .svg, .ico, .bmp), fonts (.woff, .woff2, .ttf, .otf), and media (.mp4, .webm, .mp3, .wav).

Prepare an HTML file

Your prototype has to be completely self-contained. It can't load anything from the internet while a participant is using it. A few things to check before you upload:

  • Use relative paths. Paths that start with a forward slash (/) won't work.

  • Bundle every asset. Images, fonts, and stylesheets all need to be inside a single zip file. A hosted web font or a CDN link will be turned away.

  • Include an entry page. Your zip file needs either an index.html at the top level, or exactly one .html file at the top level.

  • Point forms inward. A form that submits somewhere outside your upload won't work.

Note: Zipping a folder from your desktop is fine. Dscout unwraps a single top-level folder automatically, and it quietly ignores things like __MACOSX, .DS_Store, and README files.

Upload an HTML file

You can upload an HTML file at the study level or from inside a task question. Either way, once a prototype is in your study, you can reuse it across as many task questions as you like.

To upload at the study level:

1

On the Usability test/Study/AI moderator tab of your study, click the Task stimuli button in the top right corner. The task stimuli management modal is displayed.

2

Click + Add task stimuli. Then, select Upload HTML.

3

Locate and select your .html, .htm, or .zip file. Then, click Open.

You'll see a progress bar while Dscout reviews your file. Keep the tab open until the upload finishes.

When the check passes, your prototype appears in the list with its filename and file size.

4

Click Done.

To upload from a task question:

1

While editing your task question, click Add beside Task stimuli. Then, select Upload HTML.

2

Locate and select your .html, .htm, or .zip file. Then, click Open.

You'll see a progress bar while Dscout reviews your file. Keep the tab open until the upload finishes.

Note: If your file doesn't pass the check, Dscout tells you what it found and where. For help fixing any issues, see Troubleshooting.

3

When the check passes, click Done.

Preview an uploaded file

You have to preview an uploaded prototype and confirm it before you can launch your study. This is a required step to make sure what participants see is what you meant to upload.

Note: If you replace a prototype after confirming it, you'll need to preview and confirm the new one before you can launch. The same goes for a prototype that comes along when you copy a study.

1

On the uploaded prototype, click the Preview (eye) icon. The Preview uploaded file modal is displayed. (To open it in its own tab instead, click the Open in new tab icon.)

2

Click through your prototype and check it looks and behaves the way you expect.

3

Click Looks good.

Now, you're ready to finish building your study.

If you head to launch before confirming your upload, you'll see a validation telling you to confirm the prototype. Click the validation to preview the prototype directly—you don't need to return to the relevant question.

Convert a prototype with AI

If you run into an issue uploading a prototype, there's probably something in your prototype that isn't supported, typically JavaScript. However, many interactions can be rebuilt using only HTML and CSS, which are both supported.

Here's a breakdown of some common prototype interactions and how well they can be reproduced without JavaScript:

Interaction
Works without JavaScript?
How it's rebuilt

Moving between screens

✅ Yes

Each screen becomes its own page, connected by links.

Tabs, accordions, and dropdown menus

✅ Yes

CSS techniques and built-in HTML elements reproduce behavior.

Pop-ups and modals

✅ Yes

A link opens a section styled as a modal.

Hover effects, transitions, and animations

✅ Yes

CSS techniques.

Image carousels

🟡 Partly

CSS-only carousel, without auto-advance timers.

Filling out and submitting a form

🟡 Partly

Participants can type, but the form can't submit. The "Submit" button becomes a link to a confirmation page.

Search, filters, and sorting

🟡 Partly

Pre-built result pages for a few example choices.

Logins, carts, and anything that remembers input

❌ No

Show example states as separate pages rather than user-specific inputs (for example, a cart with two items in it).

Live data, drag and drop, randomized content, and timers

❌ No

Replace with static example content.

If the above trade-offs work for your study, you can convert your existing prototype.

To convert your prototype:

1

Export or download your prototype files from the tool where you built it.

2

In an AI tool like Claude or ChatGPT, attach the exported files and send the following prompt:

sparklesConvert-to-HTML/CSS prompt

Your AI tool will respond with a feasibility report, describing each interaction in your prototype that needs rebuilding as well as how it will be rebuilt.

3

Reply to your AI tool to confirm.

Now, your prototype is converted to a version that only uses HTML and CSS. Test it on your computer to ensure it works as needed, then upload it to your Dscout study following the steps in Upload an HTML file.

What participants see

Participants open your prototype inside Dscout, the same way they would a masked task URL. A few things worth knowing:

  • Task URL masking is always on for an uploaded prototype (and can't be disabled). Participants never see a URL for your file. For more on masking, see Mask task URL.

  • Your prototype isn't public. Only participants in your study can open it, and they won't be able to access it again once they've finished the study.

  • Clicks are captured just like any other task (though heat maps are not generated). Click data shows up in analysis labeled by page (index.html, checkout.html, and so on). For more information, see Analyze heat maps and click data.

Manage uploaded prototypes

Every prototype you've uploaded lives in the Task stimuli manager, alongside your website and Figma links. Each one shows its filename, file size, and the questions it's attached to.

To reuse a prototype: click Add beside Task stimuli on any task question, then pick the prototype from Previously added. One upload can serve as many questions as you need.

To remove a prototype from a single question: click the Delete (trash) icon on the prototype in that question. The file stays in your study for reuse elsewhere.

To delete a prototype entirely: open the Task stimuli manager and click the Delete (trash) icon beside it. If it's attached to any questions, you'll get a confirmation first.

Note: You can't delete a prototype that's attached to a question in a launched study.

Troubleshooting

If your HTML upload doesn't pass, Dscout tells you exactly what went wrong and where. Here's what each message means and how to fix it.

What you'll see
What to do

Contains JavaScript (<script>)

Remove the script tags. Uploaded prototypes support HTML and CSS only.

Uses inline JavaScript event handlers

Remove onclick, onload, and similar attributes.

Contains a javascript: link

Replace it with a normal link to a page in your upload.

Uses an element that isn't allowed

Remove any iframe, embed, object, base, or meta refresh tags.

Contains an SVG with scripts, animation, or embedded styles

Re-export the SVG without scripting or animation, or swap it for a PNG.

Loads something from outside the file

Download the web font, CDN file, or image and include it in your zip.

Has a form that submits outside the file

Point the form at a page inside your upload, or remove the action.

References a path starting with /

Switch to relative paths.

References a file that isn't in the upload

Add the missing file, or fix the path.

Embeds a data: resource of a type that isn't allowed

Only images and fonts can be embedded this way.

Includes a file type that isn't supported

Remove it. .js files are the most common cause.

Has no index.html, and no single HTML page to open

Add an index.html, or reduce to one top-level HTML file.

Is larger than 25 MB

Compress your images, or trim unused files.

Is larger than 100 MB when unzipped

Compress your images, or trim unused files.

Contains more than 500 files

Remove anything the prototype doesn't need.

Contains file paths that aren't allowed

Re-zip without .. in any path.

Contains symbolic links

Re-zip with the real files instead of shortcuts.

Couldn't be read

Your zip file may be damaged, password-protected, or saved in an unusual format. Re-zip and try again.

Couldn't be checked

Something went wrong on our end. Try uploading again.

Other things you might run into:

Situation
What's happening

Your upload finished, but nothing changed

Your new file is identical to the one already attached to your task question, so there was nothing to swap. Make sure you're using the correct file and are looking at the intended task question.

You can't launch

A prototype still needs confirming. Preview it, ensure it works as expected, then click Looks good.

"There is nothing to preview for this upload yet"

The file is still being checked, or it didn't pass.

A participant lands back at the start of your prototype

Long sessions refresh the prototype periodically, which returns participants to the entry page.

Still stuck? Reach out to your Research Advisor or Dscout Support with your file attached.

Frequently asked questions

Who can see my uploaded prototype?

On your team, anyone who can manage the study can open, preview, and reuse the prototype. Uploads follow the same permissions as everything else in your study, so they're visible to your project members and nobody outside them.

On the participant side, only participants in that study can open it, and only while they're actively working through it.

Can someone open my prototype if they're not in my study?

No. Every time a participant opens your prototype, Dscout re-checks that they're the right participant and that their session is still active. If either check fails, they get a "not available" page instead—no prototype, and no link to one.

Is my prototype public, or findable through a search engine?

No. Your file is kept in Dscout's private storage, which isn't reachable from the open web. Every request for it has to carry a valid, time-limited access signature that Dscout generates, so there's nothing for a search engine to crawl and nothing to stumble onto by guessing a URL.

Where is my file stored, and is it encrypted?

Your file is stored in Dscout's private cloud storage and encrypted at rest. The storage isn't publicly accessible, and access to it is logged.

How long does Dscout keep my uploaded prototype?

Your prototype stays in Dscout for as long as it's part of your study. Removing it from a single task question doesn't delete it—it stays in the Task stimuli manager so you can use it elsewhere.

When you delete a prototype from your study entirely, Dscout permanently removes the file from its systems 37 days later.

Can my prototype collect data from participants?

No, intentionally. If you need to collect something from participants, use Dscout question types around your task rather than building it into the prototype.

Can I use my own analytics in an uploaded prototype?

No. Analytics tools need JavaScript, which uploaded prototypes don't support. Dscout's own click tracking still works, so you'll see what participants clicked and which pages they reached. For more information, see Analyze heat maps and click data.

Can I set a starting screen or success screen for an uploaded prototype?

No. Task flow settings—starting screen and success screen—are only available for Figma prototypes, and Set success URL only works with a website. An uploaded prototype always opens on its entry page: either index.html, or the single HTML page at the top level of your zip file.

If you want participants to begin somewhere specific, make that page the entry page of your upload. To measure whether they finished, use the Self-reported completion follow-up instead.

Can I control how my prototype is sized or scaled?

No. The scaling and device frame options in Prototype settings apply to Figma prototypes only. An uploaded prototype displays at whatever size your HTML and CSS specify, so build it responsively if your participants will be on a range of screen sizes.

Can I use an uploaded prototype in a mobile study?

Yes. Uploaded prototypes work in mobile usability tests as well as desktop studies.

Keep two things in mind: Because there are no scaling options for an uploaded file, your HTML and CSS decide how it looks on a small screen—so design it responsively, or participants will spend the task pinching and zooming. And participants won't have browser navigation controls while they're in your prototype, so make sure every screen they need is reachable from links inside it.

Can I test a prototype that requires a login?

No. Uploaded prototypes can't reach the internet or submit forms, so there's nothing for a login to connect to. A sign-in screen in your upload can be a visual mock, but it can't actually sign anyone in.

If you need to test something behind a real login, host it yourself and add it as a Website instead.

Can I replace my prototype after launching my study?

No. Once your study is live, the prototype attached to a task question is locked—you can't swap in a new file or delete it.

This is why previewing is required before launch. Click through the whole prototype while you're previewing it, not just the first screen, and make sure it's the version you want participants to see. For more on what can and can't change after launch, see Edit a launched screener or study.

Can I reuse an uploaded prototype in another study?

Not directly. An uploaded prototype belongs to the study you uploaded it to, and the Task stimuli manager only shows that study's stimuli. Within a study, you can attach one upload to as many task questions as you need.

If you copy the study, the prototype comes along—but you'll need to preview and confirm it again before the copy can launch. To use the same file in an unrelated study, upload it there as well.