Getting Started Guide

Getting Started with Cards

To get started with implementing the Cards markup, you'll want to specify the type of card for your content by adding the following HTML to the HEAD section of your page:

<meta name="twitter:card" content="summary">

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 have one basic property in common and that is the card type value:

Card Property	Description
twitter:card	The card type, which will be one of "summary", "photo", "gallery", "product", "app", or "player".

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:

Card Property	Description	Required
twitter:site	@username for the website used in the card footer.	No
twitter:site:id	Same as twitter:site, but the website's Twitter user ID instead. Note that user ids never change, while @usernames can be changed by the user.	No
twitter:creator	@username for the content creator / author.	No
twitter:creator:id	Same as twitter:creator, but the Twitter user's ID.	No

URL Crawling & Caching

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 (with version, such as 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:

Here is another example, which specifies which directories are allowed to be crawled by Twitterbot (in this case, disallowing all except the images and archives directories):

Your server's robots.txt file must be saved as plain text with ASCII character encoding. To verify this, you can run the following command:

Your content is cached by Twitter for 7 days after a link to your page with card markup has been published in a tweet.

If you encounter issues with your tweets not appearing properly, please see our Cards Troubleshooting Guide.

Multiple URLs in a Tweet

In some circumstances, users many want to tweet multiple URLs. Below is the order of how we treat multiple URLs when processing Cards:

1. Cards from pic.twitter.com and vine.com have preference over alternate domains
2. URLs are processed in order of appearance in the tweet, first to last

For more background, this order was requested from early partners who requested to use pic.twitter.com to show rich images and also allow linking to richer, on-brand content. We maintain this feature for posterity, but is subject to change moving forward.

Twitter Cards and Open Graph

You'll notice that Twitter card tags look similar to Open Graph tags, and that's because they are based on the same conventions as the Open Graph protocol. If you're already using Open Graph protocol 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 recommends specifying the "og" RDFa Core 1.1 CURIE prefix mapping via <html prefix="og: http://ogp.me/ns#">, no such markup is required for Twitter cards and its use of the "twitter:" prefix in a HTML meta element's name attribute. Open Graph protocol 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 content. Twitter's parser will fall back to using property and content, so there is no need to modify existing Open Graph protocol 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: