Twitter Cards

Introduction

Twitter cards make it possible for you to attach media experiences to Tweets that link to your content. Simply add a few lines of HTML to your webpages, and users who Tweet links to your content will have a "card" added to the Tweet that’s visible to all of their followers.

We currently are in the process of slowly rolling out the technology to 100% of users. Not all users will see Cards for the time being.

As a developer, Twitter cards can...

• Give you control of how your content is displayed with Tweets
• Drive traffic to your site
• Increase the number of people following your Twitter accounts through content attribution

We’re in the process of bringing this new content preview experience to users on Twitter. And over the coming weeks we want to generate content previews for more sites from around the web. To participate in the program, you should (a) read the documentation below, (b) determine whether you wish to support Twitter cards, and then (c) apply to participate. As we roll out this new feature to users and publishers, we are looking for sites with great content and those that drive active discussion and activity on Twitter.

Card Principles

A "summary" Twitter Card on twitter.com with content attribution.

There are 3 card types that can be attached to Tweets, each of which has a beautiful consumption experience built for Twitter's web and mobile clients:

• summary: The default card, which includes a title, description, thumbnail image, and Twitter account attribution.
• photo: A Tweet sized photo card.
• player: A Tweet sized video/audio/media player card.

Specify the type of card for your content by adding the following HTML to the HEAD section of your page:

Card properties are simple key-value pairs, each defined in its own HTML meta tag as you see above. The combined collection of properties defines the overall card experience on Twitter, and each card supports and requires a specific set of properties. Only one card per-page is supported. All cards support a few basic properties:

Each card uses these properties in slightly different ways, which are described in the individual card sections below.

Card and Content Attribution

Each card has built-in content attribution, which surfaces appropriate Twitter accounts for the content as specified by you. Viewing users will be able to follow and view the profiles of attributed accounts directly from the card. There are two kinds of attribution:

Website Attribution: Indicates the Twitter account for the website or platform on which the content was published. Note that a service may set separate Twitter accounts for different pages/sections of their website, and the most appropriate Twitter account should be used to provide the best context for the user. For example, nytimes.com may set the the website attribution to "@nytimes" for front page articles, and "@NYTArts" for articles in the Arts & Entertainment section.

Creator Attribution: Indicates the person that created the content shown in the card.

Configure your card attribution using the following properties:

Summary Card

The summary card can be used for many kinds of web content, from blog posts and news articles, to products and restaurants. The screenshot below shows the expanded Tweet view for a New York Times article:

Web	Mobile

The card is designed to give the reader a preview of the content before clicking through to your website. You’ll notice that this card makes use of all of the properties described in the previous section: URL, title, description, and image.

If any required fields are omitted, the card may not be shown in the Tweet. Note that the card displays clear attribution for both the website and content creator. Here's the full HTML for the card above:

Photo Card

The photo card puts the image front and center in the Tweet:

Web	Mobile

To define a photo card experience, set your card type to "photo" and provide a twitter:image. Twitter will resize images, maintaining original aspect ratio to fit the following sizes:

• Web: maximum height of 375px, maximum width of 435px
• Mobile (non-retina displays): maximum height of 375px, maximum width of 280px
• Mobile (retina displays): maximum height of 750px, maximum with of 560px

Twitter will not create a photo card unless the twitter:image is of a minimum size of 280px wide by 150px tall. Images will not be cropped unless they have an exceptional aspect ratio. All images will be fetched and proxied by Twitter to ensure a high quality of service and SSL security for users.

Specifying the width and height using twitter:image:width and twitter:image:height helps us more accurately preserve the aspect ratio of the image when resizing.

Photo cards are the only type of card which support a blank title. To render no title for the photo card, explicitly include a blank title element. For example: <meta name="twitter:title" content="">.

Animated gifs are currently not supported in Twitter Cards.

Define the photo card with these properties:

Here’s example markup for a photo card:

Player Card

The player card is for interactive media experiences like videos, music players, and live streaming events, and allows you to present your content inside of an iframe within the Tweet. Unlike the photo and summary card, you control the entire content experience, and are responsible for providing an implementation that works across Twitter clients including:

• twitter.com and mobile.twitter.com
• Twitter for iPhone
• Twitter for Android

Web	Mobile

Due to platform capabilities, player cards work a bit differently on each client and it’s important to understand these details before you begin building your card experience. Here’s how it works:

On twitter.com, the iframe you specify will be shown immediately when a user expands a Tweet in their timeline. It will be shown automatically when the Tweet is pinned open on a user’s profile, or viewed on a Tweet permalink page. If the iframe is wider than 435px, the iframe player will be resized to fit a max width of 435px, maintaining the original aspect ratio.

In Twitter's native mobile applications (e.g. Twitter for iPhone and Twitter for Android), an image preview will be displayed in place of the video, and linked to one of the following, in preference order:

1. The URL specified in twitter:player:stream. When a user taps on the image preview, the application will load the media stream from this URL and play it within the application. If provided, the stream must be delivered in the MPEG-4 container format (the .mp4 extension). The container can store a mix of audio and video with the following codecs:

• Video: H.264, Baseline Profile (BP), Level 3.0, up to 640 x 480 at 30 fps.
• Audio: AAC, Low Complexity Profile (LC)

On mobile.twitter.com, our mobile web client, an image preview will be displayed in place of the video, and linked to one of the following, in preference order:

1. The URL specified in twitter:url
2. The URL that the user originally shared in their Tweet.

Other clients will link to the URL in the user’s Tweet, opening it up in the default web browser of the client platform.

All player cards require special whitelisting and approval by Twitter.

A few simple rules for Cards

Do:

• Build a responsive and equivalent experience that works within all Twitter Clients. Cards that do not work in all Twitter clients listed above will not be approved.
• Test your experience on the native browsers of Twitter Clients before submitting for approval.
• Provide a raw stream to video and audio content when possible.
• Use HTTPS for your iframe, stream, and all assets within your card.
• Use wmode=opaque if utilizing Flash for the twitter.com experience, so that the player renders at the correct z-index.

Do not:

• Generate mixed content browser warnings. All Twitter clients use HTTPS, and you must not break the lock of the browser.
• Automatically play content.
• Require users to sign-in to your experience.
• Commingle sharing features from other networks inside your player.

Define the player card with these properties:

Here is sample markup for a player card:

Here is sample markup for a player from foobar.com where foobar.com is also providing a URL to a raw stream to be rendered in Twitter's mobile applications.

URL crawling

Twitter's crawler will respect robots.txt when scanning URLs. If a page with card markup is blocked, no card will be shown. If an image URL is blocked, no thumbnail or photo will be shown.

Twitter uses the User-Agent of Twitterbot/1.0, which can be used to create an exception in your robots.txt file. For example, here is a robots.txt which disallows crawling for all robots except Twitter's fetcher:

Twitter cards and Open Graph

You'll notice that Twitter card tags look similar to OpenGraph tags, and that's because they are based on the same conventions as the Open Graph protocol. If you're already using OpenGraph to describe data on your page, it’s easy to generate a Twitter card without duplicating your tags and data. When the Twitter card processor looks for tags on your page, it first checks for the Twitter property, and if not present, falls back to the supported Open Graph property. This allows for both to be defined on the page independently, and minimizes the amount of duplicate markup required to describe your content and experience.

Note that while Open Graph requires specifying the "og:" prefix via <html prefix="og: http://ogp.me/ns#">, no such markup is required for Twitter cards or the "twitter:" prefix. OpenGraph also specifies the use of property and content attributes for markup (<meta property="og:image" content="http://example.com/ogp.jpg"/>) while Twitter cards use name and value. Twitter's parser will fall back to using property and content, so there is no need to modify existing OpenGraph markup if it already exists in your page.

The example below uses a mix of Twitter and Open Graph tags to define a summary card:

The table in the next section explains the OpenGraph fallback behavior for each Twitter tag.

Overview of all Twitter Card Tags