Contentful App Integration

Overview

After installing the Contentful Cloudinary app, you can add Cloudinary assets to content entries directly in the Contentful editor:

Editors open the Media Library widget, a compact version of the Cloudinary Media Library, directly inside a Contentful content item to browse and select images and videos from Cloudinary.

Contentful stores the public IDs of the selected media, and developers can use those IDs in client applications to fetch images, videos or metadata from Cloudinary’s API.

Requirements

Before you begin, make sure you:

• Have an active Cloudinary account.

• Are logged into Contentful. Some of the steps below require logging in as an admin.

All setup steps and usage instructions assume you’re already logged in to the Contentful web app.

Installation and setup

An administrator can follow these steps to set up and configure the Cloudinary app within Contentful.

Install and configure the app

1. Go to Apps > Installed apps.
2. Click Configure next to the Cloudinary app.
3. Provide your product environment's cloud name, API key, and API secret in the respective fields.
   Tip

   Find these credentials on the API Keys page of the Console Settings.
4. (Optional) Set Max number of files to limit how many individual files users can select in a single field.
5. (Optional) Select the existing JSON fields you want to enable for Cloudinary integration.
6. Click Install to finish the installation and save the configuration.

Set up JSON fields for Cloudinary content

By adding Cloudinary fields to your content types, you make it possible to attach Cloudinary images and videos whenever you create entries of those types.

In addition, you can optionally filter assets in Cloudinary based on values bound to fields in Contentful. For example, filter images by product ID so that when you enter a product ID in a Contentful field, only Cloudinary assets with matching metadata (like that product ID) appear for selection.

To set up a Cloudinary field:

1. Go to the Content model tab.
2. To create a new content type:
   1. Click Add field and select JSON object.
   2. Give the new field a meaningful name, then click Add and configure.
   3. From the Appearance section, select Cloudinary app.
3. To edit an existing content type, click Edit for the content field you want to edit.
4. Choose a Resource Type: Image, Video, or All.
5. (Optional) Under Search Filter, define a Cloudinary search expression that can include JavaScript template literals bound to Contentful entry fields. This lets you dynamically filter assets.

   For example, metadata.sku=${entry.fields.sku.getValue{}} AND metadata.status:published filters Cloudinary assets to show the SKU value from the Contentful SKU field, and only shows assets with the value for the metadata field Status as Published.

6. Click Confirm, then Save your changes to the content type.

Enable external references

To deliver Cloudinary's data using the Contentful GraphQL API you must first enable the Custom external references option.

To enable the Resolve content on delivery check box:

1. Go to the Content model tab.
2. Select a content type with a Cloudinary app field set up.
3. On the field used with the Cloudinary app, click Edit. The field editor is displayed.
4. In the Appearance section, select Cloudinary App.
5. Select the Resolve content on delivery check box.
6. Click Confirm.
7. Save your changes for the field.

Use the Cloudinary app

As a content editor, you can use the Cloudinary app in Contentful to add images and videos to your entries, preview them, and make basic edits.

Add images and videos to entries

When you create or edit an entry that includes a Cloudinary field, you can attach images and videos directly from your Cloudinary account. You can insert either the original assets or apply transformation templates.

Transformation templates are preset configurations that let you adjust things like format, size, aspect ratio, and effects before inserting. Using a transformation template is a quick way to customize how an image or video looks or behaves without manually editing or coding transformations later.

To add Cloudinary images or videos:

1. Go to the Content tab and either click Add entry or open an existing entry.
2. Find the field that your administrator set up for Cloudinary content.
3. Click the Select an Asset dropdown button to add images and videos.
   Note

   If you know that you want only images or only videos, you can select either Select an Image or Select a Video from the Select an Asset dropdown button to limit the selection.
4. Click Sign In to authorize your Cloudinary account.
5. To insert originals:
   1. From the Media Library widget, select images and/or videos.
   2. Click Insert.

      

6. To insert transformed images and/or videos:
   1. From the Media Library widget, double-click the asset to open the Download Options tab of its manage page.
   2. In this view, explore the available transformation templates.
      Note

      If you want to create transformation templates for images, see Studio for instructions. Administrators can also create transformation templates for both images and videos. See Named transformations for more details.
   3. Choose the template you want to use and click Insert next to it to add the transformed version to your entry.

      

Thumbnails of your selected images and videos will appear in the entry.

Preview images and videos

1. In the entry, go to the Cloudinary image or video.
2. Open the (3-dots) options menu at the top-right corner.
3. Select Preview. A new browser tab opens displaying the selected image or video.

Edit images (Beta)

You can crop and resize Cloudinary images that you added to an entry, directly from the Contentful editor. You can also place text and image overlays on your images.

1. In the entry, open the (3-dots) options menu on the asset.
2. Select Edit. The Cloudinary editor opens.
3. From here, you can crop, resize, and add image or text overlays.

Trim videos (Beta)

You can trim Cloudinary videos that you added to an entry, directly from the Contentful editor.

1. In the entry, open the (3-dots) options menu on the video.
2. Select Edit. The Cloudinary editor opens.
3. From here, you can trim the video to your desired length.

FAQ

Why don’t I see a content type with a JSON Object field?

Cloudinary stores data in a Contentful entry as JSON. To associate Cloudinary assets with a content type, update that content type to include a new field of type JSON Object. Learn more about the JSON Object field type in Contentful's Add a field to a content type and Fields documenation.

Why does the entry editor show Field value is incompatible?

This happens when the JSON Object field already contains data not generated by the Cloudinary app. To fix this:

1. Confirm you selected the correct field in the app configuration for use with Cloudinary.

2. Ensure you no longer need the existing data in that field.

3. Select I want to override the value using the App. to initialize the field with an empty selection.

After this, you can add media to your entry.

If you need to inspect the raw field value, deselect the field in the Cloudinary app configuration. The editor will then display the default JSON view for object fields.

Support and Resources

• Contentful marketplace listing
• Contentful help documentation
• Get support