Player Card

Video clips and audio streams 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 Rules of the Road, 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. Submitting your Card for approval
5. What the approval team looks for
6. 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
7. App Downloads and Deep Linking
8. Reference
9. 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, twitter:player and twitter:player:stream 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. (In particular, if you only supply a twitter:player with no twitter:player:stream, you’ll get a static, non-playable image.) We’re working on improving it. That said, it does indicate if your basic configuration works.

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.
Secondly, in the image to the right, the video has begun play.

On iPhone

Enter the twitter:player URL in a browser on iPhone, (If implemented using twitter:player, and not twitter:player:stream.) 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.
Secondly, in the image to the right, the video has begun play.

On Android

Similar to instructions for iPhone, enter the twitter:player URL in a browser on Android. (If implemented using twitter:player, and not twitter:player:stream.) 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.

Submitting your Card for approval

Our team is excited to bring your content to Twitter, and in a way that allows for a secure and consistent experience to all our users and across all our platforms. Our approval process includes testing your experience across the various platforms, as well as re-validating it periodically.

After you’ve tested your Player Card via the Card Validator, you also use the Validator to submit for approval. This is done in few simple steps:

1. Go to the Card Validator
2. Click on the “Validate & Apply” tab
3. Supply your URL and click “Go!”
4. If the meta tags are all properly in place, click on “Submit for Approval”
5. Fill out the form, including your e-mail address so we can contact you for updates

Before submitting for approval, ensure that you’re using *your* content, and not the content provided in the sample code bundle.

Player Cards are usually approved in a few business days. Please be sure to check your e-mail (and spam folder) often for updates from our approval team.

What the approval team looks for

We’ve published our Twitter Rules of the Road, 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 (referenced via twitter:player:stream) to be responsive, ensuring the video content fills the full width of any display area provided, across all clients.
• Use HTTPS for your iframe, stream 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 Rules of the Road and Trademark and Content Display Guidelines. 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 initially appears as the image preview (specified via twitter:image) with a “play” icon over it. When tapped, the following occurs:

• If twitter:player:stream is provided AND the twitter:player:stream:content_type is specified as “video/mp4”, the app plays the stream URL directly from the app.
• If no twitter:player:stream is provided, the native app opens the URL specified by twitter:player in a simulated browser.

Again, specifying an MP4 file and indicating twitter:player:stream:content_type as “video/mp4” will allow playback of the video inline in our mobile applications. See the Technical reference section below for more details.

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 an iframe 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 iFrame 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

Additional resources

• Twitter Cards Getting Started Bundle
• Card Validator
• Card Troubleshooting Guide
• App Installs and Deep-Linking
• Twitter Card Forums
• Twitter Rules of the Road