Get started with Iframely

If you know where you are heading to, use links to the left. Otherwise, read on. This quick intro gives the same links, but put in proper context.

What Iframely APIs do

Iframely APIs will take your URL and try to find rich media embed codes and unified meta semantics for it. Embed codes, native or Iframely-hosted iFrames, will be responsive if possible. You can see responses from Iframely via API explorer.

Is there a way to use embeds without learning APIs?

You can use embed.js library to use embeds without making API calls, just by changing HTML a little on your page. If you need more control, connect to APIs.

There is a number of Iframely integrations available: WordPress plugin, Meteor package, Medium-like text editor add-on, CKEditor supports Iframely, NodeBB forums, to mention a few. There are also guides for ReactJS and AngularJS.

API formats and endpoints

There are (just) two endpoints available: one works with JSON in oEmbed format, another one - in Iframely format.

oEmbed API is great for simple embedding. Iframely API adds semantic meta and detailed embeds data. For example,ssl, html5, autoplay flags.

How to render an embed

In a simple scenario, you'll just use the html field of the API response. Depending on your API settings, HTML may contain native embed code from the publisher as is, our use display proxy via our smart iFrames, short URLs or summary cards.

The cards design, if allowed for general links, uses your cards settings.

How do I get other features?

All features are delivered via oEmbed or Iframely endpoints but with specific optional query string parameters and/or your API settings. For example,

  • use smart iFrames and short URLs via &iframe=true parameter,
  • use AMP compatible format with &iframe=amp parameter,
  • use promo API and get promo cards HTML codes by adding &promo=... parameter with 3rd party media you want to attach to your card.

The exact set depends on your system, of course. Parameters and settings can re-format the HTML you get. Due to legacy issues, most improvements and new features arrive as new parameters and settings.

If we were to develop our own client application that relies on Iframely API, we'd use it with &omit_css so that embeds take the correct place on the screen right away, with lazy-loading activated for players in the settings, and, if course with smart iFrames always on.

What URLs to send to Iframely

We know rich media for over 1800 domains, plus can generate cards as URL preview for most other public sites. So, we'd say, send us all URLs you have. We suggest that you white-list not the specific providers, but rather specific widget types. Read more about it.

Should API usage be a concern, you can opt to skip URLs if Iframely couldn't find embed that meets your criteria. You'll get result code 417 in such cases. See error handling.

Should I cache embed codes?

Yes, generally you do. Providers change their embed codes, videos get removed, we add new providers, etc.

But if you use our embed.js or our iFrames with lazy-loading, the embeds will keep updating by themselves in the background. If you use iFrames without embed.js script - you should be fairly safe too, except we won't be able to remove a no longer available video from your page.

If you use native embed codes from the publisher, you would need to make a decision about caching on your own. The trigger can be either your own time-to-live settings, or a user event, such as page view. We recommend cache time-to-live value of 1 day. Iframely on its part uses heuristic algorithm that re-checks fresh URLs more often than the older ones.

Promo Cards

Promo API lets you generate promo cards and become embeds publisher. It is a great way to promote your site and drive traffic. You can integrate it easily with the help of Embed Dialog for your site.

Basically, you just attach rich media to your own URLs. Check out our Klip To app for a demo.