Iframely API: media 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 <head> section of the page’s HTML to be.
Links are used as raw data which you can use to select and render a media yourself. html field is included as generated responsive embed code based on media.
Example of a link object
{
// SRC of embed. The main attribute
// can be omitted for apps, for example Twitter and Facebook.
"href": "https://player.vimeo.com/video/141567420",
// 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 posts, or elsewhere with very specific HTML codes instead of the iFrames or media files.
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 use-case rels
rel object contains an array of functional and technical use cases about the rich media. You may disable any of those rels in your settings, should it not fit your app.
Possible primary functional rels:
player
A widget with media playback. Like video, audio or slideshow players.
image
Sizeable photo or picture, indicating that this is the main content of a web page. For example, Imgur, 500px or Droplr.
app
General embed code for an app. For example, Twitter statuses, Facebook posts, Instagrams, etc. Usually comes with inline html, but can be an iFrame. Google Maps, for example.
thumbnail
A preview image, usually smaller size, but not guaranteed. We recommend that you do not hot-link third party images on your site. There’s Camo, for example.
reader
Longer-form text or graphical widget intended for reader functionality, e.g. Storify. In chat apps, you may want to show it in a popup dialog.
survey
The widget is a questionnaire, e.g. PollDaddy or Apester
summary
Returned if widget is generated by Iframely as summary card or publisher provide its own articles preview card.
file
Downloadable file. We return this rel for direct links to files, including image files. May come together with reader e.g. for Office Files, PDFs — where Iframely links to doc viewers.
icon
Attribution favicon or glyph. Can be large enough homepage icon for mobile devices.
logo
Logo image is returned mostly for pages with a news article. Use it if you need better attribution.
Information rels
Information rels are used mostly to detail what sort of player is being used.
video, audio, playlist
Represents a general video, auidio or playlist players.
slideshow
Slideshow presentation documents, such as Slideshare and similar.
gifv
That comes with player rel indicates auto-looping and muted video
playerjs
Flags that player emits JavaScript playback events
autoplay
Player starts media playback when it is visible. See Autoplay.
attach
Indicates the attachment media. For use with media cards
3d
Virtual and 3D realities.
Feature-policy
The list of rel may also include the number of feature-policy directives that need to be passed into allow attribute of an iFrame for content to properly work.
Iframely recognizes the following feature-policies:
accelerometer, ambient-light-sensor, autoplay, battery, bluetooth, camera, clipboard-read, clipboard-write, display-capture, document-domain, encrypted-media, execution-while-not-rendered, execution-while-out-of-viewport, fullscreen, gamepad, geolocation, gyroscope, hid, identity-credentials-get, idle-detection, local-fonts, magnetometer, microphone, midi, otp-credentials, payment, picture-in-picture, publickey-credentials-get, screen-wake-lock, serial, speaker-selection, storage-access, usb, web-share, window-management, xr-spatial-tracking.
Technical rels
Iframely also uses supplementary technical rels as the way to flag platform aspects of the media:
ssl
Indicates that embed media is safe to load via HTTPs.
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 script. Facebook embeds are not “inline” for a different reason: the first widget will embed alright, but all the next ones will fail afterward if more of them are added via JavaScript.
MIME types
type suggests a method to render media link as widget. It’s a MIME type, as in expected content-type header of a resource behind href of a link. There are following types:
text/html
Widget needs to be rendered as iframe unless it has html field already.
video/mp4
HTML5 video. Will be rendered with as video.
application/vnd.apple.mpegurl, application/x-mpegURL
Streaming HTMl5 video.
audio/mp3, audio/mpeg, audio/mp4, audio/wav
HTML5 audio. Will be rendered with as audio.
application/javascript
JavaScript widget to source as script (rarely used).
image and image/*
Image to render as img.
Direct links to other binary files (except JavaScript and Flash) will have the file’s original MIME type (e.g. application/pdf). They come with file rel.
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 favouritemax-widthmin-heightmin-widthmax-heightwidthheight
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 link object. The exception is image types: thumbnails, icons and logos (to avoid hot-linking).
If you’d like to generate a responsive embed code yourself based on the raw data, please refer to:
- “Responsive embeds” by Anders M. Andersen / 2011
- Creating Intrinsic Ratios for Video by Thierry Koblentz / 2009