Wistia Learning Center
Guides
Login

Channel Embeds

Learn how to set Channel embed options and use the Channel API.

Suggest Edits

What is a Channel Embed?

At a high level, a Channel Embed is a snippet of code that lets you put a Wistia Channel on your website.

A Channel Embed displays a collection of episodes (audio or video) in a gallery-style format, and can be split into Sections for better organization. In wide layouts, each Section displays a horizontal row of its episodes. In narrow layouts, each Section displays vertically.

The main view of a Channel--when an episode is not showing--includes a name, description, "Play" button, and a "hero" image or video in the background.

Clicking on a thumbnail will load that episode in the "hero" area. When an episode ends, the next episode in the Channel will automatically start. As it approaches the end, an "Up Next" preview will appear in the lower right. For a full breakdown on Channels, head on over here.

Channel Embed Types

There are a few different settings that impact how your channel loads and displays.

Inline

Use an Inline Channel when you want your channel to show within the flow of your website.

Responsive Inline

A Responsive Inline Channel will horizontally fill the width of its parent element and grow vertically based on the content of the channel.

This is the preferred inline mode.

Fixed Size Inline

A Fixed Size Inline Channel will not grow vertically and has a fixed width. This will make it so that the channel scrolls independently of your website.

Popover

Use a Popover Channel when you want the viewer to click a "card" which launches your channel so that it covers the full window.

Fixed Size Popover

A Fixed Size Popover Channel has a card with a specific width and height that do not change. These are just CSS values; you may change the width and height to work with the CSS of your site.

Responsive Popover

A Responsive Popover Channel has a card that will match its width to its immediate parent element, and modify its height to maintain the aspect ratio defined by the Fixed Size values in the Channel Share tab.

If you care about your popover card maintaining a specific aspect ratio, use this type.

Structure of a Channel Embed Code

A channel embed code is structured similarly to a video's standard embed code. In its most basic form, it looks like this:

<script src="https://fast.wistia.net/assets/external/channel.js" async></script>
<div class="wistia_channel wistia_async_65su5wva44 mode=inline" style="position:relative;"></div>

Let's break that down.

The first line is our script, channel.js, which contains the code needed for the initial render of your channel.

The second line is called the "container." It is the DOM element where we will initialize the channel. The "wistia_channel" class identifies this DOM element as a channel. The "wistia_async_65su5wva44" class says "target the project with ID 65su5wva44 for our channel."

Like video embeds, the embedOptionName=value syntax is supported in the class attribute. For the example above, mode=inline is set, which means we will render the channel content directly into its container.

The different types of channels all keep this basic form, modifying the embed options, style attribute, or adding responsive wrapper elements.

Setting complex options

Sometimes embed options can't be passed as simple values. Channels support a syntax similar to video embeds to pass complex options.

window._wcq = window._wcq || [];
window._wcq.push({
  id: "a-string-that-matches-your-channel",
  options: {
    aFunctionForExample: function () {
      doAThing();
    },
  }
});

Routing

When you interact with a Channel Embed, it will change routing information in the URL bar. This makes it so that you can send links to specific videos. It also lets us inject SEO metadata for each video, to be indexed by advanced search engines like Google. You can configure your channel to use a different routing strategy if you like. We use query parameter routing by default because it is highly compatible and also indexable by search engines with no work on your part.

Changing page routing without integrating your site's routing logic can potentially cause issues. Therefore, we support passing a history object as an embed option. We plan to provide built-in adapters for the most common client-side routers.

Channel Embed Options

A channel's embed options can be set using the embedOptionName=value syntax in the container's class attribute, or by using the window._wcq object.

You can see how this syntax is used in the Embed Option documentation for the Player. Please note that channels only support embed options listed on this page. They do not support the same options as the player.

backgroundColor

Set backgroundColor=ffffff to change the background color of the embed to white. Defaults to 000000 (black). This option is best used in conjunction with the foregroundColor option. To remove the background color entirely, set to none.

color

Set color=ff0000 to change the highlight color to the hex value for pure red. Please note that this value should not be preceded by a #, which is commonly used for CSS color values.

The default value is 54bbff.

contentOffsetTop

Set contentOffsetTop=100 to move the text and video content in a Channel down by 100 pixels.

If you have a fixed position header that appears over your channel, this may be necessary to ensure the header does not block channel and player controls. In that case, you will likely want to pair this with the pageFixedHeaderHeight option, e.g. contentOffsetTop=100 pageFixedHeaderHeight=100.

The default value is 0.

customFont

Set customFont=Walsheim to change the heading font to Walsheim. If Walsheim exists as a CSS font-family on the page, it will be used. If it is not available, the channel embed will fall back to displaying the googleFont.

Note that font names with spaces must be percent-encoded if they are included as embed options via the class attribute, e.g. customFont=Slabo%2013px. You can use our percent encoding tool to help with that, if necessary.

If you are setting this font to match your brand and expect to have multiple channels, you can paste a snippet like this in the <head> of your site:

<script>
  window._wcq = window._wcq || [];
  window._wcq.push({
    id: "_all",
    options: {
      customFont: "Walsheim"
    }
  });
</script>

description

Set description=My%20channel%20has%20a%0Amulti-line%20description to change your Channel's description to:

My channel has a
multi-line description

Remember that spaces in embed option values must be percent encoded, which you can get using encodeURIComponent("my description") or by using our percent encoding tool.

foregroundColor

Set foregroundColor=000000 to change the foreground color of the embed (for things like text and icons) to black. Defaults to ffffff (white). This option is best used in conjunction with the backgroundColor option.

googleFont

Set googleFont=Roboto to change the heading font to Roboto. The font name should exactly match the name of the font as it appears in a Google Font's URL. For example, for Open Sans (https://fonts.google.com/specimen/Open+Sans), you'd use googleFont=Open+Sans.

Note that non-heading sections, like the names of videos in section, cannot be changed currently.

The default value is Roboto.

header

Set header[on]=true to turn on the Channel header. Set header[on]=false to turn the Channel header off.

headerFontSizeMultiplier

Set headerFontSizeMultiplier=1.2 to increase the size of heading fonts by 20% its default. You can use this if your base font is naturally small, or if you want an extra large effect.

The default value is 1.

history

The history option lets you integrate your site's routing mechanism with Wistia Channels. Because it defines functions, it can only be passed using _wcq.

window._wcq = window._wcq || [];
window._wcq.push({
  id: "_all",
  options: {
    history: {
      back: function () { ... },
      pushState: function () { ... },
      replaceState: function () { ... },
      state: {
        pointer: 0,
      }
    }
  }
});

When you pass a history object, we will use this object instead of the window.history object to manipulate the page's state. This gives you an opportunity to ensure any history operations work with your client-side routing.

mode

A channel can have two major modes: inline and popover. Set mode=inline to initialize the Channel content directly in the container. Set mode=popover to initialize a Channel "preview card" in container, which launches the full channel view on click.

The default value is popover.

noDescription

By default, a Channel has a description that appears in the hero area when not viewing a video. If you'd like to disable this without modifying the text, use noDescription=true.

The default value is false.

noHeroCta

A "Play" button appears by default in the hero area when a video is not playing. Set noHeroCta=true to remove this button.

The default value is false.

noTitle

By default, a Channel has a title that appears in the hero area when not viewing a video. If you'd like to disable this without modifying the text, use noTitle=true.

The default value is false.

overlayZIndex

When a channel sets mode=popover, it will launch an overlay that is intended to appear over all other elements on your site. Also, when you launch a video, it appears in another overlay that must be above the channel.

If you find that some elements of your site, such as floating headers or social widgets, appear over your channel, you can set this to a higher value, e.g. overlayZIndex=100000. Or if there are certain elements you want to appear on top of it, you can set it to a lower value, e.g. overlayZIndex=500.

The default value is 10000.

playlistLoop

Set playlistLoop=true so that, when all a Channel's videos have been played through, it will loop back to the first one.

resumable

The resumable feature causes videos to pick up where the viewer left off next time they load the page where your video is embedded.

Possible values for the resumable embed option are true, false, and auto. This embed option defaults to auto.

If auto, the resumable feature will only be enabled if the video is 5 minutes or longer, is not autoplay, and is not set to loop at the end. Setting resumable to true will enable resumable regardless of those factors. false disables resumable no matter what.

routeDataToUrl

A function for use with routeStrategy=custom. Refer to routeStrategy for example usage.

The routeData argument will be an Object that may include wchannelid and wmediaid properties. If wchannelid is set, that channel is open. If wmediaid is set, that media is open.

{
  routeDataToUrl: function (currentUrl, routeData) {
    return modifyUrlToIncludeRouteData(currentUrl, routeData);
  }
}

routeStrategy

This option chooses between a few supported methods for reading and writing the URL, as it pertains to Channel routing.

The default value is query-params.

query-params

This is the default. It will read and write these query params:

  • wchannelid
  • wmediaid

anchor-params

Use routeStrategy=anchor-params to set values that look like query params, but they will appear in the page's anchor tag. You can use this if your client-side routing cannot deal with the presence of arbitrary query params, and you do not want to use the history object to make it compatible.

Note that setting routeStrategy=anchor-params will cause the Channel to not be indexable by search engines like Google.

path

Use routeStrategy=path to update and parse the URL using friendly paths that appear native to your site. The format looks like:

https://wistia.com/my/blog/channel-abcde12345/video-fghij67890

That is, the last two path parts, if they begin with channel- and video-, are used to determine the channel ID and video ID.

NOTE: We may add support for friendly name routing at the end of the URL, e.g.

https://wistia.com/my/blog/channel-abcde12345/video-fghij67890/my-cool-video

The routeStrategy=path option is not compatible with most sites' routing code out of the box, which is why this should only be considered for customers with advanced technical resources. To support this, you will need to add special routing rules. For example:

/my/blog/* -> /my/blog

Or if you wanted to support Channels with this route strategy site-wide:

/(.*?)/channel-(.*) -> $1

That is, path parts past /my/blog should also route to /my/blog. This lets our scripts handle the channel routing on the client side.

custom

Use routeStrategy=custom if you want to have complete control over how routes are interpreted and set. If routeStrategy=custom is set, we expect two more functions to be passed as embed options: routeDataToUrl and urlToRouteData. Because these embed options are functions, they must be passed using _wcq.

window._wcq = window._wcq || [];
window._wcq.push({
  id: '_all',
  options: {
    foo: 'bar',
    routeStrategy: 'custom',
    routeDataToUrl: function (currentUrl, routeData) {
      var urlParts = currentUrl.split('?');
      var beforeQueryString = urlParts[0];
      var searchParams = new URLSearchParams(urlParts[1] || '');

      if (routeData.wchannelid) {
        searchParams.set('customChannelParam', routeData.wchannelid);
      } else {
        searchParams.delete('customChannelParam');
      }

      if (routeData.wmediaid) {
        searchParams.set('customVideoParam', routeData.wmediaid);
      } else {
        searchParams.delete('customVideoParam');
      }

      if ('' + searchParams) {
        return beforeQueryString + '?' + searchParams;
      }

      return beforeQueryString;
    },
    urlToRouteData: function (url) {
      var urlParts = url.split('?');
      var searchParams = new URLSearchParams(urlParts[1] || '');
      var result = {};
      var channelParam = searchParams.get('customChannelParam');
      var videoParam = searchParams.get('customVideoParam');
      if (channelParam) {
        result.wchannelid = channelParam;
      }
      if (videoParam) {
        result.wmediaid = videoParam
      }
      return result;
    },
  }
});

NOTE: The example above uses URLSearchParams for a simple demonstration, but it is not supported in Internet Explorer. If you use URLSearchParams, make sure you have a polyfill for it on your website.

title

Set title=My%20Title to change your Channel's title. Remember that spaces in embed option values must be percent encoded, which you can get using encodeURIComponent("my description") or by using our percent encoding tool.

upNextDisplayDuration

Set upNextDisplayDuration=5 to have the "Up Next" preview display for 5 seconds, for example, at the end of the video, instead of the default 10 seconds.

urlToRouteData

A function for use with routeStrategy=custom. Refer to routeStrategy for example usage.

It should return an Object.

{
  urlToRouteData: function (url) {
    return {
      wchannelid: "abc" // the hashed ID of the channel, if it is open
      wmediaid: "def" // the hashed ID of the media, if it is open
    };
  }
}

videoBackgroundHashedId

Set videoBackgroundHashedId=myhashedid to change the background video of your channel to another Wistia video.

The default value is undefined.

videoCardsLayout

A channel can have two different layouts: grid and carousel. Set videoCardsLayout=grid to show all thumbnails in a section at once (in a grid format). Set videoCardsLayout=carousel to show sections of videos within a single row so that you can scroll through to see all of the videos in the section.

Channel API Usage

To use the Channel API, you need to get a Channel handle. This can be accomplished using _wcq.

window._wcq = window._wcq || [];
window._wcq.push({
  id: "channelid",
  onHasData: function (channel) {
    console.log("this is my channel handle!", channel);
  }
});

Or if you just want to play with a channel, you can use the Wistia.channel(...) matching function, which has similar semantics to the Player API Matcher. So for example, if I just want to work with the first channel on the page, I can do:

var channel = Wistia.channel();

If there are multiple channels on the page, I can target them by their hashed ID or DOM ID:

var channel1 = Wistia.channel("itshashedid");
var channel2 = Wistia.channel("itsdomid");

If I want to operate on all the channels on a page, I could do:

Wistia.channel.all().forEach(function (channel) {
  console.log('a channel', channel);
});

Channel API Methods

Wistia Channels currently have a limited public API. Want to do something cool with channels and don't have the tools for it yet? Let us know--it may influence what we make available.

These are the methods that are available now:

currentVideo()

This will return a Player API handle for the video that is currently visible. If there is no video visible, it returns undefined.

console.log(channel.currentVideo().name());

destroy()

Removes a channel from the DOM and cleans up any lingering global references.

channel.destroy();

Note that this will be called automatically within 500ms if a Channel's container has been removed from the DOM. The container's wistia_channel class will change to wistia_channel_destroyed, which stops it from re-initializing.

on(eventName, callback)

Lets you respond to events triggered by Channels.

Returns a function that unbinds the callback.

var removeEventHandler = channel.on("event", function () {
  console.log("an event happened.");
  removeEventHandler();
});

off(eventName, callback)

Provides another mechanism for unbinding an event handler.

var eventHandler = function () {
  console.log("an event happened.");
  channel.off("event", eventHandler);
};
channel.on("event", eventHandler);

Channel Events

currentvideochange

Fires when the primary channel video has changed. It passes a reference to the video which can be used to access the Player API.

channel.on("currentvideochange", function (videoId) {
  if (videoId) {
    var video = Wistia.api(videoId);
    console.log("got a handle to the video", video);
  } else {
    console.log("no video is visible");
  }
});

subscribe

Fires when the viewer has entered in their details and clicks "Subscribe" in the Subscribe Modal. You may want to use this if you are doing custom integration work.

channel.on("subscribe", function (data) {
  console.log(data.firstName, data.lastName, data.email, data.visitorKey);
});

If you're looking for information entered through Turnstile on a video, see the "conversion" event in our Player API.

WordPress and Other oEmbed Consumers

A Channel's Public URL (https://fast.wistia.net/embed/channel/the-channel-hashed-id) serves as its oEmbed URL, too.

Note that the oEmbed endpoint produces Channel Embeds that are of the "popover" type by default. This is because many oEmbed consumers include a maxwidth and/or maxheight option, which does not play well with our default inline responsive Channel Embed.

You can change from the default by adding ?mode=inline to the end of the Public URL, but it will always produce a Channel with a maximum width and height, which will cause it to act like a Fixed Size Inline Channel in many situations.

WordPress

To enable oEmbed support for Wistia, install the Wistia WordPress Plugin. Pasting the Public URL on a line by itself should then cause WordPress to fetch and preview your Channel.

For better operation with Responsive Inline Channels, your WordPress theme should set a very high maximum embed size by modifying $content_width.

Updated about 1 year ago