Embedded Media Providers
A guide to creating a custom embed providers in Umbraco
The Rich Text Editor in Umbraco has an 'Embed' button, that when pressed, slides open a panel. This panel enables editors to paste the URL of a third-party media resource to embed in content.
![](https://docs.umbraco.com/~gitbook/image?url=https%3A%2F%2F2945122355-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FmmtM2UdX1OOMSi0CksPv%252Fuploads%252Fgit-blob-82a0371675a210db176379c8565db730c83b594a%252FEmbed-Button.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=bc7568aa&sv=1)
For example, a YouTube Video...
![](https://docs.umbraco.com/~gitbook/image?url=https%3A%2F%2F2945122355-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FmmtM2UdX1OOMSi0CksPv%252Fuploads%252Fgit-blob-558fd5b631acce84bad1a1c4eb4622e892bc061e%252FEmbed-YouTube.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=e7b1800&sv=1)
The task of an EmbedProvider
is to accept the pasted URL and write out the appropriate markup for the third-party provider associated with the URL.
Embed Provider Configuration
Embed Providers are registered with the EmbedProvidersCollection
during Composition when Umbraco boots.
The list of available default Embed Providers in an Umbraco install are as follows:
YouTube
YouTube Shorts
Twitter
Vimeo
Dailymotion
Flickr
SlideShare
Kickstarter
Getty Images
Ted
SoundCloud
Issuu
Hulu
Giphy
You can see the details of these, and any recent editions in the C# developer reference for Umbraco.Web.Media.EmbedProviders.
Configuring a new provider
Create a new provider by creating a C# class that implements the IEmbedProvider
interface. Umbraco provides a convenient OEmbedProviderBase
class as a starting point.
Adding a new OEmbed Provider Example
Let's allow our editors to embed artwork from the popular DeviantArt website - the world's largest online social community for artists and art enthusiasts. We can see they have information on using OEmbed: https://www.deviantart.com/developers/oembed. The format of their OEmbed implementation returns a JSON format, from a URL https://backend.deviantart.com/oembed?url=[urltoembed]
. We'll need to use the OEmbedProviderBase
and the base.GetJsonResponse
method. We can see 'links' to media shared on DeviantArt are in the format: https://fav.me/[uniquemediaidentifier]
. We'll need a regex to match any URLs pasted into the embed panel that start with fav.me, achieved by setting the UrlSchemeRegex
property.
The Provider would look like this:
Register the provider with the EmbedProvidersCollection
EmbedProvidersCollection
Create a new C# class that implements IComposer
and append your new provider to the EmbedProvidersCollection
:
The new provider should be available for editors to use:
![](https://docs.umbraco.com/~gitbook/image?url=https%3A%2F%2F2945122355-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FmmtM2UdX1OOMSi0CksPv%252Fuploads%252Fgit-blob-534b766e947262f42f99708fe3aa6e82a57deb11%252Fdeviantart-embedded-media.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=5350d199&sv=1)
Notice there isn't really any implementation written here. The regex maps the incoming URL to the provider. The base methods handle the complication of requesting from the third party API and turning the response into HTML.
Custom Embed Providers
If your third-party media provider lacks OEmbed support or requires custom HTML due to content quirks, implement GetMarkup()
without using base helper methods.
Custom Embed Provider Example
Azure Media Services (https://azure.microsoft.com/en-gb/services/media-services/) provide 'broadcast-quality' video streaming services. You can embed the Azure Media Player into your site to play a video using an IFrame.
You can create a custom EmbedProvider
to embed an IFrame video player in your content. This can be done by taking the Media asset URL and writing out the required markup.
Here the markup to embed has been manually constructed based upon the iframe video player, no request to an Api endpoint is made...
Register the Azure Embed Provider with the EmbedProvidersCollection
EmbedProvidersCollection
Create a new C# class that implements IComposer
and add append your new provider to the EmbedProvidersCollection
:
Now editors can embed Azure Media video Urls in the format: //amssamples.streaming.mediaservices.windows.net/3b970ae0-39d5-44bd-b3a3-3136143d6435/AzureMediaServicesPromo.ism/manifest
.
Last updated