Including media in your survey

Including media like images and videos in surveys to capture authentic consumer responses in scenarios where visual and emotional engagement are essential. For example, when testing ads or movie trailers, visuals allow respondents to provide feedback on elements like emotional impact, message clarity, and overall appeal. This leads to more accurate insights into how the target audience might react before launching a campaign or product.

Media is also essential in product testing, where the design and presentation play a significant role in consumer perception. By showcasing a product through images or videos, companies can gather valuable feedback on its appearance, functionality, and perceived value. This helps refine product features or packaging before they hit the market, ensuring they meet consumer expectations and preferences.

In the MX8 Labs Research Platform, adding media to your surveys is straightforward, and you can upload media in the media tab for your survey:

Uploading your media

You upload media in the "Media" tab of the survey:

When you first upload a video, the thumbnail will appear as pending while the video is ingested and encoded in our systems:

You can then add additional columns to the media to provide extra metadata for each media item. This metadata will be available to access within the survey code and will also be appended to any questions about that specific media:

Editing media metadata in Excel

When you have many media items, editing metadata one cell at a time can be slow. The MX8 Labs Research Platform lets you download the Media table as an Excel (.xlsx) workbook, edit the metadata in a spreadsheet, and upload your changes back in bulk.

The workbook edits metadata only. It does not upload, replace, or delete the underlying image and video files, and it cannot add or remove media items. To add or replace media files, use the upload controls described above.

Downloading the workbook

Use the "Download" button above the Media table to save the current metadata as an .xlsx file named media-of-survey-<survey id>.xlsx.

The workbook contains a "Media" worksheet laid out in three parts:

• Row 1 holds the column names, such as file_name, security, and any columns you have added.
• Row 2 holds the column type for each column: text, number, boolean, url, or state, plus the system types file_name, thumbnail, and security.
• Row 3 onward holds one row per media item.

Keep rows 1 and 2 intact. The type row tells the platform how to interpret each column when you upload the workbook, and the worksheet must still be named "Media".

You can edit the workbook in Excel or Google Sheets. Round-tripping through Google Sheets is supported, so you can open the file in Sheets, edit it, and export it back to .xlsx.

Editing values

For each media item you can edit the values in any non-protected column:

• Text columns accept any value.
• Number columns must contain a valid number.
• Boolean columns must contain TRUE or FALSE.

Empty cells are always accepted, whatever the column type. Leave any rows and columns you do not want to change exactly as they were downloaded.

Adding and removing columns

The workbook is also a quick way to restructure your metadata columns:

• Add a column by adding its name in row 1 and its type in row 2, then filling in the values. The type you declare must match the values you enter, so a column typed as number must contain only numbers. Use lowercase letters, numbers, and underscores for the name, starting with a letter or underscore, so you can access it from survey code.
• Remove an optional column by deleting it from the workbook.
• Change an optional column's type by editing row 2, as long as the existing values are valid for the new type.

How rows are matched

Each row is matched to an existing media item by its file_name value, and the set of rows must match the Media table exactly. Keep every file_name cell exactly as it was downloaded, and do not add or delete rows: a workbook containing a file_name that is not in the survey, missing one that is, or repeating the same file_name twice will be rejected.

Protected system columns

Three columns are protected and must be present and unchanged:

• file_name — identifies the media item and is used to match rows.
• thumbnail — the generated preview image for the item.
• security — controls the IP address watermark described below.

Their column types in row 2 must also stay as downloaded. Edits to file_name or thumbnail values are discarded in favor of the values already on the platform, and a changed security value is reported as an error. If your survey has a state column showing video encoding progress, that value is maintained by the platform and there is no reason to edit it.

Validation is all-or-nothing

When you upload the workbook, the platform validates the whole file before applying anything. If any check fails, the entire upload is rejected and the Media table is left unchanged, so you never end up with a partially updated table. A dialog lists each problem with its row, column, and message. Fix the reported problems and upload again.

Common validation errors include:

• A file_name that does not match a media item, a missing file_name, or the same file_name twice.
• A missing protected column, or a change to a protected column's type or security value.
• A value that does not match its column type, such as text in a number column or a value other than TRUE/FALSE in a boolean column.
• A new column with no type in row 2, or a declared type that does not match the values in that column.

Saving your changes

A successful upload updates the Media table with your edited metadata and confirms with a "Workbook imported successfully" message. As with any other change, you must still save the survey for the update to take effect.

Programming with survey media

You can access the media within the survey using the s.media object, for example:

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

You can also access the metadata by using dot access; in this example, there is a column "ask_like" on the metadata, which is set for items that should have the like question asked:

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

The video works just the same way, and you can play with the play_video function. Use get_videos to select the videos from the media collection, e.g.

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

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:

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

If you don't want to include the IP address watermark, you should uncheck the security checkbox in the media section of the survey:

Example Survey

Below is an example survey that uses uploaded images:

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

    # 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()