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.
Iframely protocol focuses solely on media and User Experience. Unlike oEmbed, Open Graph or Twitter Cards or Micro Formats, Iframely protocol does not cover semantic meta data.
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.
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 type, media queries and href source.
The link above will be transformed into iframe embed code:
<iframe src="//iframe.ly/bFbn" width="100%" height="100%"></iframe>
Quick example. Publisher, for example Coub adds the following player link to the head of web page:
<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:
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:
iframelyplayerreaderimagesurveythumbnailiconlogo
However, it is fairly straightforward to expand the list. See how to contribute.
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
httpandhttpsprotocols are allowed. - If
hreffor link supports bothhttpsandhttptransport, 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.
The method that needs to be used for embedding of a widget, is given as MIME type.
For example, text/html indicates that widget needs to be embedded as <iframe>.
Can also be:
javascriptimagevideoandaudioembeds.
See the list of acceptable MIME types and which HTML markup and best practices to use to embed them.
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 min- and max- of height and width:
media="(aspect-ratio: 4:3)"
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 any of sizes attribute is only allowed for image MIME type.
For horizontal iFrames that need to stretch 100% of the width with fixed height, give only height as media:
<link rel="iframely app" type="text/html" href="... " media="height: 420"/>
When height is can not be known in advance, for example due to text overflows that depend on user's viewport, there's a simple JavaScripts event flow that both publisher and consumer should implement to communicate height changes and adjust widget accordingly.
See height events.
Iframely Protocol by Itteco is licensed under a Creative Commons Attribution 3.0 License.
