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.

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, form. This customizes a form that has already been added to the video in Customize.

<script>
  window.wistiaOptions = {
    _all: { // `_all` impacts all videos, you can also use a specific media-id, eg. `'abc123'`
      plugin: {
        form: {
          title: "Please enter your email to view this video.",
          time: "before",
        }
      }
    }
  };
</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 documented for the Aurora player:

• Wistia Forms - Add an email gate to your video. Configure it to pass emails to your Email Marketing platform.

Wistia Forms

The Wistia Forms plugin displays a Wistia Form over the video at a time of your choosing. Forms, including their fields and default text, are built and added to a video from the Customize panel in Wistia. The form plugin does not create a form on its own. It customizes the form already added to the video. Use the options below to control when and how the form appears and to override its text on a specific embed.

Wistia Forms 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: {
        form: {
          time: 30,
          skippable: true,
          title: "Please enter your email below.",
          formLowerText: "We may use this email to contact you about the product, but we won't be too pushy.",
          formButtonText: "Keep watching"
        }
      },
    },
  };
</script>

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

Wistia Forms Plugin Options

backgroundColor

The background color behind the form, as a hex value such as "#1e1e1e". Defaults to "#000000".

displayMode

Determines how the form is presented. Defaults to "pause".

• "pause" pauses the video and shows the form at the point set by time.
• "overlay" shows the form over the video while the viewer hovers over or touches the player, without pausing playback. time and skippable have no effect in this mode.

formButtonText

The label on the form's submit button. If omitted, the button text saved on the form is used.

formLowerText

The text displayed below the form. Usually this is information about what you'll do with the email. If omitted, the lower text saved on the form is used.

on

Determines whether the plugin is loaded. Set to false to turn the form off for a specific embed. Defaults to true.

showLogo

Determines whether to display the video's player logo at the top of the form. The player logo is set in Customize under Appearance & brand. Has no effect if the video has no player logo. Defaults to false.

skippable

Determines whether to display a "Skip" button so viewers can continue without submitting the form. When time is "end", a "Rewatch" button is shown instead. Only applies when displayMode is "pause". Defaults to false.

time

The point in the video when the form displays. A value of "before" shows the form 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). Only applies when displayMode is "pause". Defaults to "before".

title

The heading displayed above the form. Usually a request to enter the email. If omitted, the title saved on the form is used.