Optimize Tweets with Cards

Player Card

Video and audio clips have a special place on the Twitter platform thanks to the Player Card. By implementing a few HTML meta tags to your website and following the Twitter Developer Policy, you can deliver your rich media to users across the globe.

  1. Player Card examples
  2. Getting started
  3. Testing your Card
    1. On Web
    2. On iPhone
    3. On Android
  4. Player card policy
  5. The Player Card across platforms
    1. On iPhone and Android (and other native mobile apps)
    2. On twitter.com (via desktop browser)
    3. On mobile.twitter.com and other clients
  6. Reference
  7. Additional resources

 

Player Card Example

 

Getting started

To help you get started, we’ve provided the following Twitter Card Getting Started Bundle. This bundle includes sample code and a readme with more detailed instructions. The basic steps are:

  1. Unzip the contents into a publicly accessible path on your website
  2. Open the index.html file and ensure the twitter:image and twitter:player values point to your server and file locations
  3. Ensure all paths are specified as secure (https://)
  4. Test your URL (See the Testing your Card section below)

The Card Validator is a simulated Card experience, and it won’t be exactly what you see when your Player Card is live. You’ll get a static, non-playable image.

 

Testing your Card

To further help you in building your experience, below are instructions on how to test your experience across the various platforms.

On Web

Enter the twitter:player URL in a browser. In the image to the right, note that the video has NOT yet begun play, takes up the entire space, and the secure browser lock (top left) is still intact. Please note that an active mixed content warning (signified by a red ‘X’ over the lock) will not be approved. image2
Secondly, in the image to the right, the video has begun play. image3

On iPhone

Enter the twitter:player URL in a browser on iPhone. In the image to the right, note that the video has NOT yet begun play, fits the full screen, and the secure browser lock (top left) is still intact. As noted previously, an active mixed content warning will not be approved.

 image6
Secondly, in the image to the right, the video has begun play. image7

On Android

Similar to instructions for iPhone, enter the twitter:player URL in a browser on Android. When opened, the video has NOT yet begun play, fits the full screen, and the secure browser lock (top left) is still intact. As noted previously, an active mixed content warning will not be approved.

 

Player card policy

We’ve published our Twitter Developer Policy, which cover the broad strokes of policy when building on the Twitter platform. The below bullets make these requirements concrete for Player Cards.

Do:

  • Test your experience across all Twitter clients, including Twitter’s iPhone and Android apps, as well as twitter.com and mobile.twitter.com. Cards that do not work in all Twitter clients listed will not be approved.
  • Build your HTML page used in the iFrame to be responsive, ensuring the video content fills the full width of any display area provided, across all clients.
  • Use HTTPS for your iFrame and all assets within your meta tags.
  • For video and audio content,
    1. Default to ‘sound off’ for videos that automatically play content
    2. Content greater than 10 seconds in length must not automatically play
    3. Include stop, pause and play controls
  • Mark your Card as ‘true’ for sensitive media if such media could be displayed.

Do not:

  • Do not violate the Twitter Developer Policy and Display Requirements. As a reminder, the core principles of the Twitter Platform are:
    1. Don’t surprise users
    2. Don’t create or distribute spam
    3. Respect user privacy
    4. Be a good partner to Twitter
  • Do not circumvent the intended use of the Card. Player Cards are reserved for linear audio and video consumption only.
  • Do not require users to sign-in to your experience.
  • Do not attach additional interactivity outside the video or audio player (e.g., banners or non-standard buttons).
  • Do not build end-to-end interactive experiences inside the video or audio player unrelated to Player Card content, such as the following: purchasing, gaming, polling, messaging, and data entry. Instead, build these interactive experiences with our other Card types or enhance your Player Card content with links to your website or mobile application.
  • Do not generate active mixed content browser warnings at any point during the audio or video experience, either on load or during play. For more information, see the Troubleshooting Guide.

 

The Player Card across platforms

Due to platform capabilities, player cards work a bit differently on each client. Below is a quick rundown of the behavior across various platforms.

On iPhone and Android (and other native mobile apps)

On Twitter’s iPhone and Android native apps, a Player Card will appear in the Tweet detail view (not in the timeline) and initially appears as the image preview (specified via twitter:image) with a “play” icon over it. When tapped, the native app opens the URL specified by twitter:player in a simulated browser.

On twitter.com (via desktop browser)

When viewing a Tweet with a Player Card on a desktop, the URL you specify via twitter:player will be rendered in the timeline upon expand of the Tweet. (It will be shown automatically when the Tweet is pinned open on a user’s profile, or viewed on a Tweet permalink page.)

The player will be scaled to fit the appropriate width, maintaining the original aspect ratio as provided by the twitter:player:width and twitter:player:height.

On mobile.twitter.com and other clients

On mobile.twitter.com and other clients, the image preview is displayed, and links directly to the URL in the user’s Tweet in the default web browser of that platform.

 

Reference

Card Property Required

twitter:card

Must be set to a value of “player”

 Yes

twitter:title

The title of your content as it should appear in the card

 Yes

twitter:site

The Twitter @username the card should be attributed to.

 Yes

twitter:description

A description of the content in a maximum of 200 characters

 No

twitter:player

HTTPS URL to iFrame player. This must be a HTTPS URL which does not generate active mixed content warnings in a web browser. The audio or video player must not require plugins such as Adobe Flash.

 Yes

twitter:player:width

Width of iFrame specified in twitter:player in pixels

 Yes

twitter:player:height

Height of iFrame specified in twitter:player in pixels

 Yes

twitter:image

Image to be displayed in place of the player on platforms that don’t support iFrames or inline players. You should make this image the same dimensions as your player. Images with fewer than 68,600 pixels (a 262x262 square image, or a 350x196 16:9 image) will cause the player card not to render. Images must be less than 5MB in size. JPG, PNG, WEBP and GIF formats are supported. Only the first frame of an animated GIF will be used. SVG is not supported.

 Yes

twitter:image:alt

A text description of the image conveying the essential nature of an image to users who are visually impaired. Maximum 420 characters.

 No

 

Additional resources