Iframely Protocol for Responsive Embeds
Iframely protocol is simple publishing and discovery method for iFrame embedded content that is naturally interpreted into responsive widget embed code by developers of consuming applications.
Content publisher announces what media is available on a web page, in which format and sizes and what are the expected use cases. Content consumer apps selects the widgets that work for the user's environment and presents it to the user. Content is always hosted by a publisher, yet interpreted and presented to user by consumer app.
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 />
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 transforms
<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 fixed-size - 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 fixed- or variable- height iFrames - use
For horizontal iFrames that need to stretch 100% of the width with fixed height, give only
<link rel="iframely app" type="text/html" href="... " media="height: 420"/>
See height events.