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. You can disable specific use-case rels in your API settings.

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 A 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.
app General extract for an app. For example, Twitter statuses, Facebook posts, Instagrams, etc. Often comes with inline html, but can be an iFrame, for example for Google Maps.
thumbnail The preview image, usually smaller size
reader Longer-form text or graphical widget intended for reader functionality, e.g. Storify
survey The widget is a questionnaire, e.g. PollDaddy or Apester
summary Returned if widget is generated by Iframely as summary card and for Medium article previous.
file Downloadable file. We return this rel for all direct links to files, including image files. Often comes with reader e.g. for Office Files, PDFs - where Iframely links to doc viewers.
icon Attribution favicon or glyph
logo Logo the source site. Is returned mostly for pages with the news article (custom ones) for better attribution.

Supplementary information rels:


gifv That comes with player rel indicates auto-looping and muted video
playerjs Flags that player emits JavaScript playback events
autoplay Indicates the attachment media. For use with promo cards
promo Player starts media playback when it loads

Technical Rels

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

ssl Indicates that embed media can be loaded via HTTPs
html5 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.

For example, GitHub Gists are not inline as they rely on synchronous document.write, whereas Facebook embeds are not "inline" for different reason: the first widget will embed alright, but all the next ones will fail afterward if added via JavaScript.

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 unless it has html field already
application/javascript JavaScript widget with dynamic page embedding with as script
application/x-shockwave-flash Flash, we suggest to render with embed.
video/mp4 HTML5 video. Will be rendered with as video.
image and image/* Image to render as img.

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. If there is just the height attribute for text\html - stretch iFrame to 100% width.

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: