# Cloudinary

> Source: https://agilitycms.com/docs/apps/cloudinary

The Cloudinary App for Agility lets editors search, select and attach Cloudinary resources — images and videos — to their content, without leaving the content form.

Cloudinary is an amazing tool to help you unleash the full potential of your online media. Optimize, transform, and combine your images to create great digital experiences. Upload and stream high quality adaptive videos from your website.

The field stores Cloudinary’s own asset metadata as JSON, so your front end can hand the public_id straight to any Cloudinary SDK and get delivery, transformation and optimisation for free.

## Features

- Link to Cloudinary resources directly from Agility CMS content
- Browse, search and upload to your Cloudinary media library
- Choose the transformation, quality, and optimized versions of the resource
- Preview the selected resource, and set alt text on images
- Stores the selected resource metadata in a JSON object which is returned from the Agility API

## The Cloudinary Image Field

Shows a preview of the attached image alongside its Cloudinary public ID, type, size and URL. The alt text box writes to the asset’s Cloudinary metadata, so it travels with the value to your front end.

![The Cloudinary Image field with an asset attached](https://cdn.aglty.io/agility-cms-docs/images/apps/cloudinary/cloudinary-image-field.png)

## The Cloudinary Video Field

The same, for video. The attached video plays inline so an editor can confirm they picked the right one.

![The Cloudinary Video field with an asset attached](https://cdn.aglty.io/agility-cms-docs/images/apps/cloudinary/cloudinary-video-field.png)

## Browsing your Cloudinary assets

Click **Browse** (or **Change**, when something is already attached) and Cloudinary’s own Media Library opens inside Agility — search, folders, tags, upload and the transformation editor, exactly as your team knows them. The field filters the library to the right resource type, so an image field only offers images.

![The Cloudinary Media Library, filtered to videos](https://cdn.aglty.io/agility-cms-docs/images/apps/cloudinary/cloudinary-asset-selector.jpg)

The first time an editor opens the browser they are asked to sign in to Cloudinary, or are passed through your Cloudinary SSO. That is Cloudinary’s own authentication, and it is what scopes what they can see and upload.

## Requirements

In order to use this integration, some set up is required.

- Ensure you have setup [Agility](https://agilitycms.com/trial/) and [Cloudinary](https://cloudinary.com/) accounts.
- Install the app from the Marketplace.
- Create Content Models that use the Cloudinary Image / Video custom fields.
- Output the Cloudinary assets in your digital solution (i.e. website or app).

## Retrieve your Cloudinary API Credentials

Log in to the Cloudinary console. Take note of the **Cloud name** and **API Key** from the main dashboard. You do *not* need the API Secret, and you should not paste it into the app.

## Install the App

Install the app from the **Settings > Apps** section of Agility, then fill in its two configuration values:

- **Cloud Name** — your Cloudinary product environment, e.g. demo
- **API Key** — the API Key from the same dashboard

Until both are filled in, the fields show a “Cloudinary is not configured yet” notice naming what is missing.

## Set Up Content Models to use Cloudinary Fields

In order to use Cloudinary fields, you need to have Content Models or Page Modules in Agility CMS that utilize these new field types.

- Navigate to **Models** -> **Content Models** -> {**Your Content Model**}
- To add an **Image** field, click **Add Field**
  - Field Name: *Cloudinary Image*
  - Field Type: *Custom Field*
  - Custom Field Type: *Cloudinary Image*
- To add a **Video** field, click **Add Field**
  - Field Name: *Cloudinary Video*
  - Field Type: *Custom Field*
  - Custom Field Type: *Cloudinary Video*

Next, create some content using your Content Model.

- Navigate to an instance of your content that is based off your **Content Model**
- Click **+ New**
- Fill out the fields
  - On the **Cloudinary Image** field, click **Browse**. Your Cloudinary media library opens — upload or choose an existing image.
  - On the **Cloudinary Video** field, click **Browse** to choose a video.

## Render/Output the Cloudinary Assets in your Solution

Now that you have set up the field and allowed editors to reference assets from Cloudinary, the next thing you will need to do is actually output these fields in your digital solution (i.e. website or app).

### Cloudinary Field Values

The value of an Image or Video Cloudinary field is a JSON string returned from the Content Fetch or GraphQL API. Parse it to an object with JSON.parse(value) before reading it. An empty field is an **empty string**, so guard for that first — JSON.parse("") throws.

### API Response Format

```
{
  "public_id": "pexels-juan-salamanca-61143_o51ss6",
  "resource_type": "image",
  "type": "upload",
  "format": "jpg",
  "version": 1623349590,
  "width": 5184,
  "height": 3456,
  "bytes": 1992294,
  "created_at": "2021-06-10T18:26:30Z",
  "secure_url": "https://res.cloudinary.com/agility-cms/image/upload/v1623349590/grass.jpg",
  "url": "http://res.cloudinary.com/agility-cms/image/upload/v1623349590/grass.jpg",
  "tags": [],

  // alt text typed in the field lives here
  "context": { "custom": { "alt": "This is a grass field" } },

  // present ONLY when a transformation was chosen. This is an ARRAY.
  "derived": [
    {
      "raw_transformation": "c_fill,h_600,w_1200",
      "secure_url": "https://res.cloudinary.com/agility-cms/image/upload/c_fill,h_600,w_1200/v1623349590/grass.jpg"
    }
  ]
}
```

A few things worth knowing:

- **public_id** is the asset’s identity, and the argument every Cloudinary SDK takes. It is the only key you can rely on always being there.
- **derived** is an **array**, and it is absent when the editor picked the original rather than a transformation. derived[0] is what the editor saw in the field, so it is usually what the page should render.
- **alt text** is at context.custom.alt. It is absent rather than empty when unset, so *?? fallback* works.
- **duration** is present on videos only, in seconds.
- Cloudinary’s payload varies by resource type, account features and over time — treat everything except public_id as optional.

### Rendering Example

With no Cloudinary SDK at all — take the URL the editor saw:

```
const asset = JSON.parse(item.fields.heroImage)
const src = asset.derived?.[0]?.secure_url ?? asset.secure_url

<img
  src={src}
  alt={asset.context?.custom?.alt ?? ""}
  width={asset.width}
  height={asset.height}
/>
```

Or apply your own transformations from the public_id, using Cloudinary&rsquo;s current React SDK:

```
import { Cloudinary } from "@cloudinary/url-gen"
import { AdvancedImage } from "@cloudinary/react"
import { fill } from "@cloudinary/url-gen/actions/resize"

const cld = new Cloudinary({ cloud: { cloudName: "agility-cms" } })
const asset = JSON.parse(item.fields.heroImage)

<AdvancedImage
  cldImg={cld.image(asset.public_id).resize(fill().width(1200).height(600))}
  alt={asset.context?.custom?.alt ?? ""}
/>
```

Video, with the browser&rsquo;s own player:

```
const video = JSON.parse(item.fields.promoVideo)

<video
  src={video.secure_url}
  controls
  playsInline
  width={video.width}
  height={video.height}
/>
```

### Using Cloudinary Libraries

Cloudinary builds and maintains front-end SDKs to assist with rendering images and videos, complete with handling transformations and much more.

- [Cloudinary JavaScript SDK](https://cloudinary.com/documentation/javascript_integration)
- [Cloudinary React SDK](https://cloudinary.com/documentation/react_integration)
- [Cloudinary Vue.js SDK](https://cloudinary.com/documentation/vue_integration)
- [Cloudinary Mobile/Native SDKs](https://cloudinary.com/documentation/mobile_sdks)
- [Nuxt SDK](https://cloudinary.nuxtjs.org/)

### Source Code

The app is open source (MIT) at [github.com/agility/agility-cms-app-cloudinary](https://github.com/agility/agility-cms-app-cloudinary).