Player Card

English | 日本語

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

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. Required for Twitter Card analytics .

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. Image must be less than 1MB in size

Yes

twitter:image:alt

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

No

twitter:player:stream

URL to raw stream that will be rendered in Twitter’s mobile applications directly. 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)
No

twitter:player:stream:content_type

The MIME type/subtype combination that describes the content contained in twitter:player:stream. Takes the form specified in RFC 6381. Currently supported content_type values are those defined in RFC 4337 (MIME Type Registration for MP4)

Yes, if stream is provided