Overview
Embedded
Tweets make it possible for you take any Tweet and embed it directly in
to the content of your article or website. Tweets display with expanded
media like photos, videos, and article summaries, and also include
real-time retweet and favorite counts. When embedded, Tweets are
interactive and enable your readers to follow the Tweet author, and
reply, retweet, favorite all directly from the page.
This document
explains how to use Embedded Tweets on your website, and also how
developers can integrate Embedded Tweets in to their applications
through our API. Here’s an example:
How to Embed a Tweet on your Website
Every
Tweet on twitter.com and TweetDeck has a set of Tweet actions at the
bottom, including Reply, Retweet, Favorite, and More. Click the “More”
Tweet action and select “Embed Tweet”:
A
dialog will appear providing you with an HTML embed code. Copy and
paste this directly into your article where you’d like the Tweet to
appear. There’s a preview which shows you how the Tweet will look.
If
the Tweet is a reply, you’ll be given a checkbox inside the embed
dialog that allows you to exclude the rest of the conversation.
Controlling Tweet Display
By
default, embedded Tweets will render in full, similar to how they do on
a twitter.com permalink page. There are a few settings you can change
to ensure they fit well within your content. For example, if you are
collecting Tweets from a conversation and don’t want the thread attached
to every Tweet, you can hide the conversation using the
data-conversation attribute:
<blockquote class="twitter-tweet"
data-conversation="none">
...
</blockquote>
|
This is equivalent to unchecking the “Include parent Tweet” option in the twitter.com embed code dialog.
Also, when embedding many Tweets that link to the same content you might find some
cards to be redundant. You can hide the card in an embedded Tweet using the
data-cards attribute:
<blockquote class="twitter-tweet"
data-cards="hidden">
...
</blockquote>
|
Width and Height of Embedded Tweets
Height
is variable based on the content in the Tweet, and may change slightly
over time. Tweets will render at a default width of 500px, but if the
page section they are pasted into is smaller they will adjust
accordingly. Width is responsive to changes in container size.
You may override the default width of the embedded Tweet by adding a
width attribute to the embed code, like so:
<blockquote class="twitter-tweet"
width="350">
...
</blockquote>
|
Alignment
By
default, Tweets render as a standalone block of content. Alignment and
floating of the Tweet can be set manually by using the
align attribute on the blockquote element of the embed code. Add
align="left",
align="right" or
align="center" to position the Tweet in your content. For example:
<blockquote class="twitter-tweet"
align="left">
...
</blockquote>
|
Theme and Color
By default, Tweets render links in the standard blue used by twitter.com. This can be overridden in two ways.
1. On individual embedded Tweet codes, the
data-link-color attribute sets link color (e.g.
data-link-color="#cc0000". Embedded Tweets also support a
TweetDeck-style design via the
data-theme attribute.
<blockquote class="twitter-tweet"
data-link-color="#cc0000"
data-theme="dark">
...
</blockquote>
|
Adding attributes to many embedded Tweet codes is laborious, so the link color and theme for
all embedded Tweet and
Embedded Timeline widgets can be set globally using
<meta> elements:
<meta name="twitter:widgets:link-color" content="#cc0000">
<meta name="twitter:widgets:theme" content="dark">
|
Twitter Headlines
Twitter
Headlines is a feature that connects articles about the Tweet with the
Tweet itself. When an approved publisher embeds Tweets in their content,
the headline of the article and Twitter account is surfaced on the
Tweet’s permalink page for all to see.
Here is a recent
blog post surrounding the launch of Twitter Headlines. If you would like your
site to be considered for the program, please submit an application
using
this form.
If you have already been approved for Headlines, you can control the attribution for your site by using
twitter:site to specify your @account. For example:
<meta name="twitter:site" content="@twitterapi">
|
Twitter will use the canonical URL on the page if present. For example:
Embedding from WordPress and other CMSs
Some
content management systems such as WordPress have created an optimized
workflow for embedding Tweets. In WordPress you can simply copy the URL
for a Tweet and paste it on a single line in your post. WordPress will
do the rest of the work to insert the proper embed code and make the
Tweet appear in your content. For example:
https://twitter.com/BarackObama/status/266031293945503744To add this behavior to your CMS, read the section below on Embedded Tweets for Developers.
Troubleshooting
If your embedded Tweets aren’t showing up in your page, there are a few things you can try.
Firstly, always remember that embedded Tweets require the
<script> tag from the embed code to run to fully render the Tweet. Sometimes, a CMS may not properly format the
<script> in your published articles, or may strip it out altogether. Here are ways to resolve that:
- If
your CMS has an ‘HTML’ or ‘code editing’ mode, use that. Often,
rich-text or WYSIWYG editors will misinterpret pasted code and may
remove data or try to display it in your page literally. Try entering
the code in HTML mode, pasting the code directly there, and then
publishing your post.
- If you cannot reliably work with HTML in your articles, then you or your website team should instead add a single
<script> to your main website template. In your template, find the end of the page, the closing </body> tag, and add the following code before it.
<script>!function(d,s,id){var
js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+"://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
|
will include the initialization code for embedded Tweets separate of
your CMS content editor, and you will be able to use embedded Tweets in
any page of your site without further modification.
- If these problems do not resolve your issue, please let us know in the Developer Forums,
where we can try to understand the problem, and where we can confirm
that our embedded Tweets service is running at full availability.
Language
Embedded Tweets infer their language from the HTML page in which they are embedded, using the standard HTML
lang attribute. For example:
All Tweets on that page will be rendered in Spanish. As per HTML, the closest parent lang tag is applied to the widget. e.g.
<html lang="en">
<head></head>
<body>
<article lang="fr">
<blockquote class="twitter-tweet" />
|
You can also place an explicit lang attribute on the embed code element itself. For example:
Note
that pages without a declared language will default to English. Setting
a language will translate the date, social counts, Tweet actions, and
Follow button, but not the Tweet text.
Embedded Tweets for Developers
While
the copy and paste code is useful for content authors, some
applications may wish to render these embedded Tweets programmatically.
Fortunately, Twitter now supports an
oEmbed endpoint which makes this possible.
To render a Tweet using oEmbed, the embedding site must:
- Obtain an URL to or ID number of the Tweet it wants to render.
- Make a request to the GET statuses/oembed endpoint, passing the Tweet URL or ID as a query parameter.
Editing systems can also find the API URL for a Tweet using oEmbed auto-discovery, by parsing the
of the permalink page. Refer to the
oEmbed Discovery documentation for more information.
The
oEmbed standard allows a website to embed a representation of the
contents of an URL into its own markup. The specification supports
representing an URL as an image, a video, or even a snippet of rich HTML
content. Twitter’s implementation uses the rich HTML functionality to
render a widget view of a Tweet.
Obtaining an URL to a Tweet and
requesting Twitter’s oEmbed endpoint are straightforward. Your code must
pass either an ID or URL for the Tweet it wishes to embed to
GET statuses/oembed,
along with any additional querystring parameters it needs to render the
Tweet appropriately. The response will encode enough data to embed the
Tweet. For example, the response to
https://api.twitter.com/1/statuses/oembed.json?id=133640144317198338&align=center is:
{
"type": "rich",
"author_name": "Twitter API",
"cache_age": "31536000000",
"height": null,
"html": "<blockquote
class=\"twitter-tweet tw-align-center\"><p>Search API will now
always return \"real\" Twitter user IDs. The with_twitter_user_id
parameter is no longer necessary. An era has ended.
^TS</p>— Twitter API (@twitterapi) <a href=\"https://twitter.com/twitterapi/status/133640144317198338\"
data-datetime=\"2011-11-07T20:21:07+00:00\">November7,
2011</a></blockquote>\n<script
src=\"//platform.twitter.com/widgets.js\"
charset=\"utf-8\"></script>", "provider_name": "Twitter",
"version": "1.0",
"width": 550
}
|
and use the cached data instead of making a request per page load.
The response contains HTML markup which, when rendered along with the
//platform.twitter.com/widgets.js script, will produce the embedded Tweet widget in your website. To do this, output the
html portion of the response into your site template. If you are using a
templating library, make sure to disable HTML entity encoding and
sanitization for this piece of output, or else the HTML may not render
correctly.
widgets.js
The HTML content from the copy & paste dialog or the oEmbed endpoint contains a
<script> tag pointing to
widgets.js. For example, from
https://api.twitter.com/1/statuses/oembed.json?id=133640144317198338
<blockquote class="twitter-tweet"><p>Search
API will now always return "real" Twitter user IDs. The
with_twitter_user_id parameter is no longer necessary. An era has ended.
^TS</p>— Twitter API (@twitterapi) <a href="https://twitter.com/twitterapi/status/133640144317198338" data-datetime="2011-11-07T20:21:07+00:00">November 7, 2011</a></blockquote><script src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
|
Only one copy of
widgets.js needs to be included per rendered page. If you already include a copy
(for a Tweet button, for example) or need to render more than one Tweet,
you can opt to remove the script reference from the oEmbed response by
including the
omit_script=true querystring parameter. The example URL becomes
https://api.twitter.com/1/statuses/oembed.json?id=133640144317198338&omit_script=true, with the following response:
<blockquote class="twitter-tweet"><p>Search
API will now always return "real" Twitter user IDs. The
with_twitter_user_id parameter is no longer necessary. An era has ended.
^TS</p>— Twitter API (@twitterapi) <a href="https://twitter.com/twitterapi/status/133640144317198338" data-datetime="2011-11-07T20:21:07+00:00">November 7, 2011</a></blockquote> |
To remove the script reference from the copy & paste code, just delete the <script> tag by hand.
Considerations for Mobile Websites
Many
websites offer mobile versions of their content. There’s a couple
things to consider when developing for mobile with Embedded Tweets:
- Make sure to include widgets.js in your mobile template in addition to your standard website template.
- Embedded
Tweets are responsive, and adapt to the size of the container that
they’re placed in. That means they’ll look great on desktop, and on your
narrower mobile web version without you needing to do any work.
Rendering a Tweet
The
placeholder HTML has the benefit of still containing Tweet content even
in cases where JavaScript is unavailable. This means that in RSS feeds,
web crawlers, and accessibility tools the Tweet content is still part
of your page. In this case, your website’s regular quote styling is
applied, for example:
Most users will have Javascript enabled, though. They will see the fully rendered embedded Tweet, which contains
Web Intents which enable taking actions such as replying, retweeting, and following directly from the embedded Tweet:
Best practices
Cache the oEmbed response on your server. The oEmbed endpoint is rate-limited, so make sure you are not fetching it for every pageview you render.
Assume the embed HTML format will change. The HTML markup for the embed may change over time, so don’t assume
classnames or the DOM layout will stay the same. If you need to style
the embedded HTML, wrap it in a parent element and style the parent.
Opt-out of tailoring Twitter
Twitter
widgets on your site can help us tailor content and suggestions for
Twitter users. If you want to opt-out of this feature, set the optional
data-dnt parameter to be
true.
Learn more about tailoring Twitter.
<blockquote class="twitter-tweet" data-dnt="true">
|
(6). For privacy reasons, the list
