Overview
An Embedded Tweets adds pieces of the global conversation happening on Twitter to your site, content, and commentary. Sites powered by a CMS or custom software can provide deeper integration with Twitter content through site-level display preferences, content macros for cross-platform publishing, oEmbed fallback content, and JavaScript loaders described in this guide. Your extra effort will remove barriers between authors and cited content while integrating our third-party content with your site's content flows and visual design.
Define site-level theme options
Integrate Twitter widgets, including Embedded Tweets, with your site's color scheme by including HTML <meta> elements in the <head> section of your webpage. Choose a light or dark color theme for Tweet text and background, customize the anchor text color, and customize the iframe border color by adding new markup across your site.
<meta name="twitter:widgets:theme" content="light"><meta name="twitter:widgets:link-color" content="#55acee"><meta name="twitter:widgets:border-color" content="#55acee">
Twitter's JavaScript code reads the meta values on the page before constructing a new widget; these values may be overridden at the individual widget level by passing the appropriate oEmbed parameter.
Adding a Twitter widget options section in your CMS administrative interface helps individual publishers customize content without editing theme files.
Define site-level widget options
Embedded Tweets may contain images, video, link previews, or cite previous Tweets in a conversation thread. Your site may want to specify site-level embed preferences for visual consistency across all pages, overriding Twitter's default display options.
Images and video displayed alongside a Tweet may not be appropriate for all audiences. A Tweet displayed without expanded content offers a more predictable height for publishers interested in a well-defined display area.
Adding an Embedded Tweet options section in your CMS administrative interface helps individual publishers set their preferences for Tweet content display across the entire site.
Define an Embedded Tweet macro
A macro added to your site's editing interface abstracts away the implementation details of individual features, allowing an author to focus on content. Behind-the-scenes your macro should determine the best content to display in the current rendering environment, such as plain text in an email, a Tweet without attached photos on mobile, or a JavaScript-enhanced Tweet in a desktop browser.
[tweet id="20" align="right"]
A macro should also be aware of the current context of the page, passing related Twitter accounts or the language of the page content where appropriate.
Verify macro inputs against a set of known Embedded Tweet parameters before passing the option to the Twitter oEmbed endpoint to set author expectations and remove unneeded cruft.
Store a Twitter OAuth bearer token
Requests to Twitter's REST API services should include a Application-only authentication to identify your website as a known Twitter application. Create a Twitter application and exchange your application identifier and secret for a bearer token for use in future requests to Twitter's REST API.
You may wish to abstract calls to Twitter's APIs into separate libraries within your application to handle adding required HTTP headers to the request, handling common errors, and preparing JSON or XML responses for use by other parts of your application.
Request fallback markup using oEmbed
An Embedded Tweet should provide appropriate context when viewed on its own, before additional enhancements provided by Twitter for the current viewer. Request and store HTML markup for the requested Tweet data by requesting content from GET statuses/oembed. Add any custom options passed to your site's macro, or extracted from the current context, as query parameters in the oEmbed request.
A Tweet ID is preferred over a Tweet's web URL: components of the URL such as the associated account's screen_name may change; the Tweet ID is unique to the cited content and will remain the same.
You may choose to omit theme-related options from oEmbed requests if you define these preferences inside your webpage’s elements as described above.
The oEmbed response from Twitter’s servers adheres to the oEmbed specification. Twitter’s oEmbed response is a "rich" oEmbed type containing HTML markup suitable for use inside existing HTML code.
Sites should cache the HTML returned by the oEmbed API for the suggested cache lifetime specified by the cache_age response parameter. Your cache method should incorporate the customization parameters passed to the oEmbed API as these parameters will modify the HTML response.
Load widget JavaScript using your site's resource manager
Many sites, frameworks, and CMS systems have specialized CSS and JavaScript resource managers or module loaders tracking dependencies, asynchronous loading, and versioning. Include Twitter's remote-hosted widget.js in your site's resource loader whenever your site content includes an Embedded Tweet or other Twitter widget content.
Define a new module definition for Twitter's widget JavaScript hosted at https://platform.twitter.com/widgets.js. Define a module ID of "twitter-wjs" to uniquely identify Twitter's widget JavaScript using the common DOM ID used by Set-up Twitter for Websites just in case copy-and-pasted JavaScript makes its way onto the webpage.
Include an omit_script=true parameter in your oEmbed request to strip JavaScript from the Twitter response.
Sites loading page fragments containing an Embedded Tweet will need to request a scan for Embedded Tweet content by Scripting: Loading and Initialization after the new content is inserted into the page. Pass one or more DOM elements to the load function to restrict the scan for new content to just the new page fragments to improve site performance.