Supporting Twitter Cards

Blog 4 min read | May 20, 2013 | JW Player


A while back Twitter introduced a feature called “Twitter cards” that allows you to embed rich content such as video directly into a tweet. The content is then visible when you click “view media” on your timeline, on the permalink for a tweet, when you embed a tweet, and in the official twitter apps. Any site can do this; all you need are some Twitter friendly meta tags in the head of your page and a video page that can be embedded into an iframe. This is really easy to do and Twitter’s official documentation is excellent.

In this blog post I will explain how to set up your page so your video can easily be embedded into Twitter.

Twitter Card Principles

Twitter has three kinds of Twitter Cards: Summary, Photo and Player. This post will only cover the Player type of cards, for tweeting video. If you have different types of media on your site (articles or photos) you will want to look into the other types of cards too.

Building a preview page that can be put in an iframe

In order to play back a video within Twitter’s web page, you will need to create a special page with just the player that Twitter can put into an iframe on the tweet’s details page. This video embed code also needs to work across platforms and devices. Of course the JW Player does just that for you!

A very basic preview page will look like this:

So essentially all you need is a really simple page with a player configured so it fills the entire page. Twitter has a few requirements that you need to follow when building the preview page that gets embedded into Twitter:

  • The preview page and all assets (including the video files) need to be hosted via HTTPS. That means that when you open the preview page directly in the browser, the lock in the navigation bar should be closed. You should also test this on the iOS and Android browsers
  • The content must have stop or pause controls
  • The content must not play automatically
  • The content must not implement its own sharing controls to third party networks, so do not enable the Sharing feature that is in JW Player 6 Premium
  • The content must not require viewers to sign in
  • The content must not be entirely an ad

Adding Twitter Card properties to the head of your page

Similar to Facebook’s OpenGraph tags, you need to put twitter tags into the head of your page. The properties pretty much speak for themselves, so I’m including example code below and will explain a bit more about these properties afterwards:

  • twitter:card This indicates that Twitter should show a player
  • twitter:site This is generally the handle of the official Twitter account for your site
  • twitter:creator This is the handle of the editor/contributor that created the video
  • twitter:url This is the permalink to the page that the video is embedded in
  • twitter:title The title of the video
  • twitter:description The description of the video. The description has a maximum length of 200 characters
  • twitter:image A preview image for the video. This image has a minimum size of 68,600 pixels (a 262×262 square image, or a 350×196 16:9 image)
  • twitter:player This is the link to the preview page for the video that we built previously. This link must be a HTTPS URL.
  • twitter:player:width and twitter:player:height The dimensions of the video preview in pixels
  • twitter:player:stream This is a direct link to your video file. This video file must be an mp4 file. The supported codecs within the file are: H.264 video, Baseline Profile Level 3.0, up to 640 x 480 at 30 fps and AAC Low Complexity Profile (LC) audio. This property is optional
  • twitter:player:stream:content_typeThis is the MIME type for your video file. This property is only required if you have set a twitter:player:stream

We have added these twitter card headers to the preview pages of our video platform too, so if you’re using that, you can simply copy them over from the source of the preview page and have a head start.

URL Crawling

When someone shares a link through Twitter and Twitter has enabled Twitter cards for your domain, Twitter’s crawler will visit your page and check if your page has Twitter Cards set. Twitter uses the Twitterbot User-Agent. If you do have a robots.txt to block certain indexers, you do need to make sure that Twitter’s has access to the areas for which you wish Twitter Cards to show.

Submitting to Twitter

Submitting your site to Twitter is a simple, 3-step process:

  1. Build your Twitter Card integration. Remember to host your video player on HTTPS
  2. Test your markup with Twitter’s preview tool
  3. Apply for approval from the validation tool

All player cards require special whitelisting and approval by Twitter. Unfortunately we have seen reports that approval of Twitter cards for videos can take many months.