Web Intergation Script

Learn how to embed the TronDesigner Editor directly into your website.

This guide outlines how to integrate the TronDesigner Editor directly into your website using our Web Integration Script. This method allows the Editor to appear as a seamless part of your UI, providing the most interactive experience for your users.

Load the Script

To begin, add the integration script to your website's <head> or before the closing </body> tag. This script initializes the environment and authenticates your session using your API key.

<script 
  src="https://cdn.trondesigner.com/integration-script.js"
  data-td-api-key="YOUR_API_KEY"> 
</script>

Initialization Behavior

Once the script is loaded into the browser, it performs the following lifecycle steps:

  1. Parses configuration from the <script> tag (API key, endpoint, customer identifiers, etc.).

  2. Initializes internal services like the API client, logging, and event subscriptions.

  3. Creates the global object: window.tronDesigner.

  4. Scans the page for elements using Data Attributes (e.g., data-td-action).

  5. Registers click handlers and starts monitoring for new elements.

  6. Executes the on-load callback: Calls the function specified in data-td-script-initialized-callback.

Input: Choosing Your Transport Method

The "Transport Method" is how you deliver the Editor Arguments JSON to the script. You can choose a method based on how much custom JavaScript you want to write.

Which one should you use?

  • Use HTML Data Attributes if you just need to open a standard product from our catalog.

    It is ideal if you control the HTML templates, want a low-code integration, product data is available directly in the markup. Use JS API / Builder if you need to define the product or quantities via JavaScript before opening. This is recommended when data is assembled in JavaScript (configurators, SPAs), you need to compute Editor arguments at runtime, or you want to integrate with other JS logic like the cart, validation, or tracking.

  • Use advanced Full JSON Integration if you need to override names, prices, or define your own technical print specifications. This method typically relies on the JS API to pass the complex, custom-computed JSON payload to the Editor.

See more in Data Attributes article.

HTML Data Attributes (Basic/Demo)

The simplest way to integrate TronDesigner without writing custom JavaScript. This method is best for static sites or standard webshop integrations where you want to turn a regular button into an "Editor Launcher" by simply tagging HTML elements with specific attributes.

  • Best for: Standard product pages, simple e-commerce sites, and e-commerce platforms. Demos, or testing integration, as the method is very limited.

  • Key Advantage: Requires zero coding knowledge — the Web Integration Script automatically detects these buttons and handles the click logic for you.

You can provide data using attributes (Property-by-Property): Each piece of information is its own attribute. This is highly readable and easy to generate from server-side templates.

Example
<button
  data-td-action="OpenCreate" 
  data-td-options-supplier-code="PFC" 
  data-td-options-product-code="10000200" 
  data-td-options-technology-code="PAD03" 
  data-td-options-position-code="FRONT"
>
Open Designer </button>

JavaScript API / Builder (Recommended)

The most robust choice for modern web applications and professional webshop integrations. This method allows you to assemble the payload dynamically based on real-time user selections (like choosing a color or size) and launch the Editor programmatically via a clean function call.

  • Best for: Dynamic product pages, custom portals, and B2B applications.

  • Key Advantage: Provides full programmatic control over the Editor's lifecycle and data assembly on the fly.

  • Recommended for most webshops.

Example
window.tronDesigner.openDesigner({ 
  supplierCode: "PFC", 
  productCode: "10000200", 
  printPositionCode: "FRONT", 
  printTechnologyCode: "PAD03" 
});

Display Options (Where the Editor Appears)

When using the Builder method on your own webpage, you can control the physical placement of the Editor:

  • Dialog Overlay (Default)

    The editor opens as a modal overlay (dialog) on top of your website. This is the recommended and most common mode for the webshops. The dialog is created by the script and is appended to the body of the host website.

    window.tronDesigner.openDesigner({ __data__}, {mode: 'dialog', ...});

  • Embedded container
    The editor is rendered inside a specific <div> element within your layout. This allows the Editor to feel like a "widget" or a native part of your application’s UI. Useful for custom web applications where the Editor must remain within a fixed area of the screen.

    window.tronDesigner.openDesigner({ __data__}, {
  mode: 'container', 
  container: document.getElementById('container')
});

Container option is not available when opening the editor via URL as it always loads the full standalone Editor page.

Full JSON Integration (Advanced)

Maximum control for complex configurations. Instead of using individual properties, you provide the complete Editor Arguments object as a single block. This is required if you are using overrides, custom product definitions, or multiple print areas.

  • Best for: Complex B2B scenarios, ERP integrations, and custom product catalogs.

  • Key Advantage: You can pass the entire finalized payload via either the data-td-options attribute or the JS API.

  • Pro Tip: This method is ideal when you need to pass Custom Metadata that you intend to retrieve later via the REST API for your production workflow.

Example
<button 
  data-td-action="OpenCreate" 
  data-td-options='{ 
    "supplierCode": "PFC", 
    "productCode": "10000200", 
    "printings": [ { 
      "printPositionCode": "FRONT", 
      "printTechnologyCode": "PAD03" } ] }'> 
  Open Designer 
</button>

Output: Handling the Result

Once the user performs actions inside the Editor, you need to capture the result to move them forward in your sales funnel. While JavaScript Events provide the best user experience, a professional integration often combines multiple methods to ensure both speed and data integrity.

Depending on your workflow, you can either wait for the Editor to notify you (Push) or proactively request data from the Editor (Pull).

Push Methods (Active Notification)

These methods "fire and forget." The Editor tells your system that something has happened.

JavaScript Events (Real-time, Client-side)

The script emits browser events that you can listen for. This is the fastest way to update your shopping cart or show a success message.

  • Best for: Instant UI updates and client-side logic.

  • See details: JS Event Subscriptions for the full list of events and payloads.

Webhooks (Server-side)

Webhooks are HTTP POST callbacks sent from TronDesigner’s servers directly to your backend. They act as a safety net for your integration; if a user’s internet drops or they close their browser tab too quickly, the Webhook ensures your database still receives the design data.

  • Best for: Order persistence and backend automation.

  • See details: Webhooks to learn how to set up your endpoint listener.

Pull Methods (On-Demand Retrieval)

These methods are used when your system needs to "reach in" and grab specific information at a time of your choosing.

JS API Methods (Client-side)

Your frontend script asks the integrated Editor for its current state. For example, you can request the current design's metadata or price before the user even clicks "Save." This allows you to validate the design or check the state of the Editor at any moment.

  • Example: window.tronDesigner.getEditorState()

  • See details: JS API Methods for more information.

REST API (Server-side)

The REST API is used after you have received a printJobGuid (via Events or Webhooks). It allows your server to "reach back" into TronDesigner to pull specific data needed for fulfillment or display, such as high-resolution production files.

  • Best for: Secure access to production files and job history.

  • See details: REST API for more information.

Client-Side Reliability: Since JS Events and JS Methods run in the browser, they depend on the tab staying open. If a user saves and closes their laptop instantly, a Push event might be interrupted. We recommend using Webhooks as your primary source of truth for finalizing orders.

Summary Guide: How to proceed

To complete your integration, follow this checklist:

  1. Initialize: Load the Web Integration Script in your HTML with your unique API Key.

  2. Trigger: Decide if you will use Data Attributes (Low-Code) or the JS API Builder / full JSON (Programmatic).

  3. Input: Construct your Editor Arguments payload (defining the Product, Printings, and Modes).

  4. Listen: Set up an Event Listener (Push method) to catch the result in real-time.

  5. Store: Save the printJobGuid returned by the event to your database to link the design to your user's order.

  6. Retrieve: Use a Pull method (REST API) to fetch thumbnails for the shopping cart or high-resolution production files for fulfillment.

Next Steps & Resources

Ready to start building? Explore the technical references below: