Contribute to this guideReport an issue

guideEmbedding Media Resources with oEmbed

This feature was introduced in CKEditor 4.5. It is provided through optional plugins that are not included in the CKEditor 4 presets available from the Download site and need to be added to your custom build with online builder. In order to enable the plugin you need to configure the content provider first.

The optional Media Embed and Semantic Media Embed plugins introduce two new widget types — an embedded media resource and an embedded media resource with a semantic output.

An article with a YouTube video and a tweet embedded

Both widgets allow to embed resources (videos, images, tweets, etc.) hosted by other services (called the “content providers”) in the editor. In order to use the widget, you need to set up the content provider in your editor configuration first. We recommend to use the Iframely proxy service which supports over 1800 content providers such as YouTube, Vimeo, Twitter, Instagram, Imgur, GitHub, or Google Maps.

# Media Embed vs Semantic Media Embed

The difference between Media Embed and Semantic Media Embed is that the first will include the entire HTML needed to display the resource in the data, while the latter will only include an <oembed> tag with the URL to the resource. See the following examples:

Media Embed:

<div data-oembed-url="">
    <blockquote class="twitter-tweet">
        <p>Coding session with <a href="">@fredck</a>, <a href="">@anowodzinski</a> and Mr Carrot. <a href=""></a></p>
        &mdash; Piotrek Koszuliński (@reinmarpl) <a href="">March 4, 2015</a>
    <script async charset="utf-8" src="//"></script>

Semantic Media Embed:


This difference makes the Media Embed plugin perfect for systems where the embedding feature should work out of the box. The Semantic Media Embed plugin is useful for rich content managment systems that store only pure, semantic content ready for further processing. For instance, a CMS may display a different result in desktop browsers, different in mobile ones and different for the print version of a website.

# Configuring the Content Provider

Since CKEditor 4.7 the content provider URL is set to empty by default. The former default URL is still available, although it is recommended to set up an account on the Iframely service for better control over embedded content.

The default CKEditor 4 configuration up till version 4.7 was using an anonymized endpoint provided by Iframely, however, it did not include several features such as Google Maps. It is still possible to use it by setting the CKEDITOR.config.embed_provider in the following way:

config.embed_provider = '//{url}&callback={callback}'

However, for better control of API usage it is recommended to set up an account at Iframely. The free “Developer” tier does not have this restriction.

Iframely can also be configured to be hosted on your server — you can read more about it in the “Self-host Iframely APIs” article.

At the same time both widgets can be easily configured to use another oEmbed provider or custom services.

# Automatic Embedding on Paste

If the optional Auto Embed plugin is enabled, pasting the resource URL directly into the editing area will result in embedding it. By default this feature is configured to work with the Media Embed and Semantic Media Embed plugins.

If you wish to make it work with your custom media embed widget (see Implementing a New Embed Widget), just change the autoEmbed_widget option to point to your widget, for example:

config.autoEmbed_widget = 'customEmbed';

You can test auto embedding in the Embedding Media Resources with oEmbed sample.

# Implementing a New Embed Widget

Both plugins utilize the Embed Base API exposed by the Embed Base plugin which can be used to implement other types of widgets for embedding asynchronously retrieved content.

# Embedding Media Demo

See the working “Embedding Media Resources with oEmbed” sample that showcases the Media Embed and Auto Embed plugins.