Iframely Protocol for Responsive Embeds
Iframely protocol is simple embeds content publishing and discovery method that is naturally interpreted into responsive widget embed code by developers of consuming application.
Content publisher announces what widgets are available on a web page, in which format and which sizes and what are the expected use cases. Content consumer selects the widgets that work for the user's environment and presents it to the user.
Thus, the widgets are always hosted by a publisher, yet interpreted by consumer. This forces parties to put their best effort to collaborate on acceptable user experience for their shared audience.
This is how it works:
- Content Publisher puts available widgets as
<link>tag in the
<head>section of (X)HTML document. Publisher indicates MIME type of a hosted resource, sizing options and what are the expected use cases.
- Consumer selects the widgets that work for the user's environment and app circumstances and presents it to the user.
The protocol references HTML5/CSS3 and will naturally evolve with those standards from a technical standpoint.
This document and changes to it are managed on GitHub.
Publish and Discover Embeds - via
Automatic discovery starts when publisher puts a number of
<link> tags in the
head of their webpage:
<link rel="iframely player" // list of functional use cases type="text/html" // guides to embed as iFrame href="//iframe.ly/bFbn" // with this src media="(min-width:100) and (min-height:100)" // when these sizes are ok title="Open Web FTW!" />
Publisher may specify a number of links, either for various user experience options of the same content, or links for multiple pieces of content on the same page.
Consumer (perhaps with user's explicit choice) selects what link to use, given the other viewers' environment (e.g. device, screen resolutions, etc) and functional context (e.g. "media library", "Feed reader", etc).
Consumer app transofrms
<link> information into embed code, based on MIME
media queries and
The link above will be transformed into
iframe embed code:
<iframe src="//iframe.ly/bFbn" width="100%" height="100%"></iframe>
Quick Example - Coub Viral Videos
<link rel="iframely player" href="https://coub.com/embed/2pc24rpb" type="text/html" title="PARADISE BEACH" media="(aspect-ratio: 1280:720)"/>
Consumer, for example Realtidbits, detects the link, sees that it requires iFrame responsive embed with aspect-ratio of 1280/720.
Consumer generates the following embed code for it (see Creating Intrinsic Ratios for Video by Thierry Koblentz):
<div style="width: 100%; height: 0px; position: relative; padding-bottom: 56%;"> <iframe src="http://coub.com/embed/2pc24rpb" frameborder="0" style="width: 100%; height: 100%; position: absolute;"> </iframe> </div>
Voilà! User sees:
Specify Use Case - in
The supported use cases of a published widget should be listed in
rel attribute, separated by a space, in no specific order.
The initial dictionary of the use cases is listed in Rel Types section and includes:
However, it is fairly straightforward to expand the list. See how to contribute.
Host & Source the Widget - via
href is the actual source of the link is address of the iFrame or script or an image, etc that needs to be added as
src when embedding the widget.
- Only sources with
httpsprotocols are allowed.
hreffor link supports both
httptransport, use opening
//in source value.
hrefcan not be a relative path on a domain. Only absolute paths are accepted.
HTTPS protocol is preferred to ensure maximum distribution for publishers' content, as consumers may opt not to consider HTTP-only embeds.
Choose Embed Method - as MIME
The method that needs to be used for embedding of a widget, is given as MIME type.
text/html indicates that widget needs to be embedded as
Can also be:
See the list of acceptable MIME types and which HTML markup and best practices to use to embed them.
Select Size Options - via
Iframely embeds are expected to be fluid. Widgets should load responsively, and also react to resize event triggers of a browser or app.
media attribute is for any valid CSS3 media query, indicating the sizes of the containers where embed content would fit.
Publishers are encouraged to use as simple media features as possible. Consumer apps would require extensive programming to cover all variety of queries, thus making complex queries a high risks of not being interpreted well and thus reducing distribution of content for publishers.
An example of a simple media query is fixed
aspect-ratio, or anything that relies on
For Non-Responsive - use
sizes attribute can be used instead of
media for fixed-size embeds:
<link rel="iframely thumbnail" sizes="800x600" type="image/png" href="//domain.com/thumbnail.png"/>
See sizes spec on W3C. Please, note that value
sizes attribute is only allowed for
image MIME type.
For Multiple Embeds On The Page - itemize with
Both Publisher and Consumer should assume that there could potentially be a number of Iframely links/widgets on a page.
To distinguish between them, publisher must give separate titles for each one.
logo can have the same title on all pages on your site and be equal to your "Site Name".
However, if the
link represents the same content but with different variations in use case or media sizes,
it is expected that such multiple links would share the same
tittle attribute is omitted, the title should be taken from Open Graph
og:title value or the value of
<title>...</title> HTML tag on the web page.