Embed Options and Plugin
Learn more about the embed options and plugins available for your embedded videos.
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.
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.
<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;"> </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:
_wq before the video is embedded.
<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;"> </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 ?.
<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.
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.
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.
muted
If set to true, the video will start in a muted state.
If you would like your video to play silently and not show the Click For Sound button, then you can set this option.
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).
playlistLinks
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.
silentAutoPlay
This option allows videos to autoplay in a muted state in contexts where normal autoplay is blocked or not supported (e.g. iOS, Safari 11+, Chrome 66+). Possible values are:
true: The video will default to autoplaying silently.allow: The video will default to normal autoplay, with silent autoplay as a fallback if needed.false: The video will not autoplay silently.
Note that, technically, a video is considered to be "autoplaying" if the play() command is not issued within a user-generated event (like a click) or within the "end" event handler (e.g. for the next video in a playlist).
If you need to see when the video enters and exits "silent playback mode," refer to the docs on the "silentplaybackmodechange" event.
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 - Add an email gate to your video. Configure it to pass emails to your Email Marketing platform.
- Post-Roll CTA - Suggest an action after viewing.
- Annotations - Add links or notes to your video during playback.
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
<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;"> </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
<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;"> </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.
- When saved via the Customize API,
<style>tags andstyleattributes will be sanitized to prevent XSS vectors. <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.- 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.
<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;"> </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().
<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;"> </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.
<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;"> </div>
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
<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;"> </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
<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;"> </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).