Logo visualizations

Show your customers their own logo on your product images — on product lists and detail pages, without opening the editor. You mark <img> elements with data-td-action="RenderVisualization", and the script replaces their src with a rendered visualization of the customer's current logo on that product.

TIP

Example: Logo visualization · source

Check the prerequisites

License feature 2D Visualizations, and logo visualizations enabled in the Admin Portal (Settings → Logo Visualizations, on by default). The script learns whether they are available from the customer initialization (isVisualizationEnabled in the customer/init response). When they aren't, the script ignores the images: no requests, no errors. The print editor's own 2D visualizations setting doesn't affect them.
A supplier code. data-td-supplier-code must be one of the codes defined in Settings → Suppliers.
A visualization source for the product. Either a realistic visualization set up for the product variant and print option (provided by the supplier, by PromoTron or by your own instance), or a print mockup of the product, from which TronDesigner generates the visualization. Which of the two may be used is set in the Admin Portal (see Configure them in the Admin Portal). Images of products with neither keep their original src.
A logo. Either the customer has a current logo (see Logos), or the image names a logo with data-td-visualization-logo.

Mark up a product image

html

<img
  data-td-action="RenderVisualization"
  data-td-supplier-code="TD"
  data-td-product-code="10601353_TD"
  data-td-print-position-code="FRONT"
  data-td-print-technology-code="DPRINT03"
  data-td-visualization-size="max600"
  src="https://www.example.com/images/notebook-royal-blue.jpg"
  alt="Teak A5 notebook - Royal Blue"
/>

Attribute	Required	Meaning
`data-td-action="RenderVisualization"`	yes	Marks the image. Only works on `<img>` elements.
`data-td-supplier-code` or `data-td-supplier-guid`	one of them	The supplier of the product
`data-td-product-code`	yes	The supplier's product variant code. One image shows one variant.
`data-td-print-position-code`	no	Print position to visualize
`data-td-print-technology-code`	no	Print technology to visualize
`data-td-visualization-size`	no	Output size, see below. Default `auto`.
`data-td-visualization-logo`	no	GUID of a logo to use for this image instead of the customer's current logo

Without data-td-product-code, or without a supplier, the image is ignored.
Without position and technology, TronDesigner picks a print option of the variant itself: a realistic visualization set up for it, otherwise the first print option with a print mockup. Which one is not guaranteed, so set both codes when it matters. To show several print options on the same variant, use one <img> per position/technology pair.
A generated visualization uses the product photo of the variant's color from the print mockup, so each color shows the right product.
Keep a meaningful src: it is shown until the visualization is ready, and whenever no visualization can be shown.

Choose the output size

`data-td-visualization-size`	Requested size (px)
`auto` (default)	The natural width × height of the original image file
`full`	1024 × 1024
`max300` / `max400` / `max600` / `max800` / `max1000`	300 × 300 / 400 × 400 / 600 × 600 / 800 × 800 / 1000 × 1000

The result is a JPEG that fits into the requested size. A realistic visualization is rendered from the smallest stored image that is at least the requested size (or the largest one available); a generated one from the print mockup's product photo. An unknown value falls back to auto. The size is read once, when the script first finds the image.

Control which logo is shown

By default every image shows the customer's current logo. When it changes — through setLogo(), or because the customer picked a logo in the dialog opened with openLogoGallery() / openLogoUpload() — all images re-render. clearLogo() restores their original src.
data-td-visualization-logo pins one image to a specific logo from your TronDesigner instance, for example your own showcase logo. These images ignore the customer's current logo and clearLogo().
No logo at all: the images keep their original src.

// Let the customer choose a logo; the images on the page update by themselves
window.tronDesigner.openLogoGallery({ mode: 'dialog' });

Visualizations also follow setCustomer(): when the customer it sets has a different logo, the images re-render with that logo (or get their original src back if the customer has no logo).

Update images on dynamic pages

The script watches the whole document:

Visualization images you add later (infinite scroll, SPA navigation) are found and rendered automatically — both an <img> inside an added element and an <img> appended directly to the page.
If you add data-td-action to an image that is already on the page, call refreshRegisteredElements() afterwards.
When you change data-td-supplier-code, data-td-supplier-guid, data-td-product-code, data-td-print-position-code, data-td-print-technology-code or data-td-visualization-logo on an image, it re-renders — also when the previous attributes had no visualization. Use this for a color switcher, and update src to the variant's photo at the same time:

const img = document.querySelector('#product-image');
img.src = 'https://www.example.com/images/notebook-solid-black.jpg';
img.dataset.tdProductCode = '10601390_TD'; // re-renders for the "Solid Black" variant

When there is no visualization to show — the new variant has no visualization data, the logo was cleared with clearLogo(), or rendering couldn't start — the script shows the original image again, including its srcset.

NOTE

"Original" means the src and srcset the image had when the script first found it. If you change src in a color switcher and the new variant has no visualization, the script switches the image back to that first src. To show the new photo in that case, replace the <img> element instead of changing its attributes.

Understand rendering, tokens and caching

After the customer is initialized, the script sends all pending images in one request (POST …/api/visualization-render/tokens) and receives a render token per image. Images without a token (no visualization, no logo) show their original image.
For each token, the script preloads the render URL (…/api/visualization-render?token=…&mode=…&apiKey=…), then swaps it into src and removes srcset. At most four images render at a time, top to bottom.
If rendering fails, the original image stays and the error is logged in the console.

Render tokens are signed, bound to your instance, and carry the visualization and the logo. A token is valid for 24 hours, and identical requests get an identical token for a while, so the browser can reuse a cached image (rendered images are cached by the browser for one hour). The script requests fresh tokens on every page load, so you never handle expiry yourself.

Track usage

Each image the server renders and returns counts as one visualization towards the 2D Visualizations quota of your license, shown on the Admin Portal dashboard:

realistic and generated visualizations count the same;
images served from the browser cache, renders that fail, the 2D visualizations inside the editor and the preview in the Admin Portal don't count;
the REST render endpoint counts the same way.

Rendering doesn't stop when you reach the quota.

WARNING

Like every call of the script, the render URL is authorized with your API key and the page's domain, which the browser sends in the Referer header. If your site sends Referrer-Policy: no-referrer, the rendered images fail to load and the original images stay.

Configure them in the Admin Portal

Settings → Logo Visualizations — globally, or for a single website integration API key (a key's own settings replace the global ones):

Enabled — switches logo visualizations off without removing the markup from your pages.
Visualization source — realistic falling back to generated (default), realistic only, or generated only. Products without a visualization the chosen source allows keep their original image.
Watermark — an optional text or image (PNG or JPEG) watermark drawn over every visualization, once or as a mosaic, with adjustable opacity and angle.
Preview — renders one of your products with the settings before you save them.

These settings apply only to the images rendered by the integration script. The print editor has its own 2D visualizations setting, and the REST API takes the source per request and renders without a watermark.

Changed settings take effect at the next page load: they change the render URLs, so images cached by the browser are not reused.

Logo visualizations ​

Check the prerequisites ​

Mark up a product image ​

Choose the output size ​

Control which logo is shown ​

Update images on dynamic pages ​

Understand rendering, tokens and caching ​

Track usage ​

Configure them in the Admin Portal ​

See also ​