A Quick Intro to the Big Bad World of Embedding

What is the purpose of an embed?

It’s a way of displaying outside content (a Wistia Video) on a page.

The embed allows a customer to put their snazzy, Wistia hosted video on their site and use all of the features we advertise for it.

Types of Embed Codes

There are a bunch of ways a customer can embed on their site. Most commonly it’s a Standard or Iframe Embed. Here are what they look like:

Standard Embed

<script src="https://fast.wistia.com/embed/medias/i3nkzupyon.jsonp" async></script><script src="https://fast.wistia.com/assets/external/E-v1.js" async></script><div class="wistia_embed wistia_async_i3nkzupyon" style="height:360px;width:640px">&nbsp;</div>

Iframe Embed (Fallback Embed)

<iframe src="https://fast.wistia.net/embed/iframe/i3nkzupyon" title="Wistia video player" allowtransparency="true" frameborder="0" scrolling="no" class="wistia_embed" name="wistia_embed" allowfullscreen mozallowfullscreen webkitallowfullscreen oallowfullscreen msallowfullscreen width="640" height="360"></iframe>
<script src="https://fast.wistia.net/assets/external/E-v1.js" async></script>

Deconstructing the Standard Embed

We’ll go through piece by piece. Each part of the embed has a different purpose and they’re easier to understand when you look at each separately.

JSONP Speeddemon Script

<script src="https://fast.wistia.com/embed/medias/i3nkzupyon.jsonp" async></script>

This script helps the embed load faster. It’s not necessary for the embed, if it’s removed from the embed code, the embedding will still happen. For an over simplification of this very useful script, it preloads metadata information that make it possible to embed the video faster.

E-v1

<script src="https://fast.wistia.com/assets/external/E-v1.js" async></script>

E-v1 is where the magic happens. To elaborate, E-v1 is the primary script that we (Wistia) use for embedding. That means there’s a lot to unpack here, but we’re not going to do it all. There’s always more to learn about E-v1, but we’ll cover some introductory parts here.

If E-v1 is not present, the standard embed will not embed. E-v1 will transform the relatively small embed into the much bigger, faster, cooler, stronger, faster, smarter player. E-v1 does the heavy lifting to make things happen.

Unlike the Standard Embed, E-v1 does not have to be present with the iframe. It is exceptionally advisable, though. Iframes are like miniature webpages contained on the greater page. The Wistia iframe contains E-v1 inside it, which allows it to still embed properly. It’s essentionally a iframe with a little standard embed in that iframe.

It’s advisable to have E-v1 present outside of the iframe because that allows the embed to interact with the rest of the page. E-v1 can basically send the relevant information across teh iframe. If it’s not there, some Wistia features will not work.

E-v1 makes all the calculations on the page. It contains Judge Judy that will determine lots and lots of different factors to optimize the video for the embed.

It makes it possible to use MAP integrations and many of the other Wistia features. This is particularly relevant for iframe embeds. If E-v1 is not present outside the iframe, it will not be able to get the correct information/make the relevant requests for those features.

It loads asynchronously. The key here is that it won’t get in the way of other elements loading on the page.

The Actual Embed Div

<div class="wistia_embed wistia_async_i3nkzupyon" style="height:360px;width:640px">&nbsp;</div>

The key part of this div that we care about is the class section. E-v1 looks at those classes and constructs the embed based on what it sees there. We’re going to disect those classes below:

The wistia_embed class lets E-v1 know that this <div> element is a Wistia embed. It sounds simple, but it’s important, especially for customers creating custom embeds.

The wistia_async_i3nkzupyon lets E-v1 identify the embed. You can see that it ends with the video’s hashed_id. That way it will put the correct video in the unpacked embed. You could swap that hashed_id out if you wanted a different embed wherever you placed that embed code.

Embed Options! You can included embed options as classes for the div and they will change certain aspects of the embed. These are things like customizations that a customer may want to be different than normal for this particular embed. You can read a lot more about them here: https://wistia.com/doc/embed-options. It’s also possible to add embed options for popover, this is how you could specify a text popover or a thumbnail popover for instance.

Let’s Talk Iframes

A Wild Iframe Appeared…

What is an Iframe?

Think of an iframe as essentially a window to another webpage. Here’s the code above:

<iframe src="https://aardvarkgarden.wistia.land/aardvarkgarden" style="height:360px;width:640px"></iframe>

That bit of code loads the home page of the Aardvark Garden on this page. If you’d like to read some more about iframes, check this out: https://www.w3schools.com/tags/tag_iframe.asp. A Wistia iframe embed is doing the same thing, it’s just loading a specific video. Here’s that code again:

<iframe src="https://fast.wistia.net/embed/iframe/i3nkzupyon" title="Wistia video player" allowtransparency="true" frameborder="0" scrolling="no" class="wistia_embed" name="wistia_embed" allowfullscreen mozallowfullscreen webkitallowfullscreen oallowfullscreen msallowfullscreen width="640" height="360"></iframe>
<script src="https://fast.wistia.net/assets/external/E-v1.js" async></script>

There are a lot of attributes we apply to it, but at it’s base, it’s an iframe pointing at https://fast.wistia.net/embed/iframe/i3nkzupyon.

Crazy Iframe Time

For some fun, there’s a second iframe below this. It points at the Embed Tester 3000. Why don’t you try embedding a video in there? If you’re feeling bold, you could embed an iframe within iframe (do it! be that rebel!).

But wait, More Embed Codes

Responsive Embed Codes

Standard:
<script src="https://fast.wistia.com/embed/medias/i3nkzupyon.jsonp" async></script><script src="https://fast.wistia.com/assets/external/E-v1.js" async></script><div class="wistia_responsive_padding" style="padding:56.25% 0 0 0;position:relative;"><div class="wistia_responsive_wrapper" style="height:100%;left:0;position:absolute;top:0;width:100%;"><div class="wistia_embed wistia_async_i3nkzupyon videoFoam=true" style="height:100%;width:100%">&nbsp;</div></div></div>

Iframe:
<div class="wistia_responsive_padding" style="padding:56.25% 0 0 0;position:relative;"><div class="wistia_responsive_wrapper" style="height:100%;left:0;position:absolute;top:0;width:100%;"><iframe src="https://fast.wistia.net/embed/iframe/i3nkzupyon?videoFoam=true" title="Wistia video player" allowtransparency="true" frameborder="0" scrolling="no" class="wistia_embed" name="wistia_embed" allowfullscreen mozallowfullscreen webkitallowfullscreen oallowfullscreen msallowfullscreen width="100%" height="100%"></iframe></div></div>
<script src="https://fast.wistia.net/assets/external/E-v1.js" async></script>

Popover Embed Codes

Fixed Thumbnail:
<script src="https://fast.wistia.com/embed/medias/i3nkzupyon.jsonp" async></script><script src="https://fast.wistia.com/assets/external/E-v1.js" async></script><span class="wistia_embed wistia_async_i3nkzupyon popover=true popoverAnimateThumbnail=true" style="display:inline-block;height:253px;width:450px">&nbsp;</span>

Responsive Thumbnail:
<script src="https://fast.wistia.com/embed/medias/i3nkzupyon.jsonp" async></script><script src="https://fast.wistia.com/assets/external/E-v1.js" async></script><div class="wistia_responsive_padding" style="padding:56.25% 0 0 0;position:relative;"><div class="wistia_responsive_wrapper" style="height:100%;left:0;position:absolute;top:0;width:100%;"><span class="wistia_embed wistia_async_i3nkzupyon popover=true popoverAnimateThumbnail=true videoFoam=true" style="display:inline-block;height:100%;width:100%">&nbsp;</span></div></div>

Text:
<script src="https://fast.wistia.com/embed/medias/i3nkzupyon.jsonp" async></script><script src="https://fast.wistia.com/assets/external/E-v1.js" async></script><span class="wistia_embed wistia_async_i3nkzupyon popover=true popoverContent=link" style="display:inline"><a href="#">Text Popovers!</a></span>

Other Ways to Embed a Video

This section is really for oEmbeds. There’s a lot more technical information on how oEmbeds work in our documentation, but, for embedding basics, you can think of them as a different/special way that some people can embed. The most commmon place to see this is Wordpress (both .com and .org). If there is oEmbed suppport, someone can add a URL with embed options on it and it will be processed and turned into an embed.

Standard:
https://aardvark-garden.wistia.com/medias/i3nkzupyon?embedType=async&videoWidth=640

Iframe:
https://aardvark-garden.wistia.com/medias/i3nkzupyon?embedType=iframe&videoWidth=640

Troubleshooting Steps

Wait wait! I’ve learned all sorts of awesome new things about embeds and embedding, but how do I explore these things in the wild?

Fear not, helpful inquisitor, there are some useful tools that you can add to your video adventuring belt. We’re also including some steps below that are helpful for charging headlong into the brave new world of embedding.

Tools

  • Page Source - cmd + opt + u - This useful tool will show you the source html for a page. This is pretty useful for checking what the raw embed looks like before it’s unpacked by E-v1. When you’re looking at the source, try using your friend cmd + f to search for things like “wistia_embed” to find the embeds on the page and see if they’re normal. You can also search for E-v1 to make sure it’s present. There are some limitations though. Sometimes customers will use various scripts to load things onto their page and those won’t show up in the page source. Good thing there’s another tool.
  • Inspector - cmd + opt + i - The inspector allows you to the rendered page source. It’s similar to the page source, except all the scripts have run (including E-v1). Try searching (cmd + f) for “wistia_embed”. The embed will look a lot different than in the regular page source. This is particularly useful for seeing things that might have changed unexpectedly. You can also make sure that everything thatneeds to be there is there.
  • JavaScript Console - cmd + opt + j - This is a more advanced tool in your tool belt, but it’s useful to know about. This mostly is useful in conjunction with the Player API. A simple test you can run with it is to type w = Wistia.api() and the press enter. Avoiding going into too much detail, that will check whether E-v1 is present. If it returns undefined, something’s up with E-v1. If it returns, n with a bunch of information after it, the problem is likely elsewhere.
  • The Embed Doctor - https://your-wistia-account-key.wistia.com/embed_doctor - Use this to get a stripped down version of their page. The key is that it will generate a page that you can that view the page source of and create a better copy (everything won’t load properly normally). This allows you to create a page that’s a copy of theirs and easy to experiment with.
  • Local Hosting - Open your computer’s terminal. Open your local development folder by typing something like cd dev. Then open it up in your text editor so you can edit that text. Finally, enter python -m SimpleHTTPServer in your terminal window to spin up a localhost. You can now access those pages as if they were served on the internets by going to localhost:8000/whatever-the-file-name-is.html.
  • Glitch - For those who think that localhosting is too slow and you need things testable everywhere faster. There website is explains more, but it allows you to test out pages very quickly. Want to know more? Go ~poke~ politely ask Dave Cole, he loves it.

Want to test your cool new skills using Page Source and the Inspector. Try opening them up on this page and searchig for inspector-tester. It’ll take you right here. You can also search for things like wistia_embed. Go wild, inspect away!

What do I do now?

  • Does the embed look normal? Is it custom or does it match the embeds we generate for people?
  • Is E-v1 on the page? It should be…
  • Have they tried using a different embed? Iframes are more resilient and sometimes work when Standard Embeds don’t.
  • Are there outside influences causing problems? Things like CSS and JS can influence how our embeds look, be on the lookout.

    More advanced what do I do now?

  • Does the embed work alone in something like the embed tester 3000 or a locally hosted page?
  • Have you used the embed doctor to create a copy of their page to test it out? You can try deleting scripts or style sheets to see if you can narrow down the issue.

Useful Vocabulary

  • CMS
  • CDN
  • <div>
  • CSS
  • JavaScript
  • Class
  • Span
  • MAP
  • Merge Tag
  • Embed Options
  • oEmbed
  • Page Elements
  • SEO

Practice Problems

Problem One

I’m trying to embed my video, but all I see is a bunch of computer speak on my page. I just want my video to appear, can you tell me what’s wrong? Since I’m totally real and not just the ever tricky author of this page, I’ve included my embed code below.


<script src="https://fast.wistia.com/embed/medias/i3nkzupyon.jsonp" async></script>
<div class="wistia_responsive_padding" style="padding:56.25% 0 0 0;position:relative;"><div class="wistia_responsive_wrapper" style="height:100%;left:0;position:absolute;top:0;width:100%;"><div class="wistia_embed wistia_async_i3nkzupyon videoFoam=true" style="height:100%;width:100%">&nbsp;</div></div></div>

Problem Two

BLAAAAACCCCKKKKK BAAAAARRRRSSSS. When I uploaded my video it didn’t have black bars, now it does. Could you fix it asap? It’s very important. I’m a completely different person than problem one, but I’ve also embedded an example below here. I also included my perfect embed code:

<script src="https://fast.wistia.com/embed/medias/i3nkzupyon.jsonp" async></script><script src="https://fast.wistia.com/assets/external/E-v1.js" async></script><div class="wistia_embed wistia_async_i3nkzupyon" style="height:360px;width:100%">&nbsp;</div>
 

Problem Five

It would be really awesome if you could set up a popover embed so that it’s just some text like a button. I really don’t like what the thumbnail does for my image. It doesn’t work for me. Is there anything you can do to help?

Problem Three

I’ve created a wonderful garden full of embeds, but none of them look good at all. My beautiful garden is ruined. Could you take a look at it? Here’s a link: https://wistia.github.io/aardvarkgarden/csstroubleshooting/. But wait! It’s dangerous to go alone! Take this.

The mystical developer tools of Chromaticus. You can activate them by pressing cmd+opt+i. It will form a magicical inspector to look past the ethereal void that is.......the internet.