Sitecore Media Query Parameters You Did Not Know About!

Anton Tishchenko
Anton Tishchenko
Cover Image for Sitecore Media Query Parameters You Did Not Know About!

Important Upate 2025-02-21

I downloaded the latest Sitecore XM an XP (10.4) and checked the Sitecore.Kernel.dll for the presence of ttc and tt query parameters. They are absent there. It means that all ttc and tt query parameters information is valid only for Sitecore XM Cloud. Also, if you are using Experience Edge, these parameters are not present there as well.

Introduction

I have been working on a pretty standard Sitecore project lately: Sitecore in Docker, a headless website on Next.js — nothing unusual. But I noticed strange behavior for images. From time to time, images stopped working locally. Restarting the container fixed the problem, but rebooting something when it doesn’t work is not an option. Something was wrong.

Media Query Parameters

I started to dig up. And I noticed some strange query parameters: ttc and tt.

I had 2 very similar URLs:

  • /-/media/Project/Verticals/Services/Mockups/colleagues-working-desk.webp?h=620&iar=0&w=620&ttc=63875592181&tt=53A7CC474E8A3AECD1A6F4082A123420&hash=2C60C9CB5249B9125D33446DD6B6B81E
  • /-/media/Project/Verticals/Services/Mockups/colleagues-working-desk.webp?h=620&iar=0&w=620&ttc=63875583505&tt=4D4D737163FC452689E99D08B06FDEED&hash=2C60C9CB5249B9125D33446DD6B6B81E

The first one wasn’t working. The second one was working but stopped after a while. ttc definitely looked like a timestamp. tt looked like some identifier or hash. But I haven’t heard about them before. I even double-checked the official documentation:

  • w - width in pixels.
  • h - height in pixels.
  • mw - maximum width in pixels.
  • mh - maximum height in pixels.
  • la - language (defaults to context language).
  • vs - version (defaults to the latest version).
  • db - database name (defaults to context database).
  • bc - background color (defaults to black).
  • as - allow stretch (as=1).
  • sc - scale by floating point number (sc=.25 = 25%).
  • thn - thumbnail (thn=1).
  • dmc - disable media caching, both retrieval and storage (dmc=1).
  • hash - media request protection hash.

There are no ttc and tt in the official documentation on February 2025.

Ok, if not Sitecore, maybe Next.js is adding these parameters? No. Parameters come from the layout service!

The ttc and tt Query Parameters Purpose

If it is not documented, then there is only one option to figure out. Good old one reverse engineering with ILSpy. The thing that you don’t often do nowadays with all these movements to the cloud and headless. After investigation, the purpose of these query parameters is next:

ttc - is a timestamp. The value of this property represents the number of seconds that have elapsed since 12:00:00 midnight, January 1, 0001 in the Gregorian calendar.

tt - is hash calculated from ttc, image path, image query parameters, and unique salt(Media.RequestProtection.SharedSecret Sitecore setting). You can easily calculate it if you know Media.RequestProtection.SharedSecret. But it is impossible without knowledge of this setting.

Sitecore added one more layer of protection to your instance from attacks using media items. It makes your media request protected and valid only for some time. The default value is 10 minutes. It means that all image URLs will expire after 10 minutes. And you will get 302 response. You can extend expiration by modifying Sitecore setting Media.UrlSignatureExpirationTimeout. And I did it by setting it to 24 hours instead of 10 minutes. I was also unable to find any documentation about it.

Verification of these parameters happens inside Sitecore.Pipelines.HttpRequest.RequireAuthentication processor. I didn’t find any possibility to disable this verification other than overriding this processor and removing URL verification.

The investigation was done on Sitecore.Kernel, Version=41.0.0.0. It may differ from version to version as it is not documented. 41 is numeration for XM Cloud. I downloaded the latest Sitecore XM an XP (10.4) and checked the Sitecore.Kernel.dll for the presence of ttc and tt query parameters. They are absent there. It means that all ttc and tt query parameters information is valid only for Sitecore XM Cloud. Also, if you are using Experience Edge, these parameters are not present there as well.

Side Effects

There are a few side effects of this feature. They may cause unexpected behavior if you are using Sitecore XM Cloud without Experience Edge:

  • You can’t share links to your images. You can, but they will expire in 10 minutes. It may be considered a feature, but for some use cases, it will be a bug.
  • You will get pages without images if you run Next.js in ISR or SSG mode. Next.js prepares a static HTML cache for your pages if you use SSG or ISR. This cache will contain links to the images. Next.js doesn’t know anything about image URL expiration. And it will provide you with expired image URLs. I don’t know how to completely avoid this problem. You can increase image URL lifetime, you can decrease ISR cache lifetime. It will make this problem very rare. But the possibility remains. You can remove the URL verification by overriding the request processor, but it was added for protection purposes. Removing protection is an extreme measure I would not do it unless I need to.

Conclusion

If you are faced with the strangely rare absence of images on your website, pay attention to the presence of tt and ttc parameters in your image URLs. They could be the reason. And now you are prepared to handle problems with them if you get any. If you use Next.js Static Site Generation (SSG) or Incremental Static Regeneration (ISR), make sure that your publishing and caching strategies are aligned with Media.UrlSignatureExpirationTimeout Sitecore setting to make the problem of absent images as rare as possible.