Media fields & ALT Attributes

Overview

The way multimedia files (images, videos, 3D models, PDFs, etc.) are managed, uploaded, and reused is aimed at optimizing:

• File reuse and duplicate removal by reading multimedia elements from Shopify and caching them in the client’s database.
• SEO capabilities through alternative text (ALT).
• Optimized use of Shopify’s media library.
• Support for different file types in metafields.

Media Management Rules

Rule 1: Images Shared in Metafields

If we have 50 metafields in 50 different products, all referencing the same image, only one image is uploaded to Shopify’s file library. That single image is linked to the 50 metafields of the 50 products.

How items are linked to multimedia files:

• Items are linked using a hash calculated from the content of the multimedia file.
• This means the system checks the actual content of the file, not its name.

Note: The file name is never used to establish the link between the item and its multimedia file. Even if the file name changes, as long as the content hash is the same, the system will recognize it as the same file.

Persistence of files in the Shopify library:

• Once uploaded, a multimedia file remains permanently stored in the Shopify library.
• It is never deleted by the connector.
• If the ALT text is updated, the file remains, and only the text is modified.
• If the file content changes, a new file with a new hash is generated.

Rule 2: Direct Upload of Images from Metafields

When a metafield is configured in the connector and outputs an image:

• This image is uploaded to the store’s Shopify media library.
• If previously uploaded files are reused: data transfer is reduced, organization is maintained, and storage costs are lowered.

Note: Image metafields are not linked to Shopify’s regular product images. They exist as separate entities. More information about supported metafields can be found here.

Rule 3: PDF Support in Metafields

Use cases for sending PDF files through metafields:

• Instructions
• Manuals
• Any other documents required by the customer
• Multilingual support is also possible

Rule 4: Optimized Image Reference for SEO in Products

• Even if two products use the same image, they do not share the multimedia file reference. 
• This allows defining a different ALT for each one.
• File references are only shared within the same product, not between different products.
• However, if a product and one of its variants use the same image, it is uploaded only once. In that case, the variant reuses the product’s main multimedia reference.

Images and ALT attributes: Images are imported with ALT attributes to improve SEO positioning. The attribute is filled with the product title or the variant SKU, and the corresponding order number.

Note: Each product will have its own image to ensure a unique ALT text, which is optimal for SEO. Remember that Shopify only allows one image associated per variant.

If there are multiple images, they will follow the order in Sales Layer.

Rule 5: File Formats Supported by Shopify

• Images: PNG, JPEG, PSD, TIFF, BMP, GIF, SVG, HEIC, WebP
• Videos: .mp4, .mov, .webm
• 3D Models: .glb, .usdz
• Documents (via metafields): .pdf, .csv, .json, .js, .css

Rule 6: File Name Changes in Shopify

Changes made directly to file names within Shopify are permanent. In Shopify, each multimedia file has a unique ID that is used to link it to items, not the file name. Therefore:

• The connector does not overwrite manual name changes made in Shopify.
• When modifying an image name in the PIM, the new name will NOT sync to Shopify.
• Manual edits are preserved, and the system continues to maintain the internal file ID.
• Example: A client can optimize file names for SEO, changing IMG_1234.jpg to red-leather-woman-bag.jpg.

Note: The default image field does not accept multi-language values (Shopify limitation). If mapped with a multi-language field, the connector will sync values from the default language.

External Videos

It is possible to send a URL of an external video through the connector, for example, adding a YouTube-hosted video to a specific product. To do this, a new field called media_external can be created in the connector and mapped to the catalog field (short text or URL field type) containing the video URLs.

Multiple videos can be sent in the same field, separated by commas.

Internal Videos and 3D Images

In addition to external videos, it is possible to send videos or 3D images from the Sales Layer file library.
To do this, a field called media_video must be created in the connector and mapped to a file-type field in Sales Layer.

This field can include all videos or 3D images to be assigned to a product.

Supported extensions:

• 3D Images: .glb, .gltf, .usdz

• Videos: .mp4, .mov

ALT Attribute Customization

It is possible to customize the ALT value for all images through the connector. To do this, the following fields must be created in the catalog and mapped:

• collect_alt
• product_alt
• variant_alt
• media_video_alt: for internal videos and 3D images
• media_external_alt: for external videos

ALT attributes can be configured in two ways:

• Using a text field with descriptions separated by commas, in the same order as the files.
• Using a table-type field, with a column where the first row links to the first file, the second row to the second file, and so on.

If no value is provided, the connector will automatically generate the alt text using the article’s title.

Multimedia File Order

If you want to set the order of multimedia files, you can create the media_order field in the connector and add the formula PRINT ("model3d|mediaimage|video|externalvideo"), placing the elements in the formula in the order in which they should appear in Shopify, where:

• mediaimage: corresponds to the item’s images
• model3d: corresponds to 3D images
• video: corresponds to videos hosted in the Sales Layer library
• externalvideo: corresponds to external videos

 If the media_order field is not mapped, the connector will position the media elements in the following order: media_video, images, media_external.

Media Synchronization and External Systems