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 Rules of the Road, you can deliver your rich media to users across the globe.
Player Card examples
Below are two examples of great Player Card experiences:
|
|
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:
- Unzip the contents into a publicly accessible path on your website
- Open the index.html file and ensure the twitter:image, twitter:player and twitter:player:stream values point to your server and file locations
- Ensure all paths are specified as secure (https://)
- 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:
- Go to the Card Validator
- Click on the “Validate & Apply” tab
- Supply your URL and click “Go!”
- If the meta tags are all properly in place, click on “Submit for Approval”
- 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 may take up to a week for approval. 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,
- Default to ‘sound off’ for videos that automatically play content
- Content greater than 10 seconds in length must not automatically play
- Include stop, pause and play controls
- Mark your Card as ‘true’ for sensitive media if such media could be displayed.
- 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:
- Don't surprise users
- Don't create or distribute spam
- Respect user privacy
- 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.)
If the iframe is wider than 435px, the iframe player will be resized to fit a max width of 435px, maintaining the original aspect ratio.
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.
App Downloads and Deep Linking
In addition to displaying your content in a more engaging way, the Summary Card can also drive downloads of and even link directly into your mobile applications. For more information, see App Installs and Deep-Linking.
Additionally, you can learn how to deep-link from this Card into your mobile app by reading here.
Reference
| Card Property | Description | 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:description | A description of the content in a maximum of 200 characters. | Yes |
| 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. | 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: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:
|
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 |