Getting Started Guide
Getting Started with Cards
빅히트 엔터테인먼트의 신인 그룹 투모로우바이투게더. TOMORROW X TOGETHER - The New Boy Group from Big Hit Entertainment.
To get started with implementing Cards markup, specify the type of card for your content by adding the following HTML markup to the HEAD section of the page:
- We would like to show you a description here but the site won’t allow us.
- TXT WORLDWIDE on Twitter. March 2021 “Minisode 1: Blue Hour Concept Photo R Version #HUENINGKAI (1) #BlueHourR @TXTmembers @TXTbighit”.
Card properties are simple key-value pairs, each defined in an HTML meta tag as seen above. The combined collection of properties defines the overall card experience on Twitter, and each card type supports and requires a specific set of properties.
All cards have one basic property in common - the card type value:
Card Property | Description |
twitter:card | The card type, which will be one of “summary”, “summary_large_image”, “app”, or “player”. |
Only one card type per-page is supported. If more than one
twitter:card
value exists in the page, the “last” one in sequence will take priority.Card and Content Attribution
Each card has built-in content attribution, which surfaces appropriate Twitter accounts for the content as specified by you. Users will be able to follow and view the profiles of attributed accounts directly from the card. There are two kinds of attribution:
Website Attribution: Indicates the Twitter account for the website or platform on which the content was published. Note that a service may set separate Twitter accounts for different pages/sections of their website, and the most appropriate Twitter account should be used to provide the best context for the user. For example, nytimes.com may set the the website attribution to “@nytimes” for front page articles, and “@NYTArts” for articles in the Arts & Entertainment section.
Creator Attribution: Indicates the individual user that created the content within the card. This applies to the Summary with Large Image card.
Configure card attribution using the following properties:
Card Property | Description | Required |
twitter:site | @username for the website used in the card footer. | No |
twitter:creator | @username for the content creator / author. | No |
URL Crawling & Caching
Twitter’s crawler respects Google’s robots.txt specification when scanning URLs. If a page with card markup is blocked, no card will be shown. If an image URL is blocked, no thumbnail or photo will be shown.
Twitter uses the User-Agent of Twitterbot (with version, such as Twitterbot/1.0), which can be used to create an exception in the
robots.txt
file.For example, here is a
robots.txt
which disallows crawling for all robots, except Twitter’s fetcher:Here is another example, which specifies which directories are allowed to be crawled by Twitterbot (in this case, disallowing all except the images and archives directories):
The server’s
robots.txt
file must be saved as plain text with ASCII character encoding. To verify this, run the following command:Content is cached by Twitter for 7 days after a link to a page with card markup has been published in a Tweet.
If you encounter issues with cards in Tweets not appearing properly, see the Cards Troubleshooting Guide.
Card Display
Twitter Cards generated from meta tags only appear when a Tweet is either expanded in the timeline (on web) or viewed on the Tweet’s individual permalink page (by clicking on the date from the timeline, either on web or on mobile).
Text Twitter Header
In limited circumstances, Cards may appear in the timeline, such as in images posted to Twitter, Ad formats, and Twitter-run experiments.
If you are looking to bring media (photos, videos and Cards) into the timeline, consider one of the following options:
- Accounts can pin a Tweet to the top of their timeline, which auto-expands the Tweet and displays the Card. (This is possible on web only.).
- For photos and animated GIFs, upload the media directly with the Tweet or consider using the Twitter API to upload media.
- For Ad formats with a call-to-action, visit Twitter Ads for Website Cards.
Multiple URLs in a Tweet
In some circumstances, users may want to Tweet multiple URLs. Only one card may be shown in a Tweet. Here is the order of precedence when processing multiple URLs:
- Images or media attached to Tweets will have precedence over any card attached to a URL.
- URLs with cards are processed in order of appearance in the Tweet, first to last
Twitter Cards and Open Graph
Twitter card tags look similar to Open Graph tags, and are based on the same conventions as the Open Graph protocol. When using Open Graph protocol to describe data on a page, it is easy to generate a Twitter card without duplicating tags and data. When the Twitter card processor looks for tags on a page, it first checks for the Twitter-specific property, and if not present, falls back to the supported Open Graph property. This allows for both to be defined on the page independently, and minimizes the amount of duplicate markup required to describe content and experience.
Note that while Open Graph recommends specifying the “og” RDFa Core 1.1 CURIE prefix mapping via
<html prefix='og: http://ogp.me/ns#'>
, no such markup is required for Twitter cards and its use of the twitter:
prefix in a HTML meta element’s name attribute. Open Graph protocol also specifies the use of property
and content
attributes for markup (<meta property='og:image'/>
) while Twitter cards use name
and content
. Twitter’s parser will fall back to using property
and content
, so there is no need to modify existing Open Graph protocol markup if it already exists.The example below uses a mix of Twitter and Open Graph tags to define a summary card:
Troubleshooting Guide
Use this troubleshooting guide to help to identify and resolve commonly encountered issues during Cards development.
If you are unable to find the solution to an issue here, please use the Twitter Cards category on the developer forums.
- Card Validator
- Player Card Approval
- Card Display Issues
- Refreshing a Card in a Tweet
- Debugging Player Cards
Checking your site's SSL configuration
Twitter's web crawler requires the use of TLS v1.1 or higher. You should also confirm that other aspects of your site's SSL configuration are correct, using a service like Qualys SSL Labs.
Incorrect configuration may prevent Twitter's web crawler from accessing your site.
Card Validator
I get the message, “ERROR: Fetching the page failed because the request timed out.”
There are a number of possible explanations for this:
- Your CMS site is configured to block web crawlers. If you are using Wordpress, Blogger or another hosted CMS provider, your settings may inadvertently blocking crawler access from our servers. You can read our CMS integration page to see how to enable web crawler access to your CMS site.
- Your website has a robots.txt file that is blocking Twitter from getting your Card metadata. To learn how to diagnose this case, click here.
- Your Apache .htaccess file is denying requests.You can check this by opening your
.htaccess
file and looking for something like the following:Be sure to remove any deny directives from your.htaccess
file. - An image is too large for our web crawler to download. Our web crawler will typically download up to 5MB images. If you are seeing this issue, you may want to scale down the size of the image significantly and try again.
- A network lag is causing a delay in fetching your site/images. If your server is in a remote location and/or has unreliable network access, our web crawlers may have difficulty downloading your meta tags and/or images. Please retry as necessary.
- Your web host may be blocking web crawler access to your site. You should contact your hosting provider and ask them to ensure they are not blocking Twitter access by either IP or ASNUM. Twitter’s aggregate outbound IP ranges are 199.16.156.0/22 and 199.59.148.0/22. Twitter’s ASNUM is AS13414.
I get the message, “Failed to get a proxied URL for the image.” (or an image is not shown)
The most common cause is that the image specified via the
twitter:image
tag isn’t publicly accessible on the web. This often happens when testing against a staging/internal-only network. To resolve, make sure your image can be accessed via the public internet.I get the message, “Invalid Image. This image cannot be fetched.”
There are a couple of possible explanations for this:
- The dimensions of the image are smaller than the recommended size. We suggest that images are a minimum of 144 x 144 pixels in size.
- A network lag is causing a delay in fetching your images. If your server is in a remote location and/or has unreliable network access, our web crawler may have difficulty downloading your meta tags and/or images. Please retry as necessary.
As a side note, we’re working to improve error messages in the Card validator. Please be patient as we make updates.
I get the message, “Caught Exception in App Proxy Service..”
The most common cause is that the ID specified for the
twitter:app:id.*
tag is prefixed with “id”. Try removing the prefix (so it only has an integer value) and re-submitting to the validator.I get the message, “Invalid card type.”
The most common cause is that the page is missing a content-type META directive. It might look something like the following
I get the message, 'ERROR: Fetching the page failed because the response is too large.'
Twitter's crawler has a limit of 2 MB for page responses. If you are seeing this issue, you should try reducing the size of the HTML response so that it is below the limit.
The validator can’t reach my testing/staging environment.
Many testing or staging environments run under restricted access. As a result, our validator can’t access these servers to read the Card tags.
Below are a couple of solutions that other developers have found helpful:
- Run your web server on a different, publicly-accessible port.
- Configure your firewall to route port-specific requests to your test/staging environment.
- Configure your web servers to allow Twitter access via the robots.txt file. Twitter uses the User-Agent of Twitterbot (with version, such as Twitterbot/1.0), which can be used to create an exception in your
robots.txt
file. User-agent:Twitterbot
Disallow:
- Twitterbot implements Google’s robots.txt specification
Cards Approval
How do I get my Player Card approved?
Player Card implementations are reviewed to ensure they fit the guidelines for publishing to Twitter. This process sometimes takes longer than expected.
To help make this process as smooth and quick as possible, verify the following:
- You’ve added the proper Cards mark-up to your page, and your page is publicly accessible.
- You’ve tested your site through the Cards validator.
- You’ve submitted your Card for approval by clicking on the “Request Approval” button.
- The
twitter:player
URL opens and plays properly in a browser.
This will help make approval as quick as possible. Also, be sure to review the other issues listed on this page.
My Player Card hasn’t been approved for the allowlist. What does that mean?
If your Player Card was rejected, read through the documentation again, test your Player Card in the validator, and then resubmit.
The Player Card has a number of guidelines, which you can read on the Player Cards Do’s & Don’ts section.
For other issues not covered there, please continue reading below.
I’ve re-submitted my Player Card for approval. What happens next?
We will review your Player Card and respond within three weeks. If you have problems blocking you from testing, please use the Twitter Cards category on the developer forums.
Card Display Issues
My Tweet is missing the image/video/summary text.
There are a number of possible reasons for this. Here are some suggestions and ways to troubleshoot:
- Your Player Card has yet to be added to the allowlist. Please run your example URL through the Card Validator, and click the Request Approval button to begin the allowlist process.
- Your website has a robots.txt file that is blocking us from getting your Card metadata. To learn how to diagnose this case, click here.
- The video format is not supported. For steps to debug your video, click here.
My Card doesn’t appear in the timeline.
Twitter Cards generated from developer meta tags only appear when a Tweet is either expanded in the timeline (on web) or viewed on the Tweet’s individual permalink page (by clicking on the date from the timeline, either on web or on mobile).
In limited circumstances, Cards may appear in the timeline, such as in images posted to Twitter, Ad formats and Twitter-run experiments.
If you are looking to bring media (photos, videos and Cards) into the timeline, please consider one of the following options:
- Accounts can pin a Tweet to the top of their timeline, which auto-expands the Tweet and displays the Card. (This is possible on web only.).
- For photos, animated GIFs and videos, upload the media directly with the Tweet or consider using the Twitter API to upload media.
- For Ad formats with a call-to-action, visit Twitter Ads for Lead Generation and Website Cards.
My Tweet shows an outdated version of my Card.
Once you’ve been registered for your domain, our web crawlers re-index the meta information on your tag roughly every week.
If you’re testing and/or iterating on your Cards, it is sometimes helpful to test updates. You can follow these instructions to view updates to your Cards.
Refreshing a Card in a Tweet
I updated my site meta tags, but my Tweet shows the old Card. How do I refresh the Card?
Our web crawlers re-index the Card tag information on your page roughly every week.
When testing and/or iterating on Cards, it is sometimes helpful to test updates on your timeline. It may be possible to use the following technique to refresh the cache with your most up-to-date changes of your page’s Card.
- Add Card metadata to a page
- Tweet URL to that page
- Refresh your browser to view the Card contents on your timeline
- Change Card metadata on the page
- Take the same URL and runs it through bit.ly
- Tweet the new bit.ly URL
- Refresh your browser to view the updates
Additionally, you can create multiple bit.ly URLs to allow for repeat testing. For example, adding placeholder value parameters to the end of your URL (
http://www.test.com/?x=test1
) or a unique hash (http://www.test.com/#test1
) will generally not affect the page contents, but will generate a unique bit.ly URL for each unique value of x.My Card information now refreshes, but images are not updating. How do I get the images to refresh?/a>
Images referenced in a Card are also cached based on URL. This often causes images to not update when the above Card refresh technique is used.
To work-around this issue, you can add an extra parameter at the end of your image URL so that the Twitterbot treats the image as a unique URL and re-fetches the image.
For example:
Debugging Player Cards
How do I test my Player Card experience?
For the web experience, Twitter relies on the user’s browser to play a wide range of video formats. As a result, it is important to test that your video plays directly in a browser (before testing in the Twitter timeline).
In general, the
twitter:player
tag should have values that can play directly in a browser. (If they don’t, you should consider a different video format that is widely adopted by popular browsers).To test the video content directly, try the following in Google Chrome:
- Open up a browser window
- Enter the URL containing your Twitter Cards tags into the address bar
- View the source of the page (Find this in the toolbar under View->Source or View->Developer->View Source)
- Find and copy the URL specified in the
twitter:player
tag - Paste that into the address of your browser
My Player Card shows summary information instead.
The most common cause of this is that you have not yet been added to an allowlist for approval.
Please run your example URL through the Card Validator, and click the Request Approval button to begin the allowlist process.
After approval, re-try the URL to ensure that the Player Card appears.
My video isn’t playing properly in the Player Card.
There are a number of possible reasons causing this. Here are some suggestions and ways to troubleshoot:
- The URL specified points to a full website, not a page that fits in an IFRAME. The value for
twitter:player
needs to be a simplified web page with only the player on it. Having a full website will show only part of your site in the Player Card IFRAME. - The dimensions of the Player Card aren’t specified. Be sure to include the
twitter:player:height
andtwitter:player:width
tags with your Card tag. - The video format is not supported.
My Player Card does not render properly on mobile.
Txt Profiles
At Twitter, we try to ensure that all content works equally across our web and mobile platforms.
Please read the mobile section of the Player Card page to understand how to make mobile video work for you.
My Player Card is having SSL/mixed content issues. What do I do?
Twitter’s policy around mixed content and SSL security is intended to help protect the safety and security of your audience.
To briefly re-state the policy:
Do not: Generate active mixed content browser warnings at any point during the audio or video experience, either on load or during play.
Here is an example of how to diagnose the active mixed content/SSL issue. When a Player Card is expanded as such:
The browser address bar either maintains the “secure” state (left) or goes into the active mixed content “insecure” state (right).
OK | Not OK |
Below are the steps to reproduce in Google Chrome.
Open a browser window and type in the Twitter URL with the active mixed-content Tweet.
Note that the browser address has the “lock” icon to indicate a secure browsing environment
In the toolbar, click on View->Developer->Developer Tools
In the below pane, click on the Network tab.
Under the Tweet, click on the “View Media” link to expand the Twitter Card
Txt Twitter
If the “lock” icon is intact, you’ve maintained a secure browsing environment
Txt Twitter Bighit
If the “lock” icon is replaced with an “unlocked icon”, you’ve maintained a secure but passive mixed content environment
If the “lock” icon is covered with a red ‘X’, the active mixed-content/SSL issue is present. Player Cards that exemplify this state will not be approved.
- In the Network pane, click on the error icon () to show script load errors.
- In the Network pane, look for scripts or content that shows a warning icon with the message XXX
- These scripts are breaching the security of the Card, and need to be turned to HTTPS
For reference, below is an image of an HTTPS error appearing in the Developer Tools -> Network tab.
In many cases, you can work with your video content provider to resolve these issues. Please contact them first to see how they can re-configure your content.
Debugging App Cards
For App Cards or App Deep Link code, users often see that the Card fails to render when tweeted. Here are some possible reasons and solutions.
- The URL with the Card has not been validated via the Validator. Be sure to test/validate your Card here.
- The image you uploaded to the Apple App Store is larger than 5MB. This will prevent the validator from properly validating your Card. Once validated, it will also prevent your Tweet from rendering a Card. You will need to upload a smaller image to Apple (and possibly re-submit your app to the App Store for approval.)