Image Storing and Serving | Yext Hitchhikers Platform

Yext Content supports a range of image storing capabilities to ensure that images can be served flexibly on digital experiences.

Once a photo has been uploaded to Content, there are multiple ways to specify how that photo should be displayed for downstream use (i.e., any source that would refer to that image on your entity, such as Listings or Pages.)

Storing Images

Photos can be stored on entities in fields of either the Photo or File field type.

File Field Type Photo Field Type
Can add validation for height, width,
and aspect ratio
No Yes
Can add validation for file size Yes No
Can use dynamic links (dynl, dynm) Yes Yes
On-the-fly resizing Yes Yes

For more information on the usage and limitation of each of these field types, check out the File Field Type reference documentation and the Photo Field Type reference documentation.

Serving Images

When referencing images in downstream products, the base URL of the photo should change to one of our image serving base URLs. Think of a.mktgcdn.com as the hosting URL, and dyn.mktgcdn.com, dynl.mktgcdn.com, and dynm.mktgcdn.com as the serving URLs.

While the uploaded image we are hosting has a given size and specification, using our serving URLs allows for you to specify the size the image should be in downstream instances.

Using Served Images on React Front-Ends

The Image component can be used to seamlessly serve pictures from Yext Content into your downstream experiences.

The Image component does not yet support the new image serving options, but we hope to support it soon.

Dynamic Image Transformation

We use Cloudflare to host and serve our photos. This allows you to perform a variety of on-the-fly image transformations simply by adding options directly to the URL as path parameters. The full list of options can be viewed here.

If you are transforming a file field type URL to be served, a.mktgcdn.com/f/{businessID} should be adjusted to dyn.mktgcdn.com/p/.

If you are transforming a photo field type URL to be served, a.mktgcdn.com should be adjusted to dyn.mktgcdn.com and the dimensions and extension at the end of the URL should be dropped.

The served image URL should have the form: https://dyn.mktgcdn.com/p/{image_UIUD}/{options}

Example

If you uploaded a photo that you wanted to:

  • Add a blur
  • Set the size to be 1000x1000
  • Crop the rest of the image larger than 1000x1000
  • Rotate it 90 degrees

The process would be as follows:

  1. Fetch the hosted image’s URL https://a.mktgcdn.com/p/weDfOuuWD5IybzlazwEUUps4-NxElRV2E2O0_zOXE6U/1701x1295.jpg

  2. Change the base URL to dyn.mktgcdn.com https://dyn.mktgcdn.com/p/weDfOuuWD5IybzlazwEUUps4-NxElRV2E2O0_zOXE6U/

  3. Add the transforms to the image’s path https://dyn.mktgcdn.com/p/weDfOuuWD5IybzlazwEUUps4-NxElRV2E2O0_zOXE6U/blur=20,height=1000,width=1000,fit=crop,rotate=90

Format Guidelines

Here is a summary of when these formats are best suited:

  • JPEG is best for photos and any image with a wide range of colors.
  • PNG is best for images like clip art or vector art which have a limited color palette.
  • WEBP can handle both use cases well and encodes images into a smaller file at the same level of quality. This format is recommended for web page serving. However, not every application can read this format.

Limitations

Photo serving for uploaded files still relies on the general limitations of the photo system. So using Cloudflare options such as anim for animated gifs will not work because our system doesn’t support serving gifs at this time.

Generated Thumbnails (Legacy)

Before transitioning to Cloudflare, we were unable to specify exact dimensions when serving images. For that reason, the system would proactively generate a set of thumbnails for any uploaded image. Then, the system would receive a height and width as part of serving requests, and would return the thumbnail closest in size to the supplied size.

We will still continue to generate these thumbnails when a photo is uploaded to a photo type field, but we do recommend leveraging the dyn.mktgcdn.com base URLs and Cloudflare resizing for more granular control over served images.

Serving your Photos Using Thumbnails

Depending on their origin, photos have a wide variety of formats, dimensions, and metadata attributes such as orientation & color profiles. To optimize for page speed and ensure that all devices can render images correctly, we create a set of thumbnails at several sizes and normalize the image format to something that all devices can consume.

Using Thumbnails on Your Site

Thumbnails are created using your photo’s original dimensions, in addition to thumbnails which are scaled to fit within each of these fixed bounding boxes:

  • 1900x1900
  • 619x1000
  • 600x450
  • 196x400

Your photo is never enlarged nor is the aspect ratio changed. As a result, the thumbnails and dimensions created for your image will not be exactly those shown above.

You access thumbnails using URLs of the form:

FIT.mktgcdn.com/p/UUID/WIDTHxHEIGHT

Similar to Dynamic photo serving - if you are using a file field to store photos and wish to serve them, the base URL needs to be changed from a.mktgcdn.com/f/{businessID}/UIUD to FIT.mktgcdn.com/p/UIUD/WIDTHxHEIGHT.

FIT specifies one of two modes that allow dynamic selection among a set of thumbnails:

  • dynl.mktgcdn.com — “at least” as large, on one dimension
  • dynm.mktgcdn.com — “at most” as large, on either dimension

This dynamic URL will return the thumbnail which is the best fit for the given FIT and dimensions. Note that it may not be an image that has exactly the given dimensions.

Depending on the input format, the thumbnail’s format will be JPEG or PNG. The system also creates and serves WEBP variants on demand, which is a more efficient image format that is used by some applications (Chrome, Firefox).

Example

This image is originally 1220x804: https://a.mktgcdn.com/p/Kvgt-VcTQSOXJfskc8B4s-UnCpN432sCxdTY1exY5L0/original

We can request the smallest thumbnail which is “at least” as large as 600x450: https://dynl.mktgcdn.com/p/Kvgt-VcTQSOXJfskc8B4s-UnCpN432sCxdTY1exY5L0/600x450

That thumbnail is 600x395, which maintains the aspect ratio and has a width which is equal to the requested one. This is the common use case when you want to display the picture in a web page, which typically has one dimension fixed.

If we instead request 601x450, we get the next size up, which is the original size of 1220x804: https://dynl.mktgcdn.com/p/Kvgt-VcTQSOXJfskc8B4s-UnCpN432sCxdTY1exY5L0/601x450

Feedback