Relatude Help

18.1 Asset URLs: files, variants and deeplinks

An asset URL points at a file property, a converted variant of it, or a deeplink into embedded content. It carries a token that the store encodes and reads; the URL manager only decides where the token goes. The defaults:

/assets/{token}/sentrum.jpg                     a file
/assets/{token}/sentrum.webp                    a converted variant
https://cdn.example.com/assets/{token}/…        with BaseAddressAssets = "https://cdn.example.com"

The file name at the end only gives a download a sensible name.

Option Meaning
AssetUrlStyle AssetRoot (default), or UnderPageUrl: on the owner's page URL, /tv/sony-x90/sentrum.jpg?asset={token}.
AssetUrlRoot The asset root. Default /assets/.
AssetUrlParamName The query parameter that carries the token with UnderPageUrl. Default asset.
PropertyPathFormat How the target is written: which file property of which node.
AssetUrlFormat How the adjustment is written: size, crop, format, quality.
AssetUrlSignatureKey When set, asset URLs are signed, and edited ones stop working.

PropertyPathFormat and AssetUrlFormat are Encrypted by default, which keeps everything inside the token. The readable formats take it out into the URL:

Encrypted            /assets/aEQL7Rt7YbRadQ4Qhkmg…/sentrum.webp
AssetUrlFormat = QueryParameters
                     /assets/pXy9…/sentrum.webp?w=1200&h=630&f=webp&q=80
AssetUrlFormat = FriendlyShortString
                     /assets/pXy9…/w1200h630fwebpq80/sentrum.webp
PropertyPathFormat = QueryParameters
                     /assets/sentrum.webp?pn=Photo&pid=1042&w=1200&h=630
PropertyPathFormat = FriendlyShortString
                     /assets/Photo-1042/w1200h630/sentrum.webp

pn is the property's CodeName and pid the node's internal id. A readable target works only for plain node properties, not deeplinks into embedded content, and needs a readable adjustment too.

Readable URLs can be edited by hand, so anyone who sees one file can ask for other variants of it, or for another file. AssetUrlSignatureKey closes that: every asset URL then carries a sig parameter over the token, the target and the adjustment, and an edited URL is refused, like a URL that never existed. Use a stable secret, such as the container id, since URLs handed out stop working when the key changes.

/assets/Photo-1042/w1200h630/sentrum.webp?sig=k7QmXn4…

Caching. A variant is converted once and kept, however it is asked for. Asset URLs carry a version (a v parameter in the readable formats), so a ready response may be cached for 30 days. The version changes with the file content, Delete converted files in the admin UI, and, for adaptive variants, ImageDefaultFormat and ImageDefaultQuality.

Image variants adapt by default

FileAdjustmentImage.RequestedFormat defaults to FileFormat.Image, an adaptive format resolved per file when the request is served:

  • No adjustments at all: the original file, unconverted.
  • A GIF at its own size with no other changes: the original GIF, so animation and palette survive.
  • A resized or edited GIF: an animated WebP when the default format is WebP, else a GIF. Every frame is adjusted, so the animation survives either way.
  • Everything else: ImageDefaultFormat (Jpeg, WebP or Png; default Jpeg) at ImageDefaultQuality (default 85), unless the request names a quality.

So ?w=1200 alone is a complete request, and switching the whole site to WebP is one setting (§12.1). A format you name explicitly always wins.