Documentation

Including media in your survey

Upload images and videos as materials to use them in your survey. You can group related files in a named material and add metadata such as brand, campaign or product. Use those columns to choose which files to show or to group results in reports.

Uploading your media

Open materials in the survey or in the New Survey flow. Select Create → Upload files and name the material. To add files later, select the material and open the upload panel. Choose Secure or Non-secure before selecting the images or videos to upload.

New material dialog with Upload files, Import spreadsheet, and other creation options

ModeViewing and downloads
SecureProtected, watermarked image viewing and DRM video playback. Original-file and review-overlay downloads are unavailable.
Non-secureStandard viewing, original-file downloads for users with export permission, and eligible video-overlay MP4 downloads.

Image-highlighter reports use source originals, including Secure images, for analysis, display and PNG/ZIP composition. Those reports have their own access and download controls.

Choose Secure for confidential stimuli that need protected respondent viewing. Choose Non-secure when your study needs downloadable originals or review overlays. The mode is fixed when the asset is uploaded: editing metadata, replacing the file or retrying an upload does not change it. Upload the file under a new filename to use a different mode.

A new video can remain pending while processing finishes. Wait for it to become ready before testing or fielding the survey.

A padlock beside a filename marks Secure media. Users with export permission can use an enabled row download action to retrieve a Non-secure image or video's original file. The original-download action is disabled for Secure media.

Select an attachment to preview it. Use the row's Replace media action to swap in a new file. The replacement keeps the saved filename and security mode. Use Add column to store metadata, then edit the values in the grid.

Replace media dialog showing that the filename and secure viewing mode are kept

Images pasted with a questionnaire

When you paste a questionnaire with supported embedded images, choose Secure or Non-secure before saving. After upload, find the images in materials and check their placement in a survey preview. See Pasting an existing questionnaire for the full workflow.

Editing media metadata in Excel

Select the material and choose Excel above the grid. Edit the metadata in the downloaded .xlsx file, then choose Import above the same grid and select the edited workbook. Save your survey after checking the updated values.

Keep the worksheet name Material. Row 1 holds the column names, row 2 holds their types, and the remaining rows contain the data. Keep existing column names and types and preserve the unique ID on each row. For a file-based material keyed by file_name, upload new files in materials before adding their metadata to the workbook. Manage attachments and security in the workspace.

To add a metadata column, enter a lowercase name in row 1 using letters, digits and underscores, starting with a letter or underscore. Enter its type in row 2. Use text for labels, number for numeric values, boolean for TRUE or FALSE, or url for links. To remove or rename a column, use the column menu in the grid.

The platform checks the workbook before applying changes. If the import reports an invalid value, a missing column or a duplicate unique ID, correct the workbook and import it again.

Programming with survey media

Pass the material name to the image or video helper. This example uses a material named Creatives.

Code
for image in s.randomize(s.get_images("Creatives")): s.select_question("Do you like this image?", options=["Yes", "No"], image=image)

Read metadata from an attachment by its column name. This example asks about images whose ask_like column is true:

Code
for image in s.randomize(s.get_images("Creatives")): if image.ask_like: s.select_question("Do you like this image?", options=["Yes", "No"], image=image)

Use get_videos to select video attachments from a named material. Pass each result to play_video.

Code
for video in s.get_videos("Creatives", campaign="Spring launch"): s.play_video(video=video, start_message="Please watch this video.") # ... ask questions here

Use an image highlighter question to capture selected areas of an image and show them in cropped follow-ups. Crops retain the original asset's security mode. Images with EXIF orientation are oriented consistently before display, crop selection and analysis.

How media looks in the survey

You can include images in any question in the survey by using the show_image question to display the image for five seconds or more:

Including Media In Your Survey

You can also include the image in a question by using the image parameter

Including Media In Your Survey

Watermarking follows the security mode chosen at upload. You cannot switch it off by editing an existing media row. For an MP4 with dial results alongside a Non-secure video, use the Video Overlay download workflow.

Example Survey

Before running this example, upload images to a material named Creatives.

Below is an example survey that uses uploaded images:

python
from survey import Survey s = Survey(**globals()) # Introduction message s.show_message( "Welcome to the survey! We'll show you several images, and we'd like to know your opinion on each one. Please rate them based on your personal feelings about the style, emotion, and overall impression." ) # Consent question s.get_consent( consent_text="Before we begin, we need your consent to participate in this survey. Your responses will be kept confidential and used for research purposes only." ) # Screening Questions # Age question with termination for under 18 age = s.select_question( question="What is your age?", options=["18-24", "25-34", "35-44", "45-54", "55-64", "65 and above"], other_options=["Under 18"], ) s.terminate_if( age == "Under 18", reason="Sorry, but this survey is only for individuals aged 18 and above.", ) # Gender question s.select_question( question="What is your gender?", options=["Male", "Female", "Non-binary/Third gender", "Prefer not to say"], ) # Ethnicity question (USA-specific) s.select_question( question="What is your ethnicity?", options=[ "White", "Black or African American", "Asian", "Native Hawaiian or Other Pacific Islander", "American Indian or Alaska Native", ], other_options=["Other (please specify):"], ) # Hispanic or Latino origin question s.select_question( question="Are you of Hispanic or Latino origin?", options=["Yes", "No"] ) # Household income question s.select_question( question="What is your annual household income?", options=[ "Less than $25,000", "$25,000 - $49,999", "$50,000 - $74,999", "$75,000 - $99,999", "$100,000 - $149,999", "$150,000 and above", ], ) # Education level question s.select_question( question="What is the highest level of education you have completed?", options=[ "Less than high school", "High school diploma or GED", "Some college, no degree", "Associate degree", "Bachelor's degree", "Graduate or professional degree", ], ) # Core Questions for each image s.show_message("Now we'll show you a series of images and ask you a few questions about them.") # Loop through each image and ask the set of core questions for image in s.get_images("Creatives"): # Show the image first s.show_image(image) # How do you feel about the image? s.select_question( question="How do you feel about the image?", options=["Very Positive", "Positive", "Neutral", "Negative", "Very Negative"], image=image, ) # How likely are you to hang this image in your home? s.select_question( question="How likely are you to hang this image in your home?", options=["Very Likely", "Likely", "Neutral", "Unlikely", "Very Unlikely"], image=image, ) # What does this image remind you of, or what do you think it represents? (Open-ended) s.text_question( question="What does this image remind you of, or what do you think it represents?", image=image, ) # Closing message s.show_message( "Thank you for participating! Your responses will help us better understand how people connect with art." ) # Finalize the survey s.complete()