https://github.com/itteco/iframely
NEW: Iframely now provides oEmbed v1 adapter. You can easily plug your existing code to our new endpoint. See API
Iframely Gateway is powerful self-hosted endpoint, simple API for responsive embed widgets and meta. It returns JSON object with all parsed embed and semantic meta data for the requested URL.
You host the API on your own servers and domain. The primary endpoint is /iframely?uri=:
http://{YOURHOST.HERE}/iframely?uri={url encoded http link to a web page}
(see example)
Iframely provides out-of-the-box:
- Generic parsers of Iframely Protocol, Open Graph, Twitter Cards, oEmbed v1 and optional Readability articles
- More than 100 parsers for specific domains, like YouTube, Vimeo, Soundcloud, Instagram, etc.
- Plugins arсhitecture to extend the logic or to implement additional domain or generic parsers
- Caching for performance optimizations (Memached, Redis or in-memory engines)
- API for unified/merged meta semantics, thumbnails (incl sizes), video, players, articles
Iframely API response mimics the Iframely Protocol For Responsive Embeds. It also merges various meta fields into a list that you could rely on in your code.
Iframely is Node.JS app (and/or package), though you can use it from other environments via API.
(c) 2013 Itteco Software Corp. Licensed under MIT.
You might wish to read Iframely Protocol spec to get a better intro into structure of the API responses and overall concept for responsive embeds.
The custom domain plugins (all 100+ of them) and generic parsers in Iframely gateway convert domains into Iframely Protocol compliant publishers. Iframely gateway acts as the connector with this regard and by the same time is the embeds Consumer app.
Please, head to Iframely Visual Debugger tool to see what Iframely Gateway will be returning.
Once you deploy Iframely to your own servers, you will have your own copy of technical debug tool at /debug address.
You can also get a debugger as Google Chrome extension here.
Important: To jump-start with your dev effort, you may use skip installation and use our community endpoint to rapidly develop against it:
http://iframely.com/iframely?uri={URL encoded URI here}
This endpoint is hosted courtesy of Itteco and has the latest version of Iframely gateway on it. It is subject to restarts and rate-limits and thus is not suitable for production use.
Please deploy Iframely on your own hardware before going live.
In response to /iframely?uri= requests, Iframely will return JSON with the embed links and unified meta semantics.
Response structure is close resemblance of the following analogue of <head> part of the URL's page:
<head>
<meta name="..." value="..."/>
<link rel="iframely player" href="..." type="text/html" media="aspect-ratio: 1.778" title="...">
</head>
JSON response will have the following format:
{
"meta": { -- meta object with the unified semantics
"title": "BLACK&BLUE", -- e.g. title and others
...
},
"links": [ -- List of embed widgets
{
"href": "//player.vimeo.com/video/67452063", -- SRC of embed.
"type": "text/html", -- MIME type of embed method.
"rel": [ -- List of functional use cases. For example,
"player" -- `player` - is widget with media playback
],
"title": "BLACK&BLUE", -- different titles, for different content on the page
"media": { -- "media query" semantics to indicate responsive sizes
"aspect-ratio": 1.778 -- e.g. fluid widget with fixed aspect ratio
}
},
...
]
}
You can use included iframely.js jQuery library to communicate with Iframely API and to render the embeds.
It wraps Iframely API and includes responsive trick and best practices mentioned in Iframely Protocol.
For dev effort, you can source it from http://iframely.com/r3/js/iframely.js (again, not production-ready).
To get a copy of Iframely, you have three options:
- Download the latest release.
- Install via NPM:
npm install iframely. - Clone the repo:
git clone git://github.com/itteco/iframely.git.
We recommend hosting it on a separate domain for CORS security of your main app.
Read Setup and Configuration Instructions
Itteco provides Whitelist DB - the first independently run embeds QA service.
We cover Iframely Protocol, oEmbed v1, Twitter Cards and Open Graph in our test runs.
There are technical/security considerations that can be resolved algorithmically, but it really requires a human eye to check if the user experience of the embeds can be relied on.
The whitelist is a JSON file with the list of domains and ok or reject tags for each protocol.
The whitelist support is already included into Gateway. Just upload the latest whitelist file to the root of your Iframely server. See setup instructions.
Itteco has developed couple demo services based on Iframely technology (well, it was more "in parrallel with", actually):
- Iframe.ly - the web shortener
- Nowork FM - simple intranet for your team
- Iframely for Gmail - watch videos, view photos and read articles in your inbox.
Feel free to try it to get an inspiration and idea of the possibilities.
We put our best effort to maintain Iframely and all its domain parsers. Please, feel free to reach us on Twitter or to submit an issue if you have any suggestions.
Fork and do a pull-request, if you'de like to add more plugins and/or contribute fixes or improvements. By doing so, you make your work available under the same MIT license.
If you are a publisher and would like to make your embeds available under Iframely Protocol (and thus distributed through this open-source gateway) - please, add your domain to the whitelist.
We encourage you to help other folks get up to speed with Iframely by following community channels:
- Business questions and answers are handled via Iframely topic on Quora
- Technical Q&A - iframely tag on StackOverflow
- News & Experiences. #iframely or @iframely on Twitter
The authors and maintainers of the package are these guys from Itteco:
- Nazar Leush - the author
- Ivan Paramonau - coffee, donuts & inspiration
Please, check the contributors list to get to know awesome folks that also helped a lot.