How to add a vimeo video to a headless CMS

In this short article, we will cover some basics you want to know about integrating Vimeo to your headless CMS setup. We're going to use Storyblok to showcase the overall idea, and also will make use of a custom field type we've prepared for you so you can use more information of the referenced video.

What is Vimeo?

Vimeo is a video sharing platform that was launched in 2004 by a group of filmmakers who wanted an easy and beautiful way to share videos with their friends. Word started to spread, and an insanely supportive community of creators began to blossom. Now Vimeo is home to more than 70,000,000 creators worldwide. With a userbase of 70,000,000 creators, it's a great place to promote your video in a specific set of people, other than on YouTube you will notice that videos have a more art like experience. Vimeo was first in supporting HD playback for all their consumers and upgraded to 4K/UHD in 2016. More features like Vimeo Live, on-demand, 360 videos and more launched since then and more will come for sure.

What's the best way to refer to a Vimeo video?

To refer to a specific video on Vimeo all you need is the video_id since it would be a real pain to only cut out the video_id from the Vimeo URL since it will lead to more errors and would be a bad user experience to do additional work. So how do we share a video right now? Using the whole video URL, like https://vimeo.com/22439234 which is the most watched video on Vimeo with more than 76,7 million plays.

Let's start fresh

You can add that component structure to existing spaces, to keep this tutorial simple we will start with a fresh space. Our first step will be to click Create new space in the sidebar after we are logged into app.storyblok.com.

You should now see a popup with the message Click here to get started. We will click on the Home entry since we’re going to extend the default components added as an example during startup for us with our own Vimeo component.

Storyblok Compose Mode

Since we want to create and add new components to the default content structure provided, we will click on the Compose menu item next to edit in the top navbar. After entering the Compose mode you will see that the sidebar on the left will disappear and the content sidebar on the right will appear. You will also see two components (teaser, grid) that have been added to showcase the main idea. Those components are also covered in the demo code with different technologies.

Creating and adding the Vimeo component

1. Define new component

To create a new component in Storyblok you can use the components Menu in the space sidebar or directly in a content-entry. We will use the content entry approach: we will click the Add Block button below the demo components.

2. Add an instance of the component

After that, you should be in the Add Block sidebar which allows you to add existing components and also create a new one. To do so all we have to do is to enter our name in the search. Since the component does not exist you will be able to hit “create new component”. We will name our new component vimeo.

3. Define fields for the component

You’ve now already created a new component. Next step will be to define the schema (properties) of that component. Since our Vimeo component should be able to hold a Vimeo URL we will choose a Text-Input type. In the field with the placeholder Enter a key value we will enter video since this will the property we want to have for our Vimeo video. Last step to complete and save the schema we will have to press Save schema at the top right corner.

4. Load your content

You're now already able to insert Vimeo URLs in the text-field you've just created. Add a URL and press Save, by accessing your content entry:

        
      curl https://api.storyblok.com/v1/cdn/stories/home?token=YOUR_PREVIEW_TOKEN
    

you will see the URL in a field called vimeo.

We now got the URL - what's next?

With the Vimeo URL, you can actually already do more than you would expect. You can access their Oembed API to load additional information about the video by simply providing exactly the URL we've just entered. Below you can find a quick JavaScript XHR that does that request for you without the need for authentication as required by the normal Vimeo API.

        
      xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    if(this.status == 200) {
      console.log('doing this request: ', this.responseURL, ' results in: ', JSON.parse(this.responseText)
    } else {
      console.log('oh snap, there was an error: ', this.responseText)
    }
  }
});
xhr.open('GET', 'https://vimeo.com/api/oembed.json?url=https://vimeo.com/22439234');
xhr.send(data);
    

Doing so you will receive a JSON response with following fields:

        
      {
  "type": "video",
  "version": "1.0",
  "provider_name": "Vimeo",
  "provider_url": "https://vimeo.com/",
  "title": "Loved By All: The Story of Apa Sherpa",
  "author_name": "Sherpas Cinema",
  "author_url": "https://vimeo.com/sherpascinema",
  "is_plus": "0",
  "account_type": "pro",
  "html": "<iframe src=\"https://player.vimeo.com/video/270499256?app_id=122963\" width=\"640\" height=\"270\" frameborder=\"0\" title=\"Loved By All: The Story of Apa Sherpa\" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>",
  "width": 640,
  "height": 270,
  "duration": 836,
  "description": "Every spring the summit of Mount Everest draws people from around the world. But in its shadow live the Sherpa, a resilient, religious people, ...",
  "thumbnail_url": "https://i.vimeocdn.com/video/701583376_640.jpg",
  "thumbnail_width": 640,
  "thumbnail_height": 270,
  "thumbnail_url_with_play_button": "https://i.vimeocdn.com/filter/overlay?src0=https%3A%2F%2Fi.vimeocdn.com%2Fvideo%2F701583376_640.jpg&src1=http%3A%2F%2Ff.vimeocdn.com%2Fp%2Fimages%2Fcrawler_play.png",
  "upload_date": "2018-05-17 16:40:34",
  "video_id": 270499256,
  "uri": "/videos/270499256"
}
    

So all that's left for you would be to embed the iframe provided by that API to be included on your website. You can even use a thumbnail (with play button) of the video to lazyload the iframe if the video was pressed.

Custom Field Type

With Storyblok you're able to write your very own field-type because sometimes a default set of types is not enough. Maybe you want to load data from an e-commerce system to select products, assets from one of your asset management services or load additional information and validate a specific pattern. If you want to try that check out our documentation about custom field types.

For Vimeo, I've prepared a basic custom field you can either use directly or create your own version from. To activate the Vimeo field-type all we have to do is to navigate back to the Define schema section of your Vimeo component and change the Type from Text to Plugin. There you should be able to search for vimeo and choose it all that's left to do is to save by pressing Save Schema again.

You can now insert your Vimeo URL – in the background, the plugin will check if it is a valid Vimeo URL and also does the above request for you. All you will have to do is to use the information added to your content-entry and enjoy your Vimeo video. Instead of having only the URL and do the request in your website, you can now use on the information saved in Storyblok by the plugin, which is basically the request result:

        
      curl https://api.storyblok.com/v1/cdn/stories/home?version=draft&token=7cpErGW5TYi9CMWWeqISsgtt
    

If Vimeo does not return any information the response will be empty and you will receive an error directly below the field to check what is happening.

Conclusion

You can see it is really easy to add Vimeo to new or existing content structures. Adding a simple text field is all you would need to add to your content entry to have access to most of the features required by an video, if that's not enough you can still use the video_id and access the Vimeo API directly. Customizing the compose mode and fields in Storyblok is as easy as it can get. You can use Vue.js and even write ES6 modules directly in their Custom Field test suite or develop it locally and publish in there.