Embed via JavaScript

Iframely hosts embed.js JavaScript library that works in orchestrations with Iframely-hosted iFrames. By default, it is included into HTML codes from API responses when required.

But library can also be used to unfurl URLs on your page without making API requests first. Basically, you skip the step of getting HTML from our cloud and use pre-programmed HTML codes instead.

The embeds loaded this way:

  • Always use hosted iFrames as rendering engine (or switch to Web Components in browsers that support it).
  • Do not require you to cache embed codes - embed.js is always up-to-date.
  • Will follow your current API settings, for example render cards or click-to-play, if allowed.

If you get HTML codes via APIs, or need more flexibility, head to oEmbed API or Iframely API descriptions. However, you still may use event hooks that embed.js script provides.

Add embed.js to your page

Heads up: you don't need to handle embed.js yourself if you get HTML codes via API calls (except when you &omit_script=true): it will be included into the HTML output when required.

To load embed.js on your own, simply add:

<script async charset="utf-8"
  • src must either contain api_key or its MD5 hash value as key in query-string parameters (securing API key via hashed value is recommended for production use).

  • But you don't need api_key in script's src if you get your HTML codes from Iframely APIs - the key will already be included when required.

  • You can fine-tune via query-string params available for regular API calls. See the list.

  • To load embed.js script conditionally, only when there are embeds on your page, please copy-paste this example gist.

  • If you use custom CDN option - please, source embed.js script from your own domain name.

You may also opt to self-host embed.js script. It is available on GitHub and NPM.

Unfurl URLs if you don't wish to make API calls

Using embed.js directly allows you to skip getting HTML embed codes from APIs first. You can simply use the same template for all links, and let embed.js handle the rest.

To let Iframely's embed.js know which URLs to embed, simply wrap links into Iframely divs and add empty data-iframely-url attribute to your links:

 <div class="iframely-embed">
   <div class="iframely-responsive">
     <a data-iframely-url href="http://urltoembed.here"></a>

Embed.js will replace all such URLs with embedded iFrame once loaded. It will take href attribute value of the link as the URL to unfurl.

You may add Iframely styles to your page yourself as described in our omit-css doc. It helps embeds reserve better space in DOM even before embed.js script is loaded. Also, it lets you fine-tune styles if need be. Otherwise, our embed.js script will add missing default class definitions itself.

Even though pre-programmed embed templates are simpler, the HTML codes that you get from our cloud will be better optimized for each specific URL, including correct initial sizing and your other loading preferences.

If you add links dynamically, say, in a chat application, you can call embed.js renders explicitly for newly added links by calling:


It will fetch the list of missing links and unfurl it. Or you can tell Iframely exactly which <a> element to replace with embedded iFrame:

// linkElement - is <a> with 'href' to be replaced

Or you can just specify parent container and URL to embed:

iframely.load(containerElement, 'http://yoururl.here');

Act on failed embeds

It may occur that original link or rich media is no longer available. Say, it was removed from YouTube, became private on Facebook, or you changed your API settings and don't allow that media type any longer.

Embed.js will automatically remove such failed rich media on its own.

If you have your own container for rich media attachment, you can hide the entire block. Simply source embed.js with optional &parent=... parameter containing CSS style name of the parent container:

<script src="//cdn.iframe.ly/embed.js?api_key=...&parent=yourclassname" 
async charset="utf-8"></script>

Iframely will find the first parent element with such class name and will hide it, leaving the rest of your page tidy.

Alternatively, you can add your custom logic when rich media is no longer available:

iframely.on('cancel', function(url, parentNode) {
    // `url` - the original URL to rich media
    // `parentNode` - container of the deleted rich media

    // ... E.g.: send a notification to your CMS to remove URL
    // ... or restore simple link so users can click on it

Analytics events

At the moment, embed.js supports only one highly-requested event - when a user clicks on Iframely summary cards:

iframely.on('click', function(href) {
    // ... for example, call Google Analytics 
          ga('send', 'event', {
            eventCategory: 'URL preview',
            eventAction: 'click',
            eventLabel: href

We have more events coming. If you'd like your voice heard - connect with us at support@iframely.com

URL options events

If you use Iframely in text editor, Iframes that are sourced with Content IDs will declare options for a URL they represent. Use options to build a customization form for that URL in your text editor. After user chooses his preferred options, send them to Iframely as additional API query-string parameters for that URL.

iframely.on('options', function(widget, options) {
    // ... 
    // use our options.js to build 
    // the options form for your text editor

Read more about URL Options.

Previous article: Result codes
Next article: Hosted iFrames