# JM Twitter Cards - Documentation

Created: 9/8/2013
by Julien Maury.
French blogger and developer
for TweetPress.fr

Donate to this plugin

Follow me

## What are Twitter cards?

> 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.

## How to get Twitter Cards

Once you have added the specific markup with plugin do not forget to validate your website on dev.twitter :

- Preview tool
- Validation form

## Different types of cards

### Summary cards

### Summary Large Image cards

Almost the same card as Summary Card but with a large image. It is nice, isn't it?

This card requires a minimum width of 280, and a minimum height of 150, the same requirement as Photo cards, that's why it's the smallest size used by the plugin.

The image must not be more than 1mb in size that's why the custom Meta Box includes a checking system that assess your image size and display the result on each post edit. If you do not use cutom meta box be sure to upload image smaller than 1mb in size. If your image is heavier, your card will not break because meta image is not required for summary and summary large image cards but no image will be displayed in your tweets.

### Photo cards

> The Photo Card puts the image front and center in the Tweet:

> 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 width 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

### Product cards

The Product Card is a great way to represent retail items on Twitter, and to drive sales. This Card type is designed to showcase your products via an image, a description, and allow you to highlight two other key details about your product.

These fields are strings and can be used to show the price, list availability, list sizes, etc. This will require adding some new markup tags to your pages, which we will cover below.

Note: The product card requires an image of size 160 x 160 or greater. It prefers a square image but we can crop/resize oddly shaped images to fit as long as both dimensions are greater than or equal to 160 pixels.

To activate this mode you have to activate the custom meta box.

### Gallery cards

> The Gallery Card allows you to represent collections of photos within a Tweet. This Card type is designed to let the user know that there's more than just a single image at the URL shared, but rather a gallery of related images. You can specify up to 4 different images to show in the gallery card via the twitter:image[0-3] tags. You can also provide attribution to the photographer of the gallery by specifying the value of the twitter:creator tag.

## Common issues

If you have any issue, the first thing you have to do is to go to Twitter Cards troubleshooting.

### Twitter card validator does not work with my site !

Don't panic ! It's probably you did not set your robots.txt file according to Twitter's recommandation

This file is used to set specific rules for web crawlers.

Twitter's bot needs to have access to your website to fetch your content, so just insert this in the file :

    User-agent: Twitterbot
    Disallow:

### I don't see images in tweets !

Check that image does not exceed 1mb in size and/or is compatible with Twitter requirements.

### How do I use the custom fields option?

Basically you provide your custom field keys in plugin option page and then it will grab datas.

### I do not see all options in meta box

Just select card type and save draft. You will see additional fields if they exist.

### I want to disable Twitter Card Markup in particular cases

You can use the following snippet in your functions.php or in a functionality plugin.

Here I disable Twitter Cards for both page with ID 19 and page slug 'contact' :

    add_action('wp_head','disable_twitter_card_info');
    function disable_twitter_card_info() {
    	if(is_page(array(19,'contact'))) remove_action('wp_head', 'add_twitter_card_info',99);
    }

Here I disable Twitter Cards for post with format 'status':

    add_action('wp_head','disable_twitter_card_info');
    function disable_twitter_card_info() {
    	if(has_post_format( 'status' )) remove_action('wp_head', 'add_twitter_card_info',99);
    }

### Where are Open Graph Metas added by Jetpack?

Jetpack has been set to detect JM Twitter Cards and deactivate its Twitter Cards feature in case where both plugins are activated. However code for Twitter Cards and Open Graph are located in the same function in the plugin's code that is why Open Graph meta do not show up when JM Twitter Cards is on. The solution might be to add some Open Graph plugin to enjoy both JetPack and JM Twitter Cards.

# Plugin options

In 3.3.6 Plugin UI has been renewed with some flat design and in a simpler way. Only option and all explanations in documentation. All sections includind meta box on post edit has now a link to documentation.

## General

This is the first section. You can set which type of card will be the default type used in your website. You must define twitter card creator (username) and twitter card site (username). If they are the same just enter username twice.

You can also set how many words the plugin has to grab to set a description by default. This allows to avoid empty twitter meta description which often breaks twitter cards.

Last setting is for multi-author blogs. It allows your authors to get an additional field in their profile. They can provide their Twitter Account. This is meant to improve authorship. If they publish a post, their twitter usernames will be set as twitter meta creator.

Since 3.3.4 there is a new setting that allows you to use your own field for Twitter's field in profiles. A lot of theme have this feature so you probably want to keep only one field :

Be careful the key you have to provide MUST BE the key your theme use to set the Twitter's field in profile ! In addition to this, THE VALUE MUST BE A USERNAME not a URL such as http://twitter.com/user it could break the cards !

If you experience any issue or if you mess with this option just recover with the key :
jm_tc_twitter

## SEO

WordPress is great but we often need to add some SEO plugins such as WP SEO by Yoast or All In One SEO. These plugins are very very popular and you can find them in a lot of WP installations. JM Twitter Cards checks if one of the two plugins is activated and grabs meta title and description you have set. This allows you not to waste your time writting things twice for each post. If you forget to fulfill SEO fields do not panic, there are fallback (post title and the first words of your post as description). Do not forget to choose how many words the plugin has to grab for twitter meta description(max 200).

And if you do not use one of this two plugin you can use your own custom fields instead. Just provide meta keys (advanced users).

## Images

Use the dropdown menu to choose which size you want to set by default (you can override this with the metabox fields). You can now choose (3.3.0) to force crop or not. Do not forget to enter a fallback image in case no option is set. You can also set twitter image with and height to get a better control of cards display (only for photo and product cards).

## Home settings

If home page is posts page (which is often the case), this setting allows you to define a Twitter Card title and description. This prevent from getting the datas from the first post in the loop.

## Meta Box

This is one of the best features of the plugin. It allows to customize your cards for each post and you get extra features...

Once it's activated you'll get a custom meta box in your post edit :

With version 3.3.1 the plugin allows you to dismiss metabox if you do not want or need to use it. This introduces more flexibility for users who do not need to use metabox on each post. If option is set to "yes, please deactivate it", the datas will be set by general options.

To use new feature (in 3.3.6) Gallery cards, just use the WordPress Gallery System

This is meant to let the user know that there is more than just a single image at the URL shared, but rather a gallery of related images. So these images have to be part of a WordPress gallery. Please ensure you use the shortcode [gallery] in your post to enjoy Gallery cards

### Extra settings

If you select photo, or summary large image or product cards and then save draft you'll see additional fields you can set such as :

- Retina display: Be careful with Retina displays, image must be tall enough. Also make sure your image is not heavier than 1 MB if used for summary large cards
- Image options : This is optional but some users wanted alternatives for featured image
- Product card options : You can set 2 key details for your product (e.g price, size, etc)