Optimize Tweets with Cards
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.
- Player Card examples
- Getting started
- Testing your Card
- Submitting your Card for approval
- What the approval team looks for
- The Player Card across platforms
- App Downloads and Deep Linking
- Additional resources
Player Card Example¶
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:player:streamvalues 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.
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 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.
- 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 Developer Policy and Display Requirements. 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:
twitter:player:streamis provided AND the
twitter:player:stream:content_typeis specified as “video/mp4”, the app plays the stream URL directly from the app.
- If no
twitter:player:streamis provided, the native app opens the URL specified by
twitter:playerin 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.
Must be set to a value of “player”
The title of your content as it should appear in the card
The Twitter @username the card should be attributed to.
A description of the content in a maximum of 200 characters
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.
Width of iFrame specified in twitter:player in pixels
Height of iFrame specified in twitter:player in pixels
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.
A text description of the image conveying the essential nature of an image to users who are visually impaired. Maximum 420 characters.
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:
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|