JavaScript API

All methods are exposed through the global window.tronDesigner object. This API allows you to control the editor, manage user identity, and interact with the TronDesigner backend directly from your frontend.

• For handling Editor output see: JS Event Subscriptions.

• For all methods reference see: Methods (auto-generated).

Global integration object

Once the Web Integration Script is included on your page, it automatically initializes a global object: window.tronDesigner.

Example
Web Integration Script
Copy
<script
  async
  src="https://app.trondesigner.com/js/website-integration.js"
  data-td-api="https://app.trondesigner.com/api"
  data-td-api-key="{API_KEY}"
></script>

This object serves as your primary interface (implementing IWebsiteIntegration) and provides access to all core methods needed to interact with the Editor:

• openDesigner(...): Launch the editor UI.

• subscribeDesignerEvent(...): Listen for specific user actions, e.g. Print Job updates.

• setCustomer(...) / getCustomer(): Manage user identity and sessions.

• setLogLevel(...) / getLogLevel(): Control console debugging output.

Safe Initialization

Because the script loads asynchronously (async), you must ensure window.tronDesigner is fully initialized before calling its methods. You have three ways to handle this:

Initialization Callback (Global)

Specify a global function in the initialization callback attribute. The script will execute this function as soon as it is ready.

<script 
  async 
  src="https://app.trondesigner.com/js/website-integration.js" 
  referrerpolicy="origin" 
  data-td-api="https://app.trondesigner.com/api" 
  data-td-api-key="{API_KEY}" 
  data-td-script-initialized-callback="onTronDesignerReady"
></script>

<script> 
  function onTronDesignerReady() { 
    // window.tronDesigner is now available 
  } 
</script>

Using Promises (Modern JS/Frameworks)

Alternatively, if you are using a modern framework, or just prefer using async/await, you can use the built-in promise instead of a global callback function:

• getInitializing(): Returns a promise that resolves when initialization process is complete.

Status Check (Manual)

If you need to check the status immediately (for example, inside a button click handler), use the boolean check:

• getInitialized(): Returns true if the tronDesigner object is ready; false if it is still loading.

openDesigner (data, options)

The primary method to launch the TronDesigner Editor. It accepts two distinct configuration objects: one for the content and one for the display.

openDesigner(data: EditorArguments, options: DesignerOptions)

Data

EditorArguments. The payload that defines what the Editor loads and how it behaves internally. For a full list of properties see the Editor Arguments article or Full Reference.

• openMode / dataMode: Instructions on how to open the Editor.

• editorOptions: Controls specific UI features within the Editor.

• printJob: The main product and design structure.

Options

DesignerOptions. Controls how the Editor window is rendered on your website and its closing behavior. By default, it opens the Editor in a dialog overlay (modal) on top of your website.

Dialog. Basic and default usage (dialog overlay).

window.tronDesigner.openDesigner({
  supplierCode: "PFC",
  productCode: "10000200",
  printPositionCode: "FRONT",
  printTechnologyCode: "PAD03"
}, {
  mode: "dialog" // default display mode
});

Container. Embedded in a container, HTMLElement is mandatory for this case.

const container = document.getElementById("designer-container");

window.tronDesigner.openDesigner({
  supplierCode: "PFC",
  productCode: "10000200"
}, {
  mode: "container",
  container: container
});

onClose Callback (Client-Side Exit Handling)

While you can track specific milestones using JS Events, the onClose callback is the most direct way to handle the moment a user leaves the editor.

Key Distinction: This is a parameter passed directly into the options object of openDesigner, not a global event subscription.

When it triggers:

• Success: The user clicks Continue / Confirm.

• Cancellation: The user clicks Close / Cancel.

• System: The Editor is closed programmatically by your own script.

window.tronDesigner.openDesigner(
  { /* data: EditorArguments */ },
  {
    // The callback is defined here inside the options object
    onClose: (reason, redirectUrl) => {
      console.log(`Editor closed. Reason: ${reason}`);

      // Example: If the user confirmed their design, 
      // you might want to redirect them to the checkout.
      if (reason === 'confirmed' && redirectUrl) {
         window.location.href = redirectUrl;
      }
    }
  }
);

Callback Parameters:

• reason: A string indicating why the Editor closed (e.g., 'confirmed', 'cancelled', or 'error').

• redirectUrl: (Optional) A URL provided by the Editor, often used in webshop flows to lead the user to the next step (like a cart or summary page).

Event Subscription & Cleanup

To react to user actions — such as saving a design or clicking the "Buy" button — you need to register listeners.

• subscribeDesignerEvent(entity, event, callback): Starts listening for a specific milestone. It is best practice to subscribe before calling openDesigner.

• unsubscribeDesignerEvent(entity, event, callback): Stops listening for a specific milestone. Use this to prevent memory leaks or duplicate triggers once the designer is closed.

• unsubscribeDesignerEvents(): A "global reset" that removes all active listeners at once.

• For detailed explanation please refer to JS Event Subscriptions article.

Data & Utility Methods

These methods allow you to manage user sessions, troubleshoot your integration, and retrieve design data.

Identity Management

Linking a customer ensures that their uploaded logos and design history are saved to their specific account.

• setCustomer(customer): Initializes or overrides the customer context used for tracking, logo gallery. This also maps the session to a specific user (using their email or external ID)
  

  window.tronDesigner.setCustomer({ 
    customerPerson: "User 123",
    customerEmail: "john@company.com",
    customerCompany: "Example Corp",
    customerIdentity: "user-123"
  });

• getCustomer(): Returns the current CustomerDTO (customer identity). This is useful for retrieving the customerGUID to link a design to an order in your database. NULL is returned if none is initialized.
  

  const customer = window.tronDesigner.getCustomer();
  
  if (customer) {
    console.log("Current TronDesigner customer:", customer.customerGUID);
  }

• See more in Session Tracking & Identifiers.

Logging

Manage the verbosity of the browser console to help with development and troubleshooting.

• setLogLevel(level): Change the log level at runtime: (The default level is "warn".)
  

  window.tronDesigner.setLogLevel("debug");
  // allowed values: "debug", "info", "warn", "error"

• getLogLevel(): Read the current level:
  

  const level = window.tronDesigner.getLogLevel(); 
  console.log("Current TronDesigner log level:", level);

• You can set the initial log level directly on the HTML script tag using the data-td-log-level attribute. Use the JS method setLogLevel() later only if you need to change the level dynamically during the session.

• See more in Debugging.

Data access helpers

These methods allow you to call the TronDesigner API directly to retrieve specific files and data structures. All these methods are asynchronous and return a Promise.

Prerequisite: These methods require an active session or a valid printJobGuid. Since they fetch data from the server, they return Promises.

Key Implementation Details:

• Blobs: Since the motive and product images are returned as Blobs, you may need to use URL.createObjectURL(blob) to display them in an <img> tag.

• Optional Variant: For getPrintingImage, if you don't provide a productVariantCode, the system will automatically return the image for the default product variant.

• Identifiers: The printingGuid and productVariantCode can be extracted from the IPrintJobDto returned by the getPrintJob method.

• For example see the sandbox: TronDesigner integration - calling the API endpoints

Advanced Setup & Injection

While openDesigner handles the standard catalog flow, these methods allow you to programmatically control the product state and inject custom data into the session.

Product Initialization

Use these if you need to bypass the standard product selection or if you are selling custom-dimension items. These allow you to "pre-set" or "force" a specific product state before the Editor even opens.

TronCloud Products

• setExactProduct: Locks the Editor into a specific configuration (Product + Color + Size).

  • Parameters: supplierCode and a buildProduct callback.

• setPartialProduct: Used when you have limited info (like an ID) and want the Editor to fetch the remaining metadata.

  • Key Params: supplierCode, buildProduct, and UI options (like showQuantityInputs).

"Own" (Custom) Products

Direct Content Injection

These methods allow you to push specific designs or properties into the session programmatically.

Custom Metadata

Custom properties are key-value pairs that travel with the Print Job. Use these to store internal database IDs or tracking codes that you need returned once the design is finished.

• addCustomProperty(key, value): Adds a single metadata pair.

• addCustomProperties(Record<string, string>): Adds multiple properties at once using an object.

Injecting Print Areas (Printings)

These methods define where and how a user can apply their design.

• addExactPrinting: Injects a specific print position and technology using TronCloud codes.

  • Core Params: printPositionCode, printTechnologyCode.

  • Overrides: You can optionally override the name/code displayed in the UI for both position and technology. See more in the Editor Arguments article.

• addExactPrintings: A batch version of the above to add multiple positions in one call.

• addOwnPrinting: Used for custom products not in the catalog. You define the rules manually.

  • Parameters: positionName, technologyName, colorMode, and physical constraints like maxWidth, maxHeight, or maxColors.

Loading Existing Designs

• setPrintJob(printJobGuid): Bypasses product selection to load a previously saved design session directly.

Task-Specific Designers

For scenarios where you don't need the user to configure a whole product, you can launch a specialized, streamlined version of the Editor.

• openSinglePrintTaskDesigner: This "lite" version of the Editor focuses the user on a single specific task (e.g., just designing the front chest of a t-shirt) across a defined set of variants.

• Parameters:

  • supplierCode: The code of the product supplier.

  • productVariantCodes: An array of specific variants (colors/sizes) to include in this task.

  • printPositionCode: The specific TronCloud mockup position code to be edited.

  • printTechnologyCode: The specific technology allowed for this task.

Result Actions

These methods define the behavior of the Editor immediately after a user successfully saves their design. This allows you to control the "exit flow" of the session programmatically.

• setResultActionCloseEditor: Automatically closes the Editor window or modal as soon as the design is saved. This is ideal for a seamless "back to shop" experience.

  • Parameters: redirectUrl (Optional). If provided, the browser will redirect to this URL after the Editor closes.

• setResultActionShowDialog: Displays a custom dialog to the user before the session ends.

  • Parameters: dialogLocalizations (Required array of localizations) and an optional redirectUrl to trigger after the dialog is dismissed.

• setResultActionNone: The Editor performs no automatic action; the user remains in the Editor and must close it manually.

Advanced: Internal HTTP Client (JS API)

The integration script exposes the same HTTP client it uses internally to communicate with the TronDesigner API. This is a low-level tool for advanced integrations that need to make custom API calls directly from the browser.

Why use the Internal Client?

The primary advantage is that the client handles the "heavy lifting" of the request context automatically. Every request made through this client includes:

• Authentication: Your API Key is automatically attached.

• Identity: The current customer identity (if set via setCustomer) is included.

• Localization: Current language information is passed in the headers (if available).

Available Methods: The client provides standard HTTP verbs: get, post, put, delete.

When to use (and when to avoid)

• Use it if: You are building a custom dashboard inside your site and need to fetch data from TronDesigner without re-implementing authentication logic in your frontend.

• Avoid it for: Sensitive server-side operations or simple design launches.

Usage Guidelines. Because this is a lower-level API, you should:

• Use the REST API from your backend for most server-side operations.

• Use the Full Tech Reference to see the exact type and access pattern for the HTTP client (name, method signatures, request/response DTOs).

Resources

• Full Tech Reference – Auto-generated documentation.

• Web Integration Script – How to integrate the Editor as an overlay.

• Session Tracking & Identifiers – How setCustomer / getCustomer relate to CustomerDTO.

• Debugging – Using setLogLevel and client-side logs while debugging.

• JS Event Subscriptions – Events fired when Print Jobs are created, updated, etc.

• REST API – Backend endpoints for querying print jobs and assets.

• Data Attributes – For HTML-only integrations (no custom JS).