Changelog

This page lists changes that affect your integration code: the integration script (website-integration.js and the methods of window.tronDesigner), the EditorArguments contract and its TypeScript types, the data-td-* attributes, the editor events, and corrections to this documentation. Breaking changes are marked Breaking.

New editor features and product releases are announced on the TronDesigner support site.

How versions work

Entries are dated. There's a single public script URL (https://app.trondesigner.com/js/website-integration.js), so every site always loads the current version.

Unreleased

Added

• Added EDITOR:DESIGN_COLOR_<number> custom properties for suggested colors and single-color automatic logo adaptation. See suggested design colors.
• printJob.customProperties['EDITOR:DESIGN_INSTRUCTION'] displays design instructions as an informational notification at the bottom of the editor canvas. Set it through data-td-custom-properties, the JavaScript builder or the editor arguments JSON. See Show design instructions in the editor.
• setDataMode(dataMode) on window.tronDesigner and the builder, also after setPrintJob(guid, 'Edit'). Use setPrintJob(guid, 'Edit').setDataMode('Exact') to lock the structure of the print job in an Edit session (without it, Edit sessions still run as Partial). Called after the product setters, it overrides their data mode. See Open modes.
• setEditorOptions(options) on window.tronDesigner and the builder: merges any EditorOptions into editorOptions, e.g. showSelectedVariants in Exact mode. See JavaScript builder API.
• Generated logo visualizations. Products without a realistic visualization for the print option now get one generated from the product's print mockup (in the color of the variant), so data-td-action="RenderVisualization" images of many more products render. See Logo visualizations.
• Admin Portal → Settings → Logo Visualizations, globally or per website integration API key: switch logo visualizations on or off, choose the source (realistic falling back to generated, realistic only, generated only), add a text or image watermark, and preview the result. See Configure them in the Admin Portal.
• REST API: GET /api/visualizations/render renders a logo onto a product variant and returns a JPEG; the source is chosen with visualization2DMode. Needs the license feature API Visualizations. See Render a logo visualization.
• REST API: POST /api/logos uploads a logo (multipart/form-data, up to 20 MB, asynchronous with 202 and Retry-After, optional WaitSeconds and Idempotency-Key, duplicates reported as deduplicated), and GET /api/logos/{logoGuid}/upload-status reports its processing status. See Upload a logo.
• REST API: POST /api/logos/{logoGuid}/recolor replaces colors of a logo (PMS, CMYK or RGB) and returns a new, Hidden logo. Needs the license feature API Automation. See Recolor a logo.
• REST API: GET /api/logos/{logoGuid} is documented field by field, see Get a logo.

Changed

The changes in bold affect what your integration sees — check your code:

• REST API errors report exceptionType as a string. Error bodies of the REST API carried exceptionType as a number (1); it's now the name ("Validation", "Authorization", "ApplicationError", "UnhandledError"), as Swagger always described it. If your code compares it with a number, compare with the name instead.

• Breaking — REST API requests that can't be read get the usual error body. Malformed JSON, a value of the wrong type or a missing required field used to be answered with an ASP.NET problem details body (type, title, status, errors). All 400 responses now have the same body as every other error: exceptionType, title and messages, where each message names its field in messageParameters.field. If your code reads errors from a 400, read messages instead. See Errors.

• REST API logo logoUrls use file type names. The links in logoUrls end with fileType=ORIGINAL, CONVERTED or PREVIEW instead of 1, 2 and 3. Both forms are accepted, so stored links keep working.

• Documentation: the logo.created webhook is also sent for logos created by edits (recolor, crop, …), not for duplicate or failed uploads, and its body is the logo list item. A failed manual resend goes to Dead Letter.

• Logo visualizations count towards the 2D Visualizations quota. Every image rendered and returned by the server — by the integration script or the REST API — counts as one; images from the browser cache, failed renders, the editor's own visualizations and the Admin Portal preview don't. See Track usage.

• text / created events carry a GUID. entityGuid was an empty string; it's now the ID of the text object — unique for each text, the same when the customer changes that text again, and equal to the id of the text's motive object in the saved print job. See Events and callbacks.

• View mode hides the add and remove printing controls. In View mode (with the Partial data mode) the editor showed the add printing tab and the remove buttons on the printing tabs; they're now hidden.

• Order title and code from HTML attributes are no longer swapped. data-td-order-title is now saved as customer.orderTitle and data-td-order-code as customer.orderCode (before, the two were swapped). If you swapped your attribute values to compensate, swap them back. Print jobs saved before the fix keep their swapped values; they aren't migrated. setOrderInfo(), data-td-options and JSON were never affected.

• The Close result action reports 'Confirmed' and redirects. After the final confirmation the editor now closes with the reason 'Confirmed' (it was 'Cancelled'), and the script follows the redirect URL (data-td-result-redirect-url, setResultActionCloseEditor(url), editor.result.redirectUrl). If your onClose navigated to redirectUrl itself as a workaround, remove that code. Closing the editor with × still reports 'Cancelled'. See Result actions.

• getInitializing() rejects when initialization fails. It used to never settle. It now rejects for an invalid or missing API key or API URL, a failed customer initialization, a browser without localStorage, or an editor script that can't be loaded (404, Content Security Policy). If you await it, add a try … catch. The data-td-script-init-failed-callback and the userInitFailed event still fire, and a rejection nobody waits for doesn't cause an "unhandled rejection" error. See Loading the integration script.

• printJob events of proofreadings and the final confirmation. Generating a proofreading fires created only when the print job doesn't exist yet (not opened in Edit mode, not saved earlier in the session); for an existing print job it fires no print job event. The final confirmation fires updated when the print job already exists — also in a Create session after an earlier save (e.g. a proofreading) — so updated is no longer limited to Edit mode. Save / SaveAndClose are unchanged (updated in Edit mode, else created). All events of a session carry the same printJobGuid: if you listened only to created, also listen to updated, and keep upserting by printJobGuid. See Events and callbacks.

• Closing an editor no longer removes other editors. Only the closed editor is removed (for a dialog also the overlay and the scroll lock). Inline editors in different containers and a dialog can be open at the same time. See Dialog and inline display.

• A second dialog is ignored. Opening a dialog while one is open, or opening into a container that already contains an editor, is ignored with a console warning.

• unsubscribeDesignerEvent(callback) removes every subscription of the function, not only the first one. Callbacks from data-td-*-callback attributes are subscribed as the global function itself, so unsubscribeDesignerEvent(window.myCallback) removes them too.

• setCustomer() keeps the current customer. The script now sends the current customer GUID. Without customerIdentity, setCustomer() updates the current customer — it used to create a new, empty customer on every call. With a customerIdentity that isn't known yet, an anonymous current customer gets the identity, so the logos and print jobs the visitor created before logging in stay with them. An existing identity still switches to that customer, and a customer that already has a different identity is never taken over (a new customer is created). If you called setCustomer() without an identity to start a fresh customer, clear localStorage instead (see Forget the customer on logout). Also: before initialization setCustomer() rejects with an Error (it threw a TypeError), and logo visualizations on the page refresh when the customer's logo changes. See Customers and orders.

• The last product setter decides the data mode. setExactProduct(), setPartialProduct() and the setOwn… setters always set their data mode; addExactPrinting(), addExactPrintings() and addOwnPrinting() set one only if none is set yet. Before, the first call won, so addExactPrinting() followed by setPartialProduct() gave Exact; now it gives Partial. setOwnEmptyProduct() also removes a product set before. See JavaScript builder API.

• Breaking for TypeScript: subscribeDesignerEvent('logo', 'created', cb) passes DesignerEntityEvent<ILogoDTO>; 'updated' and 'deleted' have their own overload with DesignerEntityEvent<undefined> (there's no detail; call getLogo() if you need the logo). Code that read event.detail for these two events may no longer compile.

• addPrintingToPrintJob() has a new last optional parameter maxAreaOverride, like addExactPrinting().

• Breaking for TypeScript: IPrintJobDto.created and updated are typed string (ISO 8601) instead of Date. At runtime they always were strings.

• Redirects follow only http(s) URLs. A redirectUrl (result action, SaveAndClose, …) with another scheme, such as javascript:, is ignored and logged as an error. Relative URLs still work. See Result actions.

• Token links take the full editor arguments. options of POST /api/integration-site-links/generate-open-editor-link now accepts everything EditorArguments supports (result action and buttons, printJob.customer, custom properties, logos, printing display names, own-product data, Missing, OpenGallery/OpenUpload); before, these fields were dropped. A customer next to printJob and printing overrides are still accepted and moved to printJob.customer and the *Display* fields — also in links created before. New validation: returnUrl and editor.result.redirectUrl must be absolute http(s) URLs, otherwise the request fails with a validation error. See Integration via URL.

• The Integration Site opens the returnUrl of a token link when the editor closes (before, it was stored but never used), and opens the editor for the customer in printJob.customer (customerIdentity, name, company, e-mail). The redirectUrl query parameter is not supported; links with apiKey/options parameters show This window can be closed now as before.

• Editor buttons need labels. setEditorButtons() and addEditorButton() throw an Error for a button without labels or with a label that has no language or text. See Editor buttons.

• A stylesheet that can't be loaded closes the editor with the reason 'Error' (and a console error), for example a wrong ownCssVariablesUrl. Before, the editor stayed empty.

• TypeScript: the interfaces now declare the optional options parameter of openSinglePrintTaskDesigner() (DesignerOptions, default { mode: 'dialog' }), setOwnProductSingleVariant() (showQuantityInputs) and setOwnProductTwoDimensions() (AddProductOptions).

• The Developer Portal has a new site: full-text search across guides and the API reference, separate navigation for guides and reference, code samples in tabs and a dark mode. Page addresses changed, for example documents/Events_and_callbacks.html is now documents/Events-and-callbacks.html and interfaces/website-integration.IWebsiteIntegration.html is now website-integration/interfaces/IWebsiteIntegration.html. The old addresses redirect to the new ones, but update your bookmarks and links.

Fixed

• data-td-own-product="true": an element with data-td-action and data-td-own-product (no other product attributes) is now registered and opens the editor in Own mode, where the customer enters the product. Combined with supplier, product or printing attributes, own product wins: those attributes are ignored with a console warning (before, the editor opened in Own mode without a product model and crashed). The editor also asks for the product when Own mode arguments have no product model. See HTML data attributes.
• 'Dialog' result action without closeDialog no longer breaks the editor: the built-in, translated "print job saved" texts are shown. closeDialog is optional, and an entry without language no longer causes an error.
• Logging: debug messages are written only at the log level debug (the default is warn), including the translation library's own debug output. There's no longer a false "logLevel undefined is not allowed" warning when data-td-log-level is missing, and no stray console output each time the editor opens.
• setLogLevel() with an unknown value logs an error and keeps the current level; it no longer breaks later calls.
• Element monitoring (data-td-monitored-element-id, subscribeElementChanges()): changes that also add text or comment nodes (innerHTML, insertAdjacentHTML() …) now register their action elements.
• openDesigner() with editor arguments without openMode or printJob (for example a flat data-td-options object from older documentation) logs an error and does nothing, instead of leaving an empty overlay on the page.
• Opening the editor before the script is initialized, or after a failed initialization (openDesigner(), open(), openLogoGallery(), openLogoUpload(), openSinglePrintTaskDesigner()), logs an error and does nothing, instead of leaving an empty overlay and a scroll lock on the page.
• If the <trondesigner-editor> element isn't defined yet when the editor is opened, the script waits for it (up to 10 seconds) and then opens the editor; if it never gets defined, it logs an error and adds nothing to the page.
• An exception thrown inside your data-td-script-initialized-callback or data-td-script-init-failed-callback is logged and no longer affects getInitializing().
• Events: subscriptions added after openLogoGallery() / openLogoUpload() (for example to logo selected) are no longer skipped; the script's internal logo selected handler no longer stays subscribed when the logo dialog is cancelled; a callback that throws no longer stops the other subscribers (the error is logged).
• An unknown open mode (such as "CREATE") logs an error and closes the editor with the reason 'Error', instead of silently opening the logo upload dialog.
• The SaveAndClose custom button closes the editor (with 'Confirmed' and the redirect) only when the print job was saved. If saving fails, the editor stays open.
• Logo visualizations: an image that had no visualization renders again when you change its attributes; when there is no visualization, the original image (including its srcset) is shown again; an <img> appended directly to the page is detected.
• Print job data in the printJob events and from getPrintJob() now includes comment of the print job and of each printing.
• Token links (Integration Site) created without expiresAt can be opened; they don't expire. Valid token links could also be rejected with Link is no longer valid because of a library version conflict on the Integration Site.
• Integration Site simple links: showQuantityInputs=true and alwaysShowImageSelect=true are applied.
• REST API: an unknown printJobGuid (or one of another instance) returns 404 Not Found; before, it returned 400 with the message Print job with guid … not found. If you checked for 400, also handle 404.
• REST API: GET /api/print-jobs/{printJobGuid}/proofreading/{proofreadingGuid} requires the TronDesigner.PrintProofreadings.Read permission, like …/proofreading/last and …/proofreading/list (it required TronDesigner.PrintJobs.Read).
• printJob.logo is applied in Own data mode and to printings added in Edit mode (before, only to new print jobs in Exact and Partial mode). See Logos.
• Edit mode: re-adding a variant that is already in the print job without quantity or overrides keeps its saved quantity and displayed code (they were cleared). See Open modes.
• Own data mode: print option names come from printPositionDisplayName / printTechnologyDisplayName (the editor still read the removed printing overrides), and fall back to the codes.
• Own data mode: model.dimensionsCount is checked — when it's set and a variant has a different number of dimension values (dimension1Title, dimension2Title), the editor stops with an error that names the variants.
• A print job created in Own data mode can be opened again in Edit and View mode (it failed with No products found).
• Closing the Manual print mockup setup dialog with × no longer causes an unhandled promise rejection.
• Webhooks documentation corrected: X-Webhook-Event carries the event GUID, not the event name, and the event name isn't sent at all (use one endpoint per event if you need it). Deduplicate on X-Webhook-Delivery; X-Webhook-Id changes with every attempt. See Webhooks.
• Admin Portal: the webhook delivery Resend action is available to every user who can change settings (TronDesigner.Settings.Update); it was shown to PromoTron support only. The backend now also requires Settings.Update for it (it accepted Settings.Read).
• Editor buttons (editor.buttons or the Admin Portal) with an empty labels list or an unsupported language code no longer crash the editor: such labels are skipped with a warning and the button shows a default caption.

2026-10 — Developer Portal

Developer documentation moved here

The developer guides moved from the old help center (help.promotron.com, which is being retired) to this portal and were checked against the source code and the examples. Update your bookmarks:

Old help-center article	New page
Introduction	Integration concepts
Quick Start	Quick start
Web Integration Script, API (Website Integration)	Loading the integration script
Data Attributes	HTML data attributes, Data attributes reference
JS Methods	JavaScript builder API and the API reference (Modules in the sidebar)
Editor Arguments	Editor arguments
Integration via URL	Integration via URL
Editor Calling Modes	Data modes
JS Event Subscriptions	Events and callbacks
Session Tracking & Identifiers	Customers and orders
Debugging	Debugging and error handling
Integration Recipes	Integration recipes
REST API	REST API
Webhooks	Webhooks

Business and user documentation (overview, integration scenarios, glossary, editor user guide) is on the PromoTron support site.

The examples were corrected at the same time and now link to these guides. If you copied code from them before, compare it with the current version — for example result actions in PascalCase ('Close'), { mode: 'container', container } for inline display, builder chains that end with open(), and onClose('Error') instead of .catch() on openDesigner().

Removed: EditorArguments.editor.features (Breaking for TypeScript)

The editor.features property and the EditorFeature type were removed from the editor arguments contract (@promotron/editor-types). The editor never applied them.

• Runtime: no change. A features array in your JSON was ignored before and is still ignored.
• TypeScript: code that sets editor.features or imports EditorFeature no longer compiles — delete it.
• What to use instead: editor features are controlled by your license and by Admin Portal → Settings → Print editor → Behavior.

Documentation corrections

The old help-center articles contained these errors. If you copied code from them, check it against this table:

Old docs said	Correct
data-td-options-supplier-code, data-td-options-product-code, data-td-options-position-code, data-td-options-technology-code	data-td-supplier-code, data-td-product-code, data-td-print-position-code, data-td-print-technology-code — no options-, and positions/technologies are print-position / print-technology. data-td-options alone is the attribute for a complete JSON configuration.
printJob.product, printJob.printings	printJob.addProducts, printJob.addPrintings
Printing overrides.printPositionCode / printPositionName / printTechnologyCode / printTechnologyName	printPositionDisplayCode, printPositionDisplayName, printTechnologyDisplayCode, printTechnologyDisplayName directly on the printing
closeDialog: { title, message, buttonText }	An array with one entry per language: closeDialog: [{ language: 'en', title, message, buttonText }]
Own mode: dimCount, dim1Title, dim1Colors	dimensionsCount (on model), dimension1Title, dimension1Colors (on each variant; likewise dimension2…)
printings[n].overrides.maxColors / maxWidth / maxHeight	Directly on the printing: { printPositionCode, printTechnologyCode, maxColors, maxWidth, maxHeight }
printings[n].mockup.backgroundUrls	ownBackgroundUrls directly on the printing — there's no mockup object
openMode: "CREATE" / "EDIT" / "VIEW", dataMode: "PARTIAL"	PascalCase: 'Create', 'Edit', 'View' and 'Exact', 'Partial', 'Own'
The event payload is in event.data	event.detail — e.g. const { printJobGuid } = event.detail;
Script URL https://integration.trondesigner.com/js/website-integration.js	https://app.trondesigner.com/js/website-integration.js — the other URL returns 404
getPrintJobs()	getPrintJob(printJobGuid)
data-td-customer-guid, setUser() / getUser()	Don't exist. Identify customers with data-td-customer-identity (and the other data-td-customer-* script attributes) or setCustomer() / getCustomer(); the customer GUID is kept in localStorage under tron-designer-customer.
An HTTP client (get / post / put / delete) on window.tronDesigner	Doesn't exist. Call the REST API from your server.
Webhook events such as PrintJobCreated	logo.created, print_job.created, print_job.updated, proofreading.created, print_data.created
Editor links via POST https://api.trondesigner.com/api/integration-site-links and https://app.trondesigner.com/editor?token=…	POST https://api-v1.trondesigner.com/api/integration-site-links/generate-open-editor-link; open the link it returns (see Create an editor link)
REST paths /print-jobs/{guid}/thumbnail, /print-jobs/{guid}/proof	/api/print-jobs/{printJobGuid}/{printingGuid}/{variantGuid}/preview-image, /api/print-jobs/{printJobGuid}/proofreading/last (see Endpoints)

All renamed editor-argument fields are listed in Editor arguments.

Also newly documented: data-td-script-init-failed-callback, the logo selected event, both unsubscribe methods (unsubscribeDesignerEvent(callback) and unsubscribeDesignerEvents(entityType?, eventType?)), and refreshRegisteredElements().