servd

Understanding Servd Asset URLs

You may have spotted that the URLs of assets stored in Servd Asset Volumes are little more complicated than other asset volumes. Here's a little more information on what's going on.

Transformed Asset URLs #

Generally, if you run {{ asset.getUrl() }} or {{ asset.url }} in your twig templates where asset is a "transformable" image stored in a Servd Asset Volume, then you'll see a URL that looks something like this:

Breaking the URLs down a bit further:

• project-slug is your project's slug that's used in various places across the platform.
• environment is the asset environment that this asset resides in.
• subfolder is the subfolder path configured in the Servd Asset Volume. If you only have one volume, then you don't need a subfolder, it can be left blank and will be omitted from the URLs.
• w is the width parameter of the transformed image. By default it will be the natural dimensions of the image file, but you can provide Craft image transforms to change it.
• h is the height parameter of the transformed image. By default it will be the natural dimensions of the image file, but you can provide Craft image transforms to change it.
• auto is a list parameter which tells our transformer all the properties of the transform to figure out automatically. If format is part of the list, then the transformer will attempt to automatically attempt to convert the file to a more efficient format (e.g. webp or avif) depending on browser compatibility and the "Image Format Autoconversion" Servd plugin setting.
• fit is the method the transformer will use to accommodate differences in aspect ratio and dimensions.
• dm corresponds to the asset's dateUpdated timestamp. If the asset is updated, it will change and bust our CDN transform cache, resulting in a new transformed image being generated.
• s is a security token.

Relying on the Servd plugin to generate the URLs instead should avoid the issue.

File Asset URLs #

File asset URLs link to the original copy of the asset file stored on the URL. They look these:

You'll often see them when calling {{ asset.getUrl() }} or {{ asset.url }} where the asset file is not considered a transformable file type e.g. PDFs, or if you've disabled asset transformations in the Servd Plugin settings.

The project-slug, environment and subfolder parts of the URL correspond to the same things as described above for transformed asset URLs.

Video Asset URLs #

Because video assets are a bit more bandwidth-intensive, we use a separate video-optimised CDN to serve them.

When you call {{ asset.getUrl() }} or {{ asset.url }} in your twig templates, the URLs will look something like this:

Transformable File Types #

The following file types are considered transformable by the Servd Plugin:

• jpg
• png
• webp
• avif
• svg

With regards to gifs, the Servd plugin respects Craft's transformGifs general config setting.

Troubleshooting #

Invalid security hash

The value of the s query parameter is a hash of the transformed URL, excluding the s parameter key. It is there to prevent the Servd Asset Platform being overwhelmed by malicious requests to generate lots of slightly different transforms.

If the transform URL generated by the Servd plugin is tweaked manually or by your code, then the hash will no longer match the remainder of the URL, and you'll be presented with a 403 error response like this:

File with such name does not exist

If you see this 404 error response, it's likely down to the asset getting deleted or moved, or due to a misconfigured path: