Wistia

to the tippy ↑

Embed Options and Plugins

Embed options and Plugins are useful when building an embed code or customizing your embeds programmatically.

Embed Options are essentially attributes for the behavior of your video - fullscreenButton, for example, is a boolean that controls whether the fullscreen button is shown on your player or not.

Plugins are additional scripts you can add to your video, giving it new functionality and adding new interfaces. Turnstile, for example, is an email collector you can add to your video by including the plugin.

Glitch

Try embed options before writing any code: Embed Options Demo.

Using Embed Options

When you add embed options to your embed code using the approach outlined below, it will override any conflicting customizations (i.e. if you set playerColor inline, and if you've already set it in the GUI, your inline attribute will be used).

Setting options on Standard and Popover embeds

Options can be set in two ways on Standard embeds and Popover embeds (which are actually just Standard Embeds with a special option). First, the most common method is to add class in the form option=value. Multiple options are separated by spaces. If an option value has spaces, you can percent encode it.

wistia_html.html
1
2
3
4
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_5bbw8l7kl5
videoFoam=true playerColor=ff0000"
style="width:640px;height:360px;">&nbsp;</div>

If you have more complex options or need to generate them on the client side, you can use window._wq to set them with a javascript object literal:

Note

Options defined this way will only take effect if they are pushed onto _wq before the video is embedded.

wistia_html.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<script>
window._wq = window._wq || [];
_wq.push({
  id: "5bbw8l7kl5",
  options: {
    videoFoam: true,
    playerColor: "ff0000",
    plugin: {
      "requireEmail-v1": {
        lowerText: "Thanks in advance!"
      }
    }
  }
});
</script>
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_5bbw8l7kl5" style="width:640px;height:360px;">&nbsp;</div>

Setting options on iframe embeds

Options can only be set one way with iframe embeds. It is similar to the option=value syntax of Standard embeds, but every option and value must be percent encoded and separated by an &. The first character after the video's hashed ID must be a ?.

wistia_html.html
1
2
<iframe src="//fast.wistia.net/embed/iframe/abcde12345?videoFoam=true&playerColor=ff0000" allowtransparency="true" frameborder="0" scrolling="no" class="wistia_embed" name="wistia_embed" allowfullscreen mozallowfullscreen webkitallowfullscreen oallowfullscreen msallowfullscreen width="640" height="360"></iframe>
<script src="//fast.wistia.net/assets/external/E-v1.js" async></script>

Percent encoding

Need a quick way to percent encode some values? Look no further! Type your value in the box below and copy the percent encoded version.

Note that, if you have mykey=myvalue, you must encode both mykey and myvalue separately; you don't want to include the = in your percent encoding!

Setting options using the Customize API

You can update embed options saved on Wistia's servers using the API. This way, wherever you embed your video, it will inherit the customizations you've defined. Visit the Customize API documentation to see how.

NOTE: When using the Customize API to update embed options, you never need to percent encode any option names or values.

Options List

These options are for use with the Customize API and Construct an Embed Code guide.

autoPlay

If set to true, the video will play as soon as it's ready.

NOTE: autoPlay will not work on iOS and other mobile devices due to restrictions on bandwidth on cellular networks. You can find more information on these restrictions in the Player API Documentation.

Tip

If you're using your Wistia account you can set a video to autoplay right within the Customize panel. Check out our help page for all of the details.

controlsVisibleOnLoad

If set to true, controls like the big play button, playbar, volume, etc. will be visible as soon as the video is embedded. Default is true.

On mobile devices, this option has no effect (beyond hiding/showing the big play button) because the player will be using native controls.

doNotTrack

By default, data for each viewing session is tracked and reported back to the Wistia servers for display in heatmaps and aggregation graphs. If you do not want to track viewing sessions, set doNotTrack to true.

email

Associate an email with this video's viewing session. This is equivalent to running video.email(email) immediately after initialization.

endVideoBehavior

This option determines what happens when the video ends.

Possible values are:

  • "default": The video stays on the last frame.
  • "reset": The video shows the thumbnail and controls if they are set to be visible on load.
  • "loop": The video plays again from the beginning.

fullscreenButton

If set to true, the fullscreen button will be available as a video control.

NOTE: iframe embeds must have "allowfullscreen" attributes for this option to be meaningful. If "allowfullscreen" attributes are missing, then the fullscreen button will not appear.

NOTE: On mobile devices where we use native controls, this option has no effect.

googleAnalytics

If you're using Google Analytics on the page where you embed a video, the video will auto-magically send events to your Google Analytics account 📈. Learn more about that here.

If you don't want a video to send those events to Google Analytics, set this embed option to false.

playbackRateControl

If set to false, the playback speed controls in the settings menu will be hidden.

playbar

If set to true, the playbar--which includes the playhead, current time, and scrubbing functionality--will be available. If set to false, it is hidden.

NOTE: On mobile devices where we use native controls, this option has no effect.

playButton

If set to true, the big play button control will appear in the center of the video before play.

playerColor

Changes the base color of the player. Expects a hexadecimal rgb string like "ff0000" (red), "000000" (black), "ffffff" (white), or "0000ff" (blue).

playlistsLinks

The playlistLinks option lets you associate specially crafted links on your page with a video, turning them into a playlist. For information about how this works, check out the Embed Links documentation.

playlistLoop

When set to true and this video has a playlist, it will embed the first video once the last video has finished.

preload

For html5 players, sets the video's preload property. Possible values are "metadata", "auto", and "none", true, and false. The values true and false are synonyms for "auto" and "none", respectively.

qualityControl

If set to false, the video quality selector in the settings menu will be hidden.

qualityMax

Setting a qualityMax allows you to specify the maximum quality the video will play at. Wistia will still run bandwidth checks to test for speed, and play the highest quality version at or below the set maximum. Accepted values: 224, 360, 540, 720, 1080, 3840.

Keep in mind, viewers will still be able to manually select a quality outside set maximum (using the option on the player) unless qualityControl is set to false.

qualityMin

Setting a qualityMin allows you to specify the minimum quality the video will play at. Wistia will still run bandwidth checks to test for speed, and play the highest quality version at or above the set minimum. Accepted values: 224, 360, 540, 720, 1080, 3840.

Keep in mind, viewers will still be able to manually select a quality outside set minimum (using the option on the player) unless qualityControl is set to false.

seo

If set to true, the video's metadata will be injected into the page's on-page markup. Set it to false if you don't want seo metadata injection. For more information about how this works, check out the video SEO page.

NOTE: Only the Standard and Popover embeds are capable of injecting metadata right now. The Fallback iframe will not inject metadata, even if seo is set to true.

settingsControl

If set to true, the settings control will be available. This will allow viewers to control the quality and playback speed of the video.

See qualityControl and playbackRateControl if you want control of what is available in the settings control.

smallPlayButton

If set to true, the small play button control will be available.

NOTE: On mobile devices where we use native controls, this option has no effect.

stillUrl

Overrides the image that appears before the video plays. Expects an absolute URL to an image. For best results, the image should match the exact aspect ratio of the video.

time

Set the time at which the video should start. Expects an integer value in seconds or string values like "5m45s". This is equivalent to running video.time(t) immediately after initialization.

videoFoam

When set to true, the video will monitor the width of its parent element. When that width changes, the video will match that width and modify its height to maintain the correct aspect ratio.

Setting bounds for videoFoam

You can set maximum or minimum widths and heights that videoFoam will honor.

For example, when setting the videoFoam option, you can change this:

{ videoFoam: true }

to this:

{
  videoFoam: {
    minWidth: 400,
    maxWidth: 960
  }
}

or using height instead:

{
  videoFoam: {
    minHeight: 300,
    maxHeight: 450
  }
}

volume

Set the volume of the video. Expects an integer value between 0 and 1. This is equivalent to running video.volume(v) immediately after initialization.

To mute the video on load, set this option to 0.

volumeControl

When set to true, a volume control is available over the video.

NOTE: On mobile devices where we use native controls, this option has no effect.

wmode

When set to "transparent", the black background of videos will be removed. When flash is used, it also sets the "wmode" flash param.

Embed Plugins

The following Embed Plugins are available for Wistia videos:

Turnstile

The Turnstile plugin slides an extremely simple form over the video at a time of your choosing. The sizing of the top and bottom text is determined by the height of the video by default.

Turnstile also tries to avoid asking for the viewers email if it has already been collected. It does this by saving the email in local storage for the specific location.href where it was collected. You can turn off this functionality by setting alwaysShow to true.

Turnstile Plugin Example

wistia_html.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<script>
window._wq = window._wq || [];
_wq.push({
  id: "5bbw8l7kl5",
  options: {
    plugin: {
      "requireEmail-v1": {
        topText: "Please enter your email below.",
        bottomText: "We may use this email to contact you about the product, but we won't be too pushy.",
        time: 30,
        askName: true
      }
    }
  }
});
</script>
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_5bbw8l7kl5" style="width:640px;height:360px;">&nbsp;</div>

_

Turnstile Plugin Options

allowSkip

Determines whether to display a "Skip" button in the lower right for a gate at the beginning or middle. Defaults to false.

alwaysShow

Determines whether to display the Turnstile gate even if the email has already been collected. Defaults to false.

askName

Determines whether to require first and last name in addition to email. Defaults to false.

bottomText

The text displayed below the input field. Usually this is information about what you'll do with the email.

buttonBackground

The hex color of the button. Defaults to the player color.

errorColor

The hex color of the error text that can displayed. Yellow by default.

emailExampleText

The text that is displayed when the email input field is empty.

firstNameExampleText

The text that is displayed when the first name input field is empty. Only applicable when askName is true.

lastNameExampleText

The text that is displayed when the last name input field is empty. Only applicable when askName is true.

sectionIndex

Only applies to playlists. Used in conjunction with videoIndex option to determine which video to begin gating. Defaults to 0.

time

The point in the video when Turnstile displays. A value of "before" shows Turnstile before the video starts. "end" shows it at the end. You can also supply a time in seconds (e.g. 130) and it will appear when the viewer reaches that point in the video (or tries to skip past that point).

topText

The text displayed above the input field. Usually a request to enter the email.

videoIndex

Only applies to playlists. Used in conjunction with sectionIndex option to determine which video to begin gating. Defaults to 0.

Post-Roll CTA

The Post-Roll Call-to-Action plugin adds an interactive screen of your design, which slides into view after the video has finished playing.

Post-Roll CTA Plugin Example

wistia_html.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<script>
window._wq = window._wq || [];
_wq.push({
  id: "4d8229898d",
  options: {
    plugin: {
      "postRoll-v1": {
        text: "This clickable message\n will appear after your\n video ends!",
        link: "https://wistia.com"
      }
    }
  }
});
</script>
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_4d8229898d" style="width:640px;height:360px;">&nbsp;</div>

_

Scripts and CSS in Post-Rolls

<script>, <style>, and <link rel="stylesheet"> tags are allowed in the raw option, but have some special rules around them for security.

  1. When saved via the Customize API, <style> tags and style attributes will be sanitized to prevent XSS vectors.
  2. <script> and <link rel="stylesheet"> tags will not be executed when your embed is in a wistia.com domain. This includes the video that's visible in your account. However, if you embed the video on a different domain, the scripts will execute in order.
  3. Assuming you are on a non-wistia.com domain, <script>, <style>, and <link rel="stylesheet"> tags will be injected onto the page immediately after your HTML has been rendered to the page.

Post-Roll CTA Plugin Options

autoSize

When true, sets a font-size and line-height for the call to action based on the height of the video. Default is false.

backgroundOpacity

A decimal between 0 and 1 to set the overall opacity of the background. Default is 0.91.

image

The image src for the call to action.

link

The destination URL when you click the post-roll.

This param can be used with either text or image calls to action. If a raw param is given, it will be used instead of text/image/link.

Links use target="\_blank" to pop open a new window when you click. This is so that iframe embeds don't open a new link inside the iframe! If you're using a Standard embed and raw HTML, you can omit target="\_blank" safely.

on

Whether to show the post-roll. Default is true. Can be set to false to override Customize options.

raw

The raw HTML for the call to action.

rewatch

Whether to show "Rewatch" button in lower left. Defaults to true for text calls to action, false for image or HTML.

text

The text for the call to action.

time

The point in the video when the CTA displays. A value of "before" shows the CTA before the video starts. "end" shows it at the end. You can also supply a time in seconds (e.g. 130) and it will appear when the viewer reaches that point in the video (or tries to skip past that point).

Annotations

The Annotations plugin displays mid-playback links or plain text notes in the top right corner of the video.

Annotations Plugin Options

links

Array

An array of objects specifying the annotations to display at what times. The options for each annotation are specified below.

Annotation Options

time

int, required (but ignored if dynamic).

The time this annotation appears, in seconds.

duration

int, required (but ignored if dynamic).

The amount of time this annotation stays visible, in seconds.

text

string, required.

The plain text content of this annotation. HTML is not allowed.

url

string, optional.

The URL the annotation will link to. If its value is null, "", or undefined, the annotation text will be shown as plain text instead of as a link.

Annotations Plugin Example

Here's an example code. This code, when added to an embed, will configure an annotation link to display between 0:03 and 0:08 on the video. Note that this will override any existing annotations added in Customize.

annotations-params.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<script>
window._wq = window._wq || [];
_wq.push({
  id: "4d8229898d",
  options: {
    plugin: {
      "midrollLink-v1": {
        links: [
          {
            time: 3,
            duration: 5,
            text: "Click me!",
            url: "http://wistia.com"
          }
        ]
      }
    }
  }
});
</script>
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_4d8229898d" style="width:640px;height:360px;">&nbsp;</div>

If you'd rather preserve any existing annotations added via Customize and augment those annotations with your own, you can do so with .addLink() or a combination of .getLinks() and .setLinks().

annotations-custom.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<script>
window._wq = window._wq || [];
_wq.push({
  id: "4d8229898d",
  onHasData: function(video) {
    video.plugin('midrollLink-v1', function(annotation) {
      // add a single annotation like this
      annotation.addLink({
        time: 5,
        duration: 3,
        text: "I'm a dynamic annotation."
      });
      // or add a bunch like this
      annotation.setLinks(annotation.getLinks().concat([
        {
          time: 10,
          duration: 3,
          text: "I'm another dynamic annotation.",
          url: "https://wistia.com"
        }
      ]));
    });
  }
});
</script>
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_4d8229898d" style="width:640px;height:360px;">&nbsp;</div>

Dynamic Annotations

Your own script can take control of showing and hiding links. In this case, you can register a callback so that when the plugin loads, you can use its methods .showLink() and .hideLink() at will. The .showLink() method accepts an object with the same annotation options as above, but ignores time and duration.

To ensure your dynamic annotations do not conflict with any existing annotations set in the Customize panel, you must tell the Annotations plugin to ignore them with the {links: false} option.

annotations-manual.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<script>
window._wq = window._wq || [];
_wq.push({
  id: "4d8229898d",
  options: {
    plugin: {
      "midrollLink-v1": {
        links: false
      }
    }
  },
  onHasData: function(video) {
    var myCustomLink = {text: 'Click here!', url: 'https://wistia.com'};
    var isShowingLink = false;

    video.plugin('midrollLink-v1', function(annotation) {
      video.bind('timechange', function(timeInSeconds) {
        if (timeInSeconds > 10 && timeInSeconds < 20) {
          if (!isShowingLink) {
            annotation.showLink(myCustomLink);
            isShowingLink = true;
          }
        }
        else if (isShowingLink) {
          annotation.hideLink();
          isShowingLink = false;
        }
      });
    })
  }
});
</script>
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_4d8229898d" style="width:640px;height:360px;">&nbsp;</div>

Share

Add a Share control to your video player so viewers can share to various social media platforms.

Share Plugin Example

wistia_html.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<script>
window._wq = window._wq || [];
_wq.push({
  id: "5bbw8l7kl5",
  options: {
    plugin: {
      share: {
        channels: "facebook-twitter",
        tweetText: "Check out this awesome video called {video_name}",
        overrideUrl: "false"
      }
    }
  }
});
</script>
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_5bbw8l7kl5" style="width:640px;height:360px;">&nbsp;</div>

_

Share Options

channels

Use this to set the list of options you want to show up in the Share menu. The format is a dash-separated string. Here is an example with all of the available options:

"facebook-googlePlus-twitter-email-embed-download-linkedIn"

pageTitle

Determines the title to use when sharing. This title will be displayed wherever possible.

overrideUrl

A true value here will use the pageUrl value as the page to share. A false value will use the default Wistia media page.

pageUrl

If overrideUrl is true, this URL is used as the page which is shared.

downloadType

There are three choices for file types if you choose to allow viewers to download from the share menu: "sd_mp4", "hd_mp4", or "original".

tweetText

You can use this to compose the tweet text for Twitter shares. Wherever {video_name} is used, it will substitute in the name of the video (as defined on the Wistia media page).

The {page_title} option will substitute in the title of the page the video is embedded on.

Chapters

Add a control to your player to allow users to view chapters on your video. Chapters also adds clickable points on the play bar.

Chaptering Example

wistia_html.html
1
2
3
4
5
6
7
8
9
10
11
<script>
window._wq = window._wq || [];
_wq.push({
  id: "5bbw8l7kl5",
  options: {
    chaptersOn: "true", chapterList: [{title: "Chapter 1", time: "5.0"}, {title: "Chapter 2", time: "20.0"}]
  }
});
</script>
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_5bbw8l7kl5" style="width:640px;height:360px;">&nbsp;</div>

_

Chaptering Options

chaptersOn

This is a true or false value to turn chapters on or off.

chapterList

This is an array of hashes that specify your chapter titles and the times (in seconds) they should display.

Captions

This plugin displays closed captions for your video.

Captions Plugin Example

wistia_html.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<script>
window._wq = window._wq || [];
_wq.push({
  id: "qpxihhb76m",
  options: {
    plugin: {
      "captions-v1": {
        onByDefault: true,
        language: 'kor' // default to Korean captions
      }
    }
  }
});
</script>
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_qpxihhb76m" style="width:640px;height:360px;">&nbsp;</div>

Captions Plugin Options

onByDefault

Determines whether captions will display automatically for this video when it loads. If this is set to true, when the viewer starts playing the video, the captions will display automatically. If this is set to false, the viewer will need to click the CC button in the player to turn on captions.

The default for this option is false.

language

Use this to set the default caption language. This only takes effect if onByDefault is set to true.

This is a 3 character language code specified by ISO-639-2. So if you set language to kor and your video has Korean captions, the Korean captions will be displayed.

Without language specified, the player will default to the language of the viewer as set by their browser (we look at their HTTP_ACCEPT_LANGUAGE header).