Skip to content

Latest commit

 

History

History
107 lines (68 loc) · 5.43 KB

LINKS.md

File metadata and controls

107 lines (68 loc) · 5.43 KB

Iframely API: Embed Links

links in Iframely API is the list of objects with fields rel, href, type and media. Just like you would expect a <link> in <html> <head> of the page to be.

Links are used as the raw data which you can use to select a widget. html field is there as the generated responsive embed code.

Example of a link object:

{
	// SRC of embed. The main attribute
	"href": "//coub.com/embed/2pc24rpb",

	// functional and technical use cases.
	"rel": ["player", "autoplay", "html5"],

	// MIME type. Tells: "embed as iFrame"
	"type": "text/html",

	"media": {	// Media query. Mostly responsive
		"aspect-ratio": 1.777778
	},

	// plus generated or native HTML code:
	"html": "<div ..></div>"
 }

At times, Iframely will return html attribute without href. For example, for Twitter and Facebook Statuses, or elsewhere with very specific embed codes.

Also, Iframely does not generate html field for image/* MIME types.

Below is the list of possible rel values as well as information about media queries.

Functional Rels

rel object contains an array of functional and technical use cases. You may decide which link works better for the use of your app.

Possible primary rels:

  • player - widget with media playback. Like video or music or slideshow players;
  • image - sizeable photo or picture, indicating that this is the main content on the web page. For use in e.g. photo albums "details" page;
  • app - general extract for an app. For example, Twitter statuses, Facebook posts, Instagrams, etc;
  • thumbnail - the preview image, usually smaller size;
  • reader - text or graphical widget intended for reader functionality (e.g. article);
  • survey - the widget is a questionnaire;
  • product - the widget with the product information, usually has the "buy" link;
  • summary - this rel is returned if widget is generated by Iframely as summary card;
  • file - downloadable file. We return this rel for all direct links to files, including image files;
  • icon - attribution favicon or glyph;
  • logo - logo the source site. Is returned mostly for pages with the news article (custom ones) for better attribution.

See some widget samples. If embed was generated by Iframely via URL Shortener as a summary card, the rel will be summary. If media embed was attached to URL from other provider (for example, player is embedded on that page), the rel array will contain promo.

Technical Rels

Iframely also uses supplementary rels as the way to suggest technical aspects of the media:

  • autoplay - if player starts media playback on its load;
  • ssl flag indicates that embed media can be loaded via HTTPs;
  • html5 - if player is capable of HTML5 playback and will render ok on devices without Flash installed (for example, iOS);
  • inline - for app indicates that embed widgets can be dynamically added to the page via JavaScript (e.g. doesn’t use document.write). Usually goes along with html field instead of href and indicates that html should be used as srcdoc of an <iframe> (as substitute to href as src).
  • gifv - indicates that player represents a gif converted to MP4 and needs to be embedded as looping muted video.

These technical rels are result of our manual QA of the domains and are taken from our Domains DB (and therefore can change over time). For example, GitHub Gists were not inline the last time we checked.

MIME Types

MIME type defines a suggested method to render link as widget. MIME type is an expected HTTP response content-type header of a resource behind href of a link. Type of content defines the rendering method.

There are following types at the moment:

  • text/html - widget needs to be rendered as <iframe>.
  • application/javascript - JavaScript widget with dynamic page embedding with as <script>.
  • application/x-shockwave-flash - Flash widget, we suggest to render with <embed>.
  • video/mp4 - HTML5 video. Will be rendered with as <video>.
  • image and detailed image/* - this is image which will be rendered with as <img>. The detailed image type may be useful, for example, to detect GIFs.

Sizes in Media Query

media section is for media query. Iframely generates query’s attributes as well as puts it into usable JSON.

Iframely outputs the following media query attributes at the moment:

  • aspect-ratio - by far our favourite
  • max-width
  • min-height
  • min-width
  • max-height
  • width
  • height

For example, for image rel, Iframely will output exact sizes as width and height in media object.

About responsive HTML code generation

The responsive HTML code for links will be generated by API on the server and added to the link object. The exception is the complementary thumbnails, icons and logos.

If you’d like to generate a responsive embed code yourself based on the raw data, please refer to: