Media Optimizer configuration

Cloudinary's Media Optimizer is for targeted Enterprise organizations and simplifies the process to optimize and deliver high-quality media with high performance, low latency and massive scalability.

This page explains how to configure your Media Optimizer setup by introducing you to the key concepts, providing some examples showing what to configure in different situations, and providing step-by-step instructions for each element of the configuration.

Key concepts

• Media source: The location of your high quality media assets. The media source configuration in the console provides details about your media storage locations and how to access them.
• Optimization profile: Identifies a set of media assets by their delivery URL, and defines how they are delivered based on the source of the original media and applied transformations. Optimization profiles ultimately bring together all the different configuration components.
• Mapping function: Determines media transformations that are already being applied to your media sources through existing delivery platforms. Mapping functions enable Media Optimizer to apply the same transformations when delivering the media from its original source.
• Domain: The base part of your Media Optimizer URL. By default this is https://<cloud_name>.mo.cloudinary.net, but you can use your own domain by setting up a custom domain.
• Path prefix: Set in the optimization profile, the path prefix can be thought of as an extension to the domain, which can be used to categorize your media. This allows you to create more than one optimization profile for the same domain, and treat some media differently to others, as shown in Example 7. The path prefix is included in your Media Optimizer URLs, but it is not a folder in your media source.
• Media Optimizer URL: (Also known as the delivery URL). The URL required to deliver media from your media source through Media Optimizer. It combines the domain and any path prefix set in the optimization profile, with the path to the media in the media source. If you already use a platform that optimizes your media through URL parameters, you can keep these in your Media Optimizer URL and Media Optimizer will map them to Cloudinary transformations.

Configuration examples

The objective of the Media Optimizer configuration is to start optimizing the delivery of your media with minimal changes to your site. It should allow you to keep the media URLs on your site either completely unchanged, or needing only minor updates. This is achieved by defining media sources and mapping functions that are brought together in an optimization profile, determining how to treat each media URL request.

There are many different ways to configure Media Optimizer, depending on your situation.

• If you are implementing a new website, or already have a website on which you are displaying un-optimized media, then the configurations shown in Example 1, Example 2, or Example 3 will get you started.
• If you currently store your media in Cloudinary, Example 4 shows how to set up a Cloudinary media source, and choose the right mapping function.
• If you want publicly available media to be fetched through Media Optimizer, see Example 5.
• If you already have a website up and running, and are using a different platform for optimization, Example 6 shows how to map those optimizations to Media Optimizer transformations.
• If you want to treat some media differently to others, check out Example 7.
• If your media is stored in multiple locations, see Example 8.

The configuration is very flexible, so you can use a combination of the above examples, and others, to cater for the needs of your site.

The following examples assume a cloud name of mycloud.

Example 1: Using the default domain and a web address media source

This is the most basic example, which is covered by the Quick start for web address media source. Whether you have an existing site, or are building a new one, this configuration will get you up and running quickly, though later you may want to take a more nuanced approach, such as in Example 7.

Original URL	Media Optimizer URL
https://www.mydomain.com/rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

Required action:

1. Connect a media source:
   • Type: Web Address
   • URI base: https://www.mydomain.com
2. Ensure your optimization profile includes:
   • Media source: as created
   • Domain: https://mycloud.mo.cloudinary.net (Default)
   • Mapping function: Media Optimizer (Default)
3. On your site, replace https://www.mydomain.com with https://mycloud.mo.cloudinary.net.

---

Example 2: Using a custom domain and a web address media source

This is the same as Example 1, but uses a custom domain instead of the default domain. Use this configuration to serve media from your domain, with no changes to your site.

Original URL	Media Optimizer URL
https://www.mydomain.com/rest/of/the/path.jpg	https://www.mydomain.com/rest/of/the/path.jpg

Required action:

1. Connect a media source:
   • Type: Web Address
   • URI base: https://www.mydomain.com
2. Create a custom domain. This involves creating a support request to set up the DNS routing required for you to use your own domain.
   • Domain: https://www.mydomain.com
3. Create an optimization profile:
   • Media source: as created
   • Domain: https://www.mydomain.com
   • Mapping function: Media Optimizer (Default)

---

Example 3: Using the default domain and an AWS S3 media source

Similar to Example 1, this is the most basic example, but with media stored in an AWS S3 bucket. This is covered by the Quick start for AWS S3 media source. In the example shown, https://www.mydomain.com is the proxy used to serve media from the S3 bucket, s3://bucket_name/bucket_folder/rest/of/the/path.jpg.

Original URL	Media Optimizer URL
https://www.mydomain.com/rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

Required action:

1. Connect a media source:
   • Type: AWS S3
   • Bucket name: bucket_name
   • Bucket folder: bucket_folder
   • Access key and Secret key: as appropriate
2. Ensure your optimization profile includes:
   • Media source: as created
   • Domain: https://mycloud.mo.cloudinary.net (Default)
   • Mapping function: Media Optimizer (Default)
3. On your site, replace https://www.mydomain.com with https://mycloud.mo.cloudinary.net.

---

Example 4: Using the default domain and a Cloudinary media source

In this example, the media source is Cloudinary. As Media Optimizer does not come with Cloudinary storage, this example assumes the user has an existing Cloudinary account (with cloud name demo), and perhaps only uses optimization features, so wants to migrate to Media Optimizer, leaving their assets stored in Cloudinary.

The example shows transformations being applied to resize the image (c_fill,h_200,w_200). These transformations are interpreted by the Programmable Media mapping function to map to the equivalent transformations in Media Optimizer.

Original URL	Media Optimizer URL
https://res.cloudinary.com/demo/image/upload/c_fill,h_200,w_200/docs/shoes	https://mycloud.mo.cloudinary.net/image/upload/c_fill,h_200,w_200/docs/shoes

Required action:

1. Connect a media source:
   • Type: Cloudinary
   • Storage cloud name: demo
     
2. Create an optimization profile:
   • Media source: as created
   • Domain: https://mycloud.mo.cloudinary.net (Default)
   • Mapping function: Programmable Media
3. On your site, replace https://res.cloudinary.com/demo with https://mycloud.mo.cloudinary.net.

---

Example 5: Using the default domain and an HTTP proxy media source

In this example, the media source is a publicly accessible HTTP URL. You can use this configuration for media on your site that you don't own, for example, to fetch social media profile pictures. This is covered by the Quick start for HTTP proxy media source.

Original URL	Media Optimizer URL
http://www.mydomain.com/rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/http://www.mydomain.com/rest/of/the/path.jpg

Required action:

1. Connect a media source:
   • Type: HTTP proxy
2. Create an optimization profile:
   • Media source: as created
   • Domain: https://mycloud.mo.cloudinary.net (Default)
   • Mapping function: Media Optimizer (Default)
3. On your site, prefix your URLs with https://mycloud.mo.cloudinary.net/.

---

Example 6: Mapping custom transformations in the original URL

Similar to Example 1, this example uses the default domain and a web address media source, but URLs can include optimization parameters from a different platform (e.g. size=small).

Original URL	Media Optimizer URL
https://www.mydomain.com/rest/of/the/path.jpg?size=small	https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg?size=small

Required action:

1. Connect a media source:
   • Type: Web Address
   • URI base: https://www.mydomain.com
2. Create a mapping function:
   • Mapping function code: JavaScript code to convert size=small to a Cloudinary transformation (see mapping function code examples)
3. Create an optimization profile:
   • Media source: as created
   • Domain: https://mycloud.mo.cloudinary.net (Default)
   • Mapping function: as created
4. On your site, replace https://www.mydomain.com with https://mycloud.mo.cloudinary.net.

---

Example 7: Using two optimization profiles and a web address media source

Depending on your site, you may find that you need a hybrid configuration, whereby some of the media on your site can be delivered with low quality settings, saving more bytes, whereas other media needs high quality settings. You can achieve this using more than one optimization profile.

Original URL	Media Optimizer URL
https://www.mydomain.com/rest/of/path/hero.jpg	https://mycloud.mo.cloudinary.net/high-quality/rest/of/path/hero.jpg
https://www.mydomain.com/rest/of/path/thumb.jpg	https://mycloud.mo.cloudinary.net/low-quality/rest/of/path/thumb.jpg

Required action:

1. Connect a media source:
   • Type: Web Address
   • URI base: https://www.mydomain.com
2. Create a transformation for high quality:
   • Quality: Auto:Best
3. Create a transformation for low quality:
   • Quality: Auto:Low
4. Create an optimization profile for high quality:
   • Media source: as created
   • Domain: https://www.mydomain.com
   • Path prefix: high-quality
   • Base transformation: select the named transformation as created for high quality
   • Mapping function: Media Optimizer (Default)
5. Create an optimization profile for low quality:
   • Media source: as created
   • Domain: https://www.mydomain.com
   • Path prefix: low-quality
   • Base transformation: select the named transformation as created for low quality
   • Mapping function: Media Optimizer (Default)
6. On your site, replace https://www.mydomain.com with one of the following, depending on how you want that asset to be delivered:
   • https://mycloud.mo.cloudinary.net/high-quality
   • https://mycloud.mo.cloudinary.net/low-quality

---

Example 8: Using the default domain and multiple media sources

Similar to Example 1, this example uses the default domain and a web address media source, plus another media source, an AWS S3 bucket. The order in which you specify the media sources in the optimization profile is important, so if you have files of the same name in both sources, the first file found is used.

In the example shown, https://www.mydomain.com is the proxy used to serve media from the S3 bucket, s3://bucket_name/bucket_folder/rest/of/the/path.jpg.

Original URL	Media Optimizer URL
https://www.webdomain.com/rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg
https://www.mydomain.com/rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

Required action:

1. Connect a media source:
   • Type: Web Address
   • URI base: https://www.webdomain.com
2. Create a second media source:
   • Type: AWS S3
   • Bucket name: bucket_name
   • Bucket folder: bucket_folder
   • Access key and Secret key: as appropriate
3. Ensure your optimization profile includes:
   • Media sources: add both media sources, as created
   • Domain: https://mycloud.mo.cloudinary.net (Default)
   • Mapping function: Media Optimizer (Default)
4. On your site, replace https://www.webdomain.com and https://www.mydomain.com with https://mycloud.mo.cloudinary.net.

---

Initial setup

Before you can configure Media Optimizer, you need to set your domain and operating region. If not yet set, a dialog appears when you try to create a new configuration entity, such as an optimization profile or media source.

• Domain identifier: Also known as your cloud name, this is used in your media delivery URLs. You can either change it or leave it as the one you were given at sign up. You can change this at a later date in your Console Settings, but once you start using your configuration, it is best not to change it.
  • For a domain identifier of mycloud, the Media Optimizer URL domain is:
    https://mycloud.mo.cloudinary.net
• Operating region: Select the location that is closest to your existing media storage and/or the majority of your users. This helps to fetch and deliver your media in the most efficient way. Once set, this cannot be changed.

Connect a media source

Media source configurations provide details about your media storage locations and how to access them. You can connect to more than one media source if you store your media assets in multiple locations, and you can reference your media sources in one or multiple optimization profiles.

To connect to a media source:

1. In the Media Optimizer console, navigate to Configuration > Media Sources and click Add New.
2. Complete the form:
   • Media source name: Enter a name for your media source configuration.
   • Type: Select where your media is stored. You can choose from:
     • Web Address
     • HTTP Proxy
     • AWS S3
       
     • Google Storage
     • Cloudinary
   • Enter details about your media source based on the type.
3. Click Save.

Types of media sources

Media Optimizer supports a number of types of media sources, as described in the following sections.

Web address

Use the Web Address type when your media is stored on an HTTP accessible web server (most likely owned and maintained by yourself).

For an asset stored at:

http://www.mydomain.com/rest/of/the/path.jpg

by default, the Media Optimizer delivery URL takes the form:

https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

Web address settings

Setting	Description
URI base	The full URL of the web server (including http:// or https://).
Headers	Advanced option for specifying headers in key/value pairs to include in the fetch request, for authentication or authorization purposes. Example: Key: Authorization Value: Bearer {{vars.token}} {{vars.token}} is an example of an interpolated variable, defined in the mapping function code.
URI template	Advanced option for specifying parameters to include in the fetch request. You can use interpolated variables that are defined in the mapping function code. For an example, see URI template.

---

HTTP proxy

Use the HTTP proxy type to fetch media from a publicly accessible HTTP URL.

For an asset stored at:

http://www.mydomain.com/rest/of/the/path.jpg

by default, the Media Optimizer delivery URL takes the form:

https://mycloud.mo.cloudinary.net/http://www.mydomain.com/rest/of/the/path.jpg

HTTP proxy settings

There are no settings associated with the HTTP proxy type.

---

AWS S3

Use the AWS S3 type to fetch your media from an AWS S3 storage bucket.

For an asset stored at:

s3://<bucket_name>/<bucket_folder>/rest/of/the/path.jpg

by default, the Media Optimizer delivery URL takes the form:

https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

AWS S3 settings

Setting	Description
Bucket name	The name of the S3 bucket.
Bucket folder	The bucket folder containing your media files. Note: Bucket folder names containing spaces are currently not supported by Media Optimizer.
Access key	The access key ID required to read from your S3 bucket.
Secret key	The secret access key required to read from your S3 bucket.
URI template	Advanced option for specifying parameters to include in the fetch request. You can use interpolated variables that are defined in the mapping function code. For an example, see URI template.

---

Google storage

Use the Google Storage type to fetch your media from a Google storage bucket.

For an asset stored at:

gs://<bucket_name>/<bucket_folder>/rest/of/the/path.jpg

by default, the Media Optimizer delivery URL takes the form:

https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg

Google storage settings

Setting	Description
Bucket name	The name of the Google Storage bucket.
Bucket folder	The bucket folder containing your media files.
Service account key	The JSON file downloaded from the Keys tab in your service account (see Creating service account keys in Google's documentation).
URI template	Advanced option for specifying parameters to include in the fetch request. You can use interpolated variables that are defined in the mapping function code. For an example, see URI template.

---

Cloudinary

If your media is stored in a Cloudinary product environment that has a Media Library, your Media Optimizer product environment must be part of the same overall account to use this option (each will have different cloud names). If the two product environments are not part of the same overall account you can use the Web address type instead.

If using Cloudinary purely for storage, and not transformations, you can use the Media Optimizer mapping function. Otherwise you should use the Programmable Media mapping function. The Media Optimizer URL depends on the mapping function used:

Media Type	Path to Original Media	Media Optimizer URL
Image	https://res.cloudinary.com/demo/image/upload/ rest/of/the/path	With Programmable Media mapping function: https://mycloud.mo.cloudinary.net/image/upload/ rest/of/the/path With Media Optimizer mapping function: https://mycloud.mo.cloudinary.net/ rest/of/the/path
Video	https://res.cloudinary.com/demo/video/upload/ rest/of/the/path	With Programmable Media mapping function: https://mycloud.mo.cloudinary.net/video/upload/ rest/of/the/path With Media Optimizer mapping function: https://mycloud.mo.cloudinary.net/ rest/of/the/path + extension

Cloudinary Console Settings

Setting	Description
Storage cloud name	The cloud name of the Cloudinary product environment where your media is stored. It must share the same overall Cloudinary account as the Media Optimizer product environment.

Create a mapping function

Mapping functions are used to identify media transformations that are already being applied to your media sources through existing delivery platforms. They enable Media Optimizer to apply the same transformations when delivering the media from its original source.

Media Optimizer provides two built-in mapping functions that allow you to specify Media Optimizer transformations as part of the delivery URL (applied in addition to those defined in the optimization profile):

• Media Optimizer: This mapping function caters for
  • Transformation parameters added as a query string to the delivery URL, for example:
    https://mycloud.mo.cloudinary.net/rest/of/the/path.jpg?tx=c_fit,h_500,w_500
  • The resource type specified as a query string, overriding any determining of resource_type in the mapping function due to the extension given. This is particularly useful if no extension is given, for example:
    https://mycloud.mo.cloudinary.net/rest/of/the/path?resource_type=image
    where resource_type can be set to image, video or raw.
• Programmable Media: This mapping function caters for transformation parameters within a URL, as they would be if your media source was Cloudinary, for example:
  https://mycloud.mo.cloudinary.net/image/upload/c_fit,h_500,w_500/v1/sample.jpg

You can provide your own custom mapping function to cater for any non-Cloudinary transformations.

To create a mapping function:

1. Navigate to Configuration > Mapping Functions and click Add New.
2. Complete the form:
   • Mapping function name: Enter a name for the mapping function.
   • Mapping function code: Enter here a JavaScript function. For details, see Mapping function code.
3. Click Save.

Mapping function code

Mapping functions require JavaScript code to analyze incoming media URLs, extract transformations and determine the path to the highest quality original media.

As mapping functions are an advanced concept, our support team are on hand to help you create any that you need.

Signature

The expected signature of the function is:

The request parameter is an object that represents the delivery URL and the context in which it was requested. It contains the following attributes:

Attribute	Description	Example
url	The full delivery URL.	https://myhost.com/a/b/c.jpg?v=1&p=2
path	The asset path part of the url.	/a/b/c.jpg
query	A hash of string => string[] representing the query part of the url.	{"v" => ["1"], "p" => ["2"]}

The environment parameter is an object that represents the delivery URL context for the invocation. It contains the following attributes:

Attribute	Description
defaultTransformation	The transformation defined in the optimization profile.
pathPrefix	The path prefix identified for this specific request, as defined in the optimization profile.
timeMs	The current time in milliseconds.
options	A hash of string => string that represents the mapping function options.

Outputs

The output is a hash of string => string with the following keys:

Key	Description	Example
media_key	A globally unique identifier for the media within Cloudinary's storage and cache.	a/b/c.jpg
fwd_key	Optional. An identifier for the media within a media source. By default, fwd_key and media_key are identical, but they could be different if, for example you wanted to map two different sources to the same Cloudinary cache entry.	a/b/c.jpg
transformation	The Cloudinary transformation.	c_fit,h_100,w_150
resource_type	The type of resource.	image, video or raw
media_source_template_variables	A hash of string => string that may be used by the media source URI template field and other advanced media source fields.	{"timestamp": "1612733077", "signature": "1234"}

Mapping function code examples

The following code samples show simple examples of mapping functions, to demonstrate their structure, parameters and logic that may be used.

Example 1

In this example, the request URL contains query parameters that control the dimensions of the delivered image. The code maps these query parameters to Cloudinary transformation parameters. Media Optimizer then adds these transformations to the default (base) transformation that's specified in the optimization profile.

It also removes any path prefix found in the path, as this is not required in the request to be sent to the origin. This enables {{fwd_key}} to be used in the URI template field of the media source to fetch the media.

Given this request and configuration settings:

• Request URL: https://mycloud.mo.cloudinary.net/images/footwear/shoes.jpg?size=small
• Path prefix: images
• Base transformation: t_auto_format_auto_quality

the mapping function would provide the following output variables:

• fwd_key: /footwear/shoes.jpg
• media_key: /images/footwear/shoes.jpg
• transformation: t_auto_format_auto_quality/c_fit,h_100,w_150/
• resource_type: image

Example 2

In this example, the request URL contains query parameters that control the width of the delivered image, either as a width in pixels (e.g. filter=w407 that gets mapped to w_407) or as a decimal string (e.g. filter=ds2 that gets mapped to w_0.2).

In addition to returning the respective Cloudinary transformation, the host is returned in media_source_template_variables, so that it can be used in the Headers setting of a Web address media source (Key: X-Forwarded-Host, Value: {{vars.x-forwarded-host}}).

Given this request:

• Request URL: https://mycloud.mo.cloudinary.net/footwear/shoes.jpg?filter=w407

the mapping function would provide the following output variables:

• media_key: /footwear/shoes.jpg
• transformation: w_407/f_auto/q_auto
• fwd_key: /footwear/shoes.jpg
• resource_type: image
• vars.x-forwarded-host: mycloud.mo.cloudinary.net

URI template

Variables defined in your mapping function can be used in the URI template field and other advanced media source fields in your media source definition.

Variables defined in media_source_template_variables in the mapping function, are referenced using vars in the media source fields.

For example:

{{fwd_key}}?hst={{vars.x-forwarded-host}}

Create a custom domain

If you are on a paid plan and have your own domain name that you want to use instead of Media Optimizer's default domain (https://<cloud_name>.mo.cloudinary.net), you can create a custom domain.

To create a custom domain:

1. Navigate to Configuration > Domains and click the contact support link.
2. Complete the support request form, specifying the name of the domain you want to use.

The support team will add the domain to your configuration and set up the required DNS routing.

Create an optimization profile

Optimization profiles identify a set of media assets by their delivery URL, and define how they are delivered based on the source of the original media and defined transformations. Each optimization profile brings together one or more media sources, a mapping function, a domain and a transformation.

To create an optimization profile:

1. Navigate to Configuration > Optimization Profiles and click Add New.
2. Complete the form:
   • Optimization profile name: Enter a name for the optimization profile.
   • Media sources: If you've already configured media sources in Media Optimizer, select the relevant ones from the dropdown list. Otherwise, you can click Connect a new media source to open a dialog similar to the Media sources configuration dialog and create a new configuration, which you can select on completion of the dialog. When more than one media source is selected, the order in which they are specified is important. Media Optimizer tries to fetch the asset from the first media source, and if it is not found, it moves onto the next media source. Once found, it does not continue to the next media source.
   • Optimization profile URL: Set the domain and path prefix to define the base URL that identifies media belonging to the optimization profile.
   • Base transformation: Select the transformation to apply to all media in the profile. The transformation is ignored for any raw files belonging to this optimization profile.
   • Mapping function: In the advanced settings, select the mapping function that should be used to extract transformations.
3. Click Save.

Enable an optimization profile

After creating an optimization profile, you need to enable it to start optimizing your media delivery through it.

To enable an optimization profile:

1. Navigate to Configuration > Optimization Profiles.
2. Select the optimization profile to enable.
3. Select Enable optimization profile from its kebab menu.

Test your setup

To test your setup, choose a Media Optimizer URL for a media file that you want to deliver through your site. The structure of your Media Optimizer URLs depends on your setup - you can see some examples in Configuration examples.

Enter the URL into a browser and check that it returns an image or a video.

If you get an error, ensure you have one or more optimization profile enabled. You can also check out troubleshooting.

Inspect and replace media URLs

You can inspect media URLs on your site using browser tools. For example, in Chrome:

1. Right-click an image and select Inspect.
2. In the panel that appears, click Network.
3. Select the Filter icon and click Img.
4. Reload the page, and see the images being requested.
5. Hover over an image name to see the full URL, including the domain:
   
   
6. Click the name to see the details:
   
   
   If the image is being delivered through Media Optimizer, you'll see the Media Optimizer domain in the Request URL, the content type most likely being different from your original if you have automatic format enabled, and the image served through Cloudinary.

If the image is not being served through Cloudinary, be sure to update the media URLs in your source code.

For example, if your cloud name is mycloud, given the path to the original media, you can see what the new delivery URL would be:

Media Source	Path to Original Media	Media Optimizer URL
Web Address	http://www.mydomain.com/ rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/ rest/of/the/path.jpg
HTTP Proxy	http://www.mydomain.com/ rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/ http://www.mydomain.com/rest/of/the/path.jpg
AWS S3	s3://bucket_name/bucket_folder/ rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/ rest/of/the/path.jpg
Google Storage	gs://bucket_name/bucket_folder /rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/ rest/of/the/path.jpg
Cloudinary	https://res.cloudinary.com/demo/image/upload/ rest/of/the/path.jpg	https://mycloud.mo.cloudinary.net/ rest/of/the/path.jpg Note: This structure can vary - learn more.

Using Media Optimizer with external platforms

Many websites these days are maintained via content management systems or e-commerce platforms, which store media as part of their functionality. The exact steps for using Media Optimizer with these platforms depend on your specific platform, configurations, customizations, plugins, and more. This section provides some general guidance and examples on using Media Optimizer with these kinds of external platforms.

The main process is to find out the base URL that the platform uses to store media, and to use this as your Media Optimizer media source (configured as a Web Address type). Then, find a way to replace the base URL that the platform uses for media URLs with your Media Optimizer domain.

Some platforms may require manually replacing delivery URLs. Other platforms may have built-in options or plugins that you can use to automate these changes. For some platforms you may need to customize the underlying code.

Platform examples

• Contentful:

  1. Connect a Web Address media source with:
     URI base: https://images.ctfassets.net/<your_space_id>
  2. Manually replace https://images.ctfassets.net/<your_space_id> in all your media URLs, with your Media Optimizer domain, https://<cloud_name>.mo.cloudinary.net.

• Magento:

  1. Connect a Web Address media source with:
     URI base: https://<your_magento_domain>/media
  2. Use Magento's built-in functionality for Using a Content Delivery Network.
     Set Base URL for User Media Files and Secure Base URL for User Media Files to https://<cloud_name>.mo.cloudinary.net to replace https://<your_magento_domain>/media.

• Shopify:

  1. Connect a Web Address media source with:
     URI base: https://cdn.shopify.com

  2. Customize the underlying code to replace the base URL part of the media URL with the Media Optimizer domain.
     For example, replacing cdn.shopify.com with <cloud_name>.mo.cloudinary.net:

• WordPress:

  1. Connect a Web Address media source with:
     URI base: https://<your_wp_domain>
  2. Use WordPress's CDN Enabler plugin to rewrite your media URLs.
     Set CDN Hostname to https://<cloud_name>.mo.cloudinary.net to replace https://<your_wp_domain>. You may also want to edit the CDN Inclusions and CDN Exclusions lists to include only media file extensions.

Troubleshooting

When testing Media Optimizer URLs you may encounter errors. There could be many reasons for these errors, including (but not limited to) an incorrect configuration, an incorrect path used to the source media, incorrect credentials used to access a media storage bucket (e.g. AWS S3 or Google Storage), an issue with the mapping function or a missing media asset.

You can see information about a particular error in the x-cld-error header field of the HTTP response.

For example, if your browser shows HTTP ERROR 404, then using browser tools, you can see that the message in the x-cld-error field is Resource not found:

If, after looking at the error message, you still cannot resolve the issue, our support team will be happy to help.

Invalidate cached assets

If a media asset is already stored on the cache, it is not fetched from its source, so if you change the original asset, you need to clear the cache in order to fetch the correct version of the asset. This is also the case if you change a named transformation that has been applied to a delivered asset.

To clear the cache for specific media assets, and all media derived from those assets:

1. In the Media Optimizer console, navigate to Configuration.
2. Select Invalidate Cache from the Quick Actions section of the left panel.

   

3. In the URLs text box, enter up to 20 asset URLs to invalidate, separated by new lines.

   

4. Click Invalidate Cache.