Embed via JavaScript

Iframely hosts embed.js JavaScript library. It can 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 smart 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.

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 (and don't add &omit_script=1 among parameters): it will be included into the HTML output as required.

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

    <script async charset="utf-8"
        src="//cdn.iframe.ly/embed.js?api_key=..." 
    ></script>
  • The query string params in the script's src must either contain api_key or its MD5 hash value as key parameter (secure hashed value is recommended for production use). See how to secure your API key.

  • You can also include additional params available for API calls. See the list. There is no need to indicate SSL or HTML5 requirements - embed.js will detect these itself.

  • 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.

Define which URLs to unfurl

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

    <a href="http://urltoembed.here" data-iframely-url></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.

Optionally hide failed embeds

It may occur that original link is no longer available. Say, it was removed from YouTube, or became private on Facebook. Embed.js script will just remove the <a href="...">...</a> link by default.

If you'd rather hide the entire div instead, you can source embed.js with optional &parent=... parameter containing CSS style name of the parent div that need to be hidden:

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

Iframely will recursively find the first parent with such class name and will hide the entire element so that the rest of your page remains tidy.

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

    iframely.load();

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:

    iframely.load(linkElement)
    // linkElement - is <a> with 'href' to be replaced

Or if you don't want to add <a> element - you can specify parent container and URL to embed:

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

Get notified when the height changes

The height of HTML embeds may change, for example when Facebook status is loaded or when user later on expands it to read more of a message.

Add listener for such resize in the following way:

iframely.events.on(‘heightChanged’, function(iframe, oldHeight, newHeight) {
   // your handler here, like
   // adjustScroll(newHeight - oldHeight);
   // iframe is a dom element, heights are numbers
});