Media Optimizer configuration

Cloudinary's Media Optimizer 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 a Cloudinary account, 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 Quickstart 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:
  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:
  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 Quickstart 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:
  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 Quickstart 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:
  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:
  2. Create a mapping function:
  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:
  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.

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.

Media sources

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:
  3. Click Save.

Types of media sources

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

Note
If your media storage is not covered by any of the types listed, please contact support.

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 account/sub-account that has a media library, your Media Optimizer sub-account must be part of the same overall account to use this option (each will have different cloud names). If the two accounts 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 settings
Setting Description
Storage cloud name The cloud name of the Cloudinary account where your media is stored. It must share the same overall Cloudinary account as the Media Optimizer sub-account.

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.

Mapping functions

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

Note
You cannot edit or delete these built-in mapping functions.

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:

Copy to clipboard
function map(request, environment) {
  ...
}

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.

URI template field

Copy to clipboard
function map(request, environment) {
  let transformation = environment.defaultTransformation + '/';

  // If the query parameters include width and height, map them to Cloudinary transformations
  if (request.query.width && request.query.height) {
    transformation += `c_limit,h_${request.query.height},w_${request.query.width}/`;
  } 
  // Otherwise if a size is specified in the query parameters, map it to a specific transformation
  else if (request.query.size) {
    switch(request.query.size) {
      case 'small':
        transformation += "c_fit,h_100,w_150/";
        break;
      case 'medium':
        transformation += "c_fit,h_240,w_360/";
        break;
      case 'large':
        transformation += "c_fit,h_480,w_720/";
        break;
    }
  }
  let path = request.path;

  // Remove the path prefix from the path
  if (environment.pathPrefix.length > 0) {
      path = path.slice(`/${environment.pathPrefix}/`.length);
  }

  return {
    fwd_key: path,
    media_key: request.path,
    transformation,
    resource_type: 'image',
  };
}

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}}).

Headers fields

Copy to clipboard
function map(req, env) {

  // Check for the 'filter' query parameter and map it to a Cloudinary transformation
  var params = '';
  if ('filter' in req.query){
    filter = req.query['filter'];
    params = filter.split(',').map(s=> s.match(/[a-zA-Z]+|[0-9]+/g)).map(item => (item[0] == 'ds')? 'w_0.' + item[1]:item[0] + '_' + item[1]).join(',');
    params+='/';
  }

  // Get the hostname from the request URL
  const new_url = String(req.url);
  const regex = /https?:\/\/([^\/]+).*/g;
  const found = regex.exec(new_url);
  const hostname = found[1];

  return {
      media_key: req.path,
      transformation: params + "f_auto/q_auto",
      fwd_key: req.path,
      resource_type: "image",
      media_source_template_variables: {"x-forwarded-host": hostname}
  };
}

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.

Domains

To create a custom domain:

  1. Navigate to Configuration > Domains and click the contacting 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.

Optimization profiles

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.

Enable optimization profile

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:

    Inspect media URLs
  6. Click the name to see the details:

    See details of a media URL request
    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

Important
Ultimately, how you integrate your external platform with Media Optimizer depends on your platform setup, plugins or customizations that you may have configured, so you should tailor your solution to your particular circumstance.

The examples given here only show possible methods of integration and may not work exactly as described for your specific setup.

  • 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:

      Copy to clipboard
      img src="{{ img_url | replace:'cdn.shopify.com', 'yourcloud.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:

Browser tools showing HTTP error

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.

    Invalidate cache button

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

    Invalidate cache dialog

  4. Click Invalidate Cache.

Notes

  • You can also use the Media Optimizer API to invalidate cache.
  • If you're using Cloudinary as your media source, and replace an asset in your media library, you still have to invalidate the cache in this way. The invalidation discussed in Invalidating cached media assets on the CDN does not clear cache used in Media Optimizer.

✔️ Feedback sent!

Rate this page: