Guides
Wistia Learning CenterWistia
Start typing to search…

Aurora Plugin API and Plugin Options

The Plugin API provides a light framework for script loading and initialization on a video, as well as some convenient properties for positioning DOM elements.

It works with all embed types, including iframes, which means you can even use plugins in systems that don’t allow script tags.

📝

Note

The Wistia APIs were specifically built for videos in projects and folders. We do not formally support using our APIs for audio files in projects, or audio or video episodes in Channels at this time. For the most reliable experience, we recommend continuing to use these for videos in projects.

The Components of a Wistia Plugin

A Wistia plugin has two basic pieces:

First, the video's embed code needs to define the plugin's scripts and options. Note: the plugin definition must occur before the Wistia Player Embed.

Second, the plugin's internal script needs to initialize using the Wistia.plugin function.

Defining plugins in an embed code

For learning purposes, we'll demonstrate with the Standard inline embed code type. We've removed the HTML portion and left only the script, since that's the relevant part here.

First, here's an embed code that references one of Wistia's internal plugins, requireEmail-v1.

<script>
  window.wistiaOptions = {
    _all: { // `_all` impacts all videos, you can also use a specific media-id, eg. `'abc123'`
      plugin: {
        'requireEmail-v1': {
          topText: "Please enter your email\n to view this video.",
					time: 0,
        }
      }
    }
  };
</script>

<!-- <wistia-player/> embed code -->

Third Party plugins can use the exact same syntax, but they must add a src attribute.

<script>
  window.wistiaOptions = {
    _all: { // `_all` impacts all videos, you can also use a specific media-id, eg. `'abc123'`
      plugin: {
        "my-plugin-name": {
          customOption: true,
          src: "http://myscriptdomain.com/my-plugin-name.js"
        }
      }
    }
  };
</script>

<!-- <wistia-player/> embed code -->

The script file defined in the src property is executed asynchronously. This is where the second part of Wistia plugins comes in...

Initialize Your Plugin

Wistia.plugin("my-plugin-name", function(video, options) {
  video.bind("play", function() {
    if (options.customOption) {
      console.log("Do some cool stuff.");
    } else {
      console.log("Do something completely different.");
    }
  });
});

That's it! By calling Wistia.plugin("my-plugin-name", myFunction), you're doing a few things:

  1. It caches the function so, if multiple videos on the page use the same script, we don't need to download it twice.
  2. It places the function in the Wistia.plugin namespace, callable like Wistia.plugin["my-plugin-name"](video, options).
  3. It immediately executes the function with the originating video handle and plugin options as arguments.

For compatibility purposes, The video argument is a handle to legacy the Player API, which means you can now do interact with the video as the Legacy Player API would.

Using plugins with an iframe embed

Wistia iframe embeds take the exact same JSON parameters as a Standard embed, but they must be properly URL-encoded using a bracket syntax.

For example, here's the plugin parameters for the Standard embed above, but translated to be appended on an iframe src attribute.

plugin%5Bmy-plugin-name%5D%5BcustomOption%5D=true&plugin%5Bmy-plugin-name%5D%5Bsrc%5D=http%3A%2F%2Fmyscriptdomain.com%2Fmy-plugin-name.js

Plugin Options

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.
  • GA4 - Specify a Web Data Stream on your page to override account-level settings.

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 viewer's 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.

📝

Note

The Turnstile plugin requires you to supply both topText and bottomText options. If you want to leave either of those fields blank, just include empty quotes such as bottomText: "",. If you exclude either of these options, the form will not appear on the video.

Turnstile Plugin Example

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
       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>

<wistia-player media-id="abc123"></wistia-player>

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.

emailDomainVerification

Restrict the Turnstile to exclude certain email domains. You can use the invalidDomains parameter or the validDomains parameter.

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
       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,
        emailExampleText: "Business Email",
        invalidDomains: "competitor.com,heckno.com",
        validDomains: "coolsite.com,heckyeah.com",
        }
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

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. When a project is converted to a playlist, use sectionIndex to select which project section to gate with a Turnstile. This must be used in conjunction with videoIndex to identify which video in the section has the Turnstile applied. Defaults to 0 (the first project section).

NOTE: Playlists are a deprecated feature, but this embed option will still work when applied to already existing playlists in the wild.

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. When a project is converted to a playlist, use videoIndex to select which video in the playlist to gate with the Turnstile. Can be used in conjunction with sectionIndex to select which video within a project section is gated. Defaults to 0 (the first video in the playlist or playlist section).

NOTE: Playlists are a deprecated feature, but this embed option will still work when applied to already existing playlists in the wild.

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 src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
       plugin: {
        "postRoll-v1": {
          text: "This clickable message\n will appear after your\n video ends!",
          link: "https://wistia.com"
        }
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

Post-Roll CTA Plugin Options

autoSize

When true, sets a font-size and line-height for the CTA that scales based on the height of the video. Default is false, in which case the text of the CTA will remain at the same size regardless of the video's height.

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 CTA.

link

The destination URL when you click the post-roll.

This parameter can be used with either text or image CTAs. If a raw parameter is given, it will be used instead of text,image, and link.

CTAs will open the link in a new tab by default. However, when you're using a raw parameter with a Fallback iframe embed, be sure to include target="\_blank" as an attribute of any anchor <a> elements. This will ensure that the embed opens the link in a new tab and not within the iframe.

on

Whether to show the post-roll. Default is true. Can be set to false to override CTA options set via the Customize panel in the Wistia app.

raw

The raw HTML for the CTA. Keep in mind that adding HTML here will still require the HTML to be formated in JSON and as a string. If we wanted to use the Post-Roll CTA example from earlier, and combine it with our Multiple Choice CTA example, then the raw format will look like this:

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
       plugin: {
        "postRoll-v1": {
          raw: "<a href=\"#wistia_30q7n48g4f\">Next Up: Make French Toast</a><br/><p>Or you could watch...</p><a href=\"#wistia_342jss6yh5\">Our Wistia Team Intro!</a><br/>"
        },
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

rewatch

Use this to show a "Rewatch" button in the lower left corner of the video. Defaults to true for text CTAs and false for image or HTML CTAs.

text

The text for the CTA.

time

The point in the video when the CTA displays. A value of before shows the CTA before the video starts, and 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).

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.

Annotations

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

Annotations Plugin Options

links

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

Annotation Options

time

The time at which this annotation appears in the video. Expects a value in seconds. (Required, but ignored if dynamic)

duration

The amount of time this annotation stays visible, in seconds. (Required, but ignored if dynamic)

text

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

url

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. (Optional)

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 set in Customize panel within the Wistia app.

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
       plugin: {
        "midrollLink-v1": {
          links: [
            {
              time: 3,
              duration: 5,
              text: "Click me!",
              url: "http://wistia.com"
            }
          ]
        },
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

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 src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<wistia-player id="my-video" media-id="abc123"></wistia-player>

<script>
  customElements.whenDefined('wistia-player').then(() => {
    const video = document.getElementById('my-video');

    video.getPlugin('midrollLink-v1').then((plugin) => {
      plugin.addLink({
        time: 5,
        duration: 3,
        text: "I'm a dynamic annotation.",
      });
      // or add a bunch like this
      plugin.setLinks(plugin.getLinks().concat([
          {
            time: 10,
            duration: 3,
            text: "I'm another dynamic annotation.",
            url: 'https://wistia.com',
          },
        ]),
      );
    });
  });

</script>

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 within the Wistia app, you must tell the Annotations plugin to ignore them with the {links: false} option. If you don't, both sets of annotations will be visible.

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<wistia-player id="my-video" media-id="abc123"></wistia-player>

<script>
  window.wistiaOptions = {
    _all: { // or a media-id to target a specific media, e.g. `'abc123'`
      plugin: {
             "midrollLink-v1": {
        links: false
      },
    },
  };

  customElements.whenDefined('wistia-player').then(() => {
    const video = document.getElementById('my-video');

    video.getPlugin('midrollLink-v1').then((plugin) => {
      const myCustomLink = { text: 'Click here!', url: 'https://wistia.com' };
      let isShowingLink = false;

      video.addEventListener('second-change', function (event) {
        const second = event.detail.second;
        if (second > 10 && second < 20) {
          if (!isShowingLink) {
            plugin.showLink(myCustomLink);
            isShowingLink = true;
          }
        } else if (isShowingLink) {
          plugin.hideLink();
          isShowingLink = false;
        }
      });
    });
  });

Looping Video Thumbnail

The videoThumbnail plugin allows you to set a looping video thumbnail for your embedded media.

Video Thumbnail Plugin Example

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
      plugin: {
        videoThumbnail: {
          on: true,
          hashedId: "xz77w5ts33",
          trimStart: 13,
          trimEnd: 18,
          async: false,
        }
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

Looping Video Thumbnail Options

trimStart

Use this to identify the start of the section of your video you’d like to use as a looping thumbnail. Expects a value in seconds.

trimEnd

Use this to set the end of the section of your video you’d like to use for your animated thumbnail. Expects a value in seconds.

Share

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

Share Plugin Example

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
      plugin: {
        share: {
          channels: "facebook-twitter",
          tweetText: "Check out this awesome video called {video_name}!",
          overrideUrl: "false"
        }
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

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. The default value is false, which will use the page where the video is embedded.

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. Only one option is possible.

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

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
      plugin: {
        chapters: {
          on: true,
          chapterList: [
            { title: "Chapter 1", time: "5.0" },
            { title: "Chapter 2", time: "20.0" }
          ]
        }
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

Chaptering Options

on

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.

📝

Note

In order to use the Captions plugin, you'll first need to upload a captions file to your video. You can either do this from within the Wistia app or by using our Captions API.

Captions Plugin Example

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
      plugin: {
        "captions": {
          onByDefault: true,
          language: 'kor' // default to Korean captions
        },
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

Captions Plugin Options

onByDefault

This determines whether captions will display automatically for this video when it loads. If this is set to true, the captions will display automatically when the viewer starts playing the video. 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).

plugin[captions][subtitlesScale]

You can use a multiplier to scale the size of your captions if you'd like them to be bigger or smaller than our default. For example, set the option to 1.2 (plugin[captions][subtitlesScale]=1.2) to make your captions 1.2x the size of the original captions. NOTE: The scaling value is a multiplier on top of our existing scaling, so the font still gets bigger and smaller with the video, but its final size is multiplied by that option.

transcript

This option can be used to disable Interactive Captions. Default value is true, and setting the option to false will turn off Interactive Captions.

Using Multiple Plugins

If you'd like to use more than one plugin, here is an example of what that code would look like with the Post-Roll CTA and Annotations Plugins.

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    'abc123': {
      plugin: {
        "postRoll-v1": {
          text: "This clickable message\n will appear after your\n video ends!",
          link: "https://wistia.com"
        },
        "midrollLink-v1": {
          links: [
            {
              time: 3,
              duration: 5,
              text: "Click me!",
              url: "http://wistia.com"
            }
          ]
        }
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

Web Data Stream Plugin for GA4

When connecting the GA4 integration in Wistia, you can select the Use Page GA4 Configuration option to default to a measurement ID configured on your webpage.

To send the data for all videos on one Web Data Stream despite having multiple scripts on the page, use the script below to specify a measurement ID.

GA4 media plugin example

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<script>
  window.wistiaOptions = {
    '_all': {
      plugin: {
        "googleAnalytics4": {
          measurementId: "G-KCYT6JQF90"
        }
      },
    },
  };
</script>

<wistia-player media-id="abc123"></wistia-player>

If the gtag does not exist on the page, we’ll load it and configure it to use the measurement ID that was chosen when setting up the integration.

📝

Note

The id field in the plugin has a value of _all which targets all embeds on a page. This value can also be replaced with a hashed ID to target a specific media.

GA4 Channel plugin example


<script>
  window.wistiaOptions = {
    '_all': {
      plugin: {
        "googleAnalytics4": {
          measurementId: "G-KCYT6JQF90"
        }
      },
    },
  };
</script>

Updated about 20 hours ago