WordPress and Wistia
WordPress is one of the most popular website builders out there, and we've got you covered on the tips and best practices for embedding Wistia medias on your site.
WordPress is an awesome platform for creating powerful websites. Here’s a guide to making Wistia and WordPress go together like PB&J. Or in some cases, PB&J and banana.
Like Wistia’s favorite treat (donuts 🍩), WordPress comes in many flavors. Because of this, the “how” of embedding medias will vary based on the type of WordPress environment you’re using. Are you using a custom theme? What about plugins? We’ll cover all of this below, but we start with a very important question: are you using Wordpress.org, or Wordpress.com?
- Wordpress.org is the fully customizable, self-hosted version of Wordpress. It comes with full support for themes and plugins, and requires paid hosting to use.
- Wordpress.com is a free, blog style version of Wordpress with limited themes and no plugin support. It does not come with a custom domain, so your site’s URL would be something like “yoursite.wordpress.com” (unless you upgraded to a paid version).
We’ve found that most Wistia & WP users are on Wordpress.org, the self-hosted version with lots of options. Does your website have a custom domain? Then it’s probably on Wordpress.org.
WordPress.org, the self-hosted and super customizable version of Wordpress, is one of the most popular content management systems (CMS) for a reason. It offers a lot of site-building functionality to users at many different levels of web development experience, from novice to expert. When it comes to embedding Wistia-hosted medias, there are two main options that we recommend:
When you add a Standard embed to the page, make sure you’re using the text tab within the classic Wordpress editor. If you’re on the newer Gutenberg editor, use the Custom HTML block.
To get an oEmbed URL for a video in your Wistia account, first choose the Inline, Standard embed and then select “Use oEmbed URL” under Options on the Embed & Share modal. Take a look-see:
That’ll give you an oEmbed URL, which you can add into the text tab of your page:
When you publish the page, the WP editor will convert the URL into an embedded media. It’s. That said, before the magic happens you’ll need to allowlist Wistia oEmbeds in one of two ways.
By far the simplest way to enable Wistia oEmbeds in WP.org is to install the Wistia WordPress plugin. The primary job of this plugin is to handle the step of allowlisting Wistia as an oEmbed provider for Wordpress.org sites.
Install the Wistia WordPress plugin here, and you’ll be all set to start adding oEmbeds like it’s your job. Which it probably is.
If you’d prefer not to add a new plugin, you can allowlist Wistia manually instead. Fortunately, adding Wistia as a trusted provider isn’t too difficult, thanks to WordPress, who have made this process fairly straightforward.
To start, you’ll want to use the
wp_oembed_add_provider() function, explained in WordPress’s own documentation. In conjunction with some steps from our oEmbed help page, here’s how this new provider rule will look:
<?php wp_oembed_add_provider( '/https?:\/\/(.+)?(wistia.com|wi.st)\/(medias|embed)\/.*/', 'http://fast.wistia.com/oembed', true); ?>
From there it’s mostly a copy & paste job. Once you’ve added that to the
functions.php file in your WordPress directory, you should be all set to use Wistia oEmbed URLs.
Time for some Real Talk™ — there are a ton of themes and plugins that exist for Wordpress. More are being developed each day, and many of them have options for using medias in new and creative ways. Unfortunately, not all of these tools are developed with inherent support for Wistia embeds.
We do our best to provide embedding options that are compatible with a variety of CMS platforms, but it’s nigh impossible to keep up with all the WP themes and plugins out there. Additionally, many video/audio-specific plugins are built with support for only one or two hosting providers (lookin' at you, Youtube).
If the embedding options recommended on this help page aren’t working in your WP theme or plugin, there is a chance that tool does not support Wistia embeds. Here are some general pointers:
- Try different embed types: Plugins can change the expected rules around embedding medias. If the Standard embed or the oEmbed link don’t work in a plugin, you might want to try our Fallback/iframe embed. While not typically recommended for WP.org sites, sometimes a plugin or theme may be built with iframe support.
- Custom HTML options: If you’re not having any luck with the video/audio-specific plugins, try using a Custom HTML or Code block if available. Sometimes we just need to find the right widget for accepting custom code.
- Go back to the Classic editor: Often it’s the Visual Composer/Visual Editor of a theme that either won’t accept Wistia embed codes, or may modify and break them by mistake. If you’re having trouble embedding Wistia medias in a theme’s Visual Composer, try switching back to the classic WP editor to embed the media.
- Check the documentation: Sometimes we can get our answers from the online docs for that theme or plugin. For example, if you’re using the Divi builder, try Googling “embed video Divi.” Look up the support docs for tips on embedding media in the theme, and check if Wistia is mentioned as a hosting provider. If not, there’s a good chance they don’t support our embeds.
- We’re here to help: When all else fails, email firstname.lastname@example.org or use our contact form. We’ll help to determine if Wistia embeds are supported by your theme and how best to implement them.
Lastly, if there is a theme or plugin you’re using but it doesn’t appear to support Wistia embeds, you might want to contact the developers who built it. As a user of their product, let them know that you’d like more support for Wistia-hosted medias. At the very least, they’ll know there is some demand for this functionality. At best, they might add support for Wistia!
If you’re using WordPress.com, we’ve got good news: adding videos to your posts is super easy, since Wistia is a default oEmbed provider for WP.com sites. In fact, oEmbed is the primary option for embedding in WordPress.com, specifically.
Just follow the same instructions above to get an oEmbed URL and paste it right into your WP.com post via the Text tab. You may need to enter preview mode to render the link into a video. Publish the page and you’re all set!
Wistia doesn’t currently offer an “oEmbed” option within the Popover Embed tab. But that doesn’t mean it isn’t possible. In fact, creating a popover oEmbed is as easy as adding the
popover=true parameter to your oEmbed link.
So for this Standard oEmbed:
We’d add the
popover=true parameter onto the string of existing options:
http://fantastic.wistia.com/medias/60cf0ufhoo?embedType=async&popover=true&videoWidth=640Now we have an oEmbed URL that will result in a popover instead of an inline embed.
If you want to specify the size of the popover thumbnail (when playing, a popover video will always be responsive in its lightbox), change the videoWidth string.
First, make sure you’ve followed the steps above for allowlisting Wistia as an oEmbed provider.
Next, when inserting an oEmbed URL in WP.org, make sure you are in the text/HTML editing tab. We recommend leaving an open line above and below the URL. These open lines will help ensure the URL is parsed properly as an oEmbed, instead of just a link or text.
If you switch from text/HTML to visual mode before publishing, the WP editor may add formatting tags around your oEmbed URL, which can cause it to break. If you notice this happening, we suggest embedding the media in the text tab and then publishing the page directly, without switching back to visual mode first.
We recommend the Standard embed for a specific reason — the WP editor will commonly modify iframe-based embed codes to “sandbox” them. This is a security measure; iframes reference an external URL and display it as a page-within-a-page, and sandboxing iframes helps to safeguard against malicious code being inserted there.
Think of an iframe as a portal to another webpage, and a Wistia iframe is a portal to a page with a media. Unfortunately, when Wistia embeds are sandboxed it prevents our scripts from executing within the WordPress page, therefore the player will not work as expected.
If you want to center your media inside a div or column on your website, and you are using an oEmbed URL to embed your media, please use a second div with the
style display: inline-block;, as seen here:
<div style="text-align: center;"> <div style="display: inline-block;"> http://fantastic.wistia.com/medias/60cf0ufhoo?embedType=async&videoWidth=640 </div> </div>
If you have larger resolution videos and they are appearing smaller or squished, access the WordPress admin control panel (Settings → Media → Maximum Video Embed Size) and set the max to the largest size of your video (’no limit' setting doesn’t work, it must be actual size). Some WordPress themes will also set a maximum width for content embedded with oEmbed. If you want to change that, check out How to Set oEmbed Max Width in WordPress 3.5 with $content_width.