Overview
An embedded Post adds pieces of the global conversation happening on X to your site, content, and commentary. Sites powered by a CMS or custom software can provide deeper integration with X 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
- Define site-level widget options
- Define an embedded Post macro
- Request fallback markup using oEmbed
- Load widget JavaScript using your site’s resource manager
Define site-level theme options
Integrate X widgets, including embedded Posts, with your site’s color scheme by including HTML<meta> elements </web/overview/widgets-webpage-properties> in the <head> section of your webpage. Choose a light or dark color theme for Post text and background and customize the iframe border color by adding new markup to your site templates.
Define site-level widget options
Embedded Posts may contain images, video, link previews, or other Posts in conversations. Your site can specify site-wide preferences for display consistency across all pages, overriding default display options. Adding an embedded Post options section in your CMS administrative interface helps individual publishers set their preferences for Post content display across the entire site.Define an embedded Post macro
A macro added to your site’s editing interface abstracts away the detail of embedding Posts, 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 HTML and JavaScript on a webpage, native views on iOS and Android, or custom elements in AMP or Apple News Format. The simplest macro is a Post URL added to your article content. You may choose to have a more custom macro to capture additional embedded Post options unique to the article display.Request fallback markup using oEmbed
An embedded Post should provide appropriate context when viewed on its own, before additional enhancements provided by X for the current viewer. Request and store HTML markup for the requested Post data by requesting content from the oEmbed API endpoint. Add any custom options passed to your site’s macro, or extracted from the current context, as query parameters in the oEmbed request. A Post ID is preferred over a Post’s web URL: components of the URL such as the associated account’s screen_name may change; the Post 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’selements as described above. The oEmbed response from X’s servers adheres to the oEmbed specification. X’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 thecache_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 the remote-hosted widgets.js in your site’s resource loader whenever your site content includes an Embedded Post or other X widget content. Define a new module definition for the X for Websites JavaScript hosted athttps://platform.x.com/widgets.js. Define a module ID of “twitter-wjs” to uniquely identify the X JavaScript with the common ID used by asynchronous loading snippets — 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 X response.
Sites loading page fragments containing an embedded Post will need to request a scan for embedded Post content by calling the twttr.widgets.load function </web/javascript/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.
Sites calling X JavaScript should setup an asynchronous function queue storing functions to be executed in an array accessible at window.twttr._e. The X asynchronous loading snippet provides setup of a function queue array with new functions queued by passing a function to window.twttr.ready. The X for Websites JavaScript will flush the function queue while first executing its JavaScript.
Export Post content in syndicated formats
A modern news organization may publish alternate versions of its content formatted for Apple News, Facebook Instant Articles, or AMP clients. A Post cited in an article will need to be described in the markup expected by each format.AMP
A Post should be described in an AMP template using the<amp-twitter> custom element.
amp-twitter component’s JavaScript rendering code to the document’s <head> to transform the supplied markup into a rendered embedded Post.
Apple News Format
Describe a Post in your article using the Post component in Apple News Format.Facebook Instant Articles Format
Describe a Post contained in your content with an op-interactive<figure> element.