Quick start

This page gets you from zero to a working editor on your own page: one <script> tag, one button, and a callback that gives you the print job GUID back. It takes about five minutes and is the fastest way to check that your API key and allowed domains are set up correctly.

TIP

Examples: Quick Start · source — Attributes - Overview · source

Before you start

You need:

• A TronDesigner license with access to the Admin Portal. To use the editor on your own website (outside the PromoTron platform), the license must include the Web Integration feature.
• A website integration API key. Create it in the Admin Portal under Settings → API Keys, tab Website Integration API Keys.
• Your domain in the key's allowed domains. Enter host names only — shop.example.com, or localhost for local testing — without https://, port or path. A page is accepted when its host name is an allowed entry or its subdomain, so example.com also covers shop.example.com. Use a separate key for testing: localhost doesn't belong on a production key (see Allowed domains).
• A product to design on: a supplier code, a product variant code, a print position code and a print technology code. Supplier codes are the codes set up in the Admin Portal under Settings → Suppliers. The samples below use PFC / 10086021 / front / PAD03 (PF Concept product Oregon 400 ml, red). Replace them with codes from your catalog.

NOTE

Serve the test page from a web server (for example http://localhost:8080), not by opening the file from disk. The API checks the page's host name, and a file:// page has none, so initialization fails.

1. Add the script

Add the integration script to the <head> of your page and replace {API_KEY} with your key:

<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}"
></script>

The script creates the global object window.tronDesigner, identifies the visitor as a TronDesigner customer and loads the editor. In the Admin Portal's API key list, the Copy to clipboard with integration script button next to a key copies this tag with the key filled in.

2. Add a button

The quickest option needs no JavaScript: put data-td-* attributes on a button. If you prefer JavaScript, use the builder API on window.tronDesigner instead. Both tabs below open the same editor.

HTML attributes

<button
  type="button"
  data-td-action="OpenCreate"
  data-td-supplier-code="PFC"
  data-td-product-code="10086021"
  data-td-print-position-code="front"
  data-td-print-technology-code="PAD03"
>
  Design your print
</button>

JavaScript builder

<!-- Add data-td-script-initialized-callback="onTronDesignerReady" to the script tag from step 1. -->
<button type="button" id="design-button" disabled>Design your print</button>

<script>
  // Called by the integration script when it is ready. Must be a global function (not a const).
  function onTronDesignerReady() {
    const button = document.getElementById('design-button');
    button.disabled = false;
    button.addEventListener('click', () => {
      window.tronDesigner
        .setExactProduct('PFC', undefined, (product) => product.addVariant('10086021'))
        .addExactPrinting('front', 'PAD03')
        .open({ mode: 'dialog' });
    });
  }
</script>

Open the page and click the button. The editor opens as a full-screen dialog over your page with the product and print area preselected.

• With HTML attributes, the script finds the button once it has finished initializing and attaches a click handler. See HTML data attributes for every attribute and valid combination.
• With the JavaScript builder, you chain setExactProduct(supplierCode, supplierGuid, …) and addExactPrinting(positionCode, technologyCode), then call open(). See the JavaScript builder API.

3. Get the print job GUID back

When the customer saves their design, the editor creates a print job. Store its GUID with your cart item or order: you need it to reopen the design and to download preview images and print data later.

Point data-td-print-job-created-callback on the script tag at a global function, or subscribe from JavaScript:

Script attribute

<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-print-job-created-callback="onPrintJobCreated"
></script>

<script>
  function onPrintJobCreated(event) {
    console.log('Print job created:', event.entityGuid, event.detail);
  }
</script>

JavaScript

// Call after the script is initialized, e.g. inside onTronDesignerReady().
window.tronDesigner.subscribeDesignerEvent('printJob', 'created', (event) => {
  console.log('Print job created:', event.entityGuid, event.detail);
});

The callback receives a DesignerEntityEvent: entityGuid is the print job GUID and detail contains the print job data. All events and their payloads are described in Events and callbacks.

If the editor doesn't open

Open the browser developer tools (F12). Most first-time problems show up in the console, or in the failed (401) customer/init request on the Network tab:

Message contains	Cause
API key is invalid: Domain … is not allowed	The page's host name isn't in the key's allowed domains.
API key is invalid: Provided API key is not valid	Wrong or deleted key.
Web Integration feature for TronDesigner license is required…	The license doesn't include website integration.
cannot initialize element for action: openDesigner - missing required data props	The button is missing an attribute, or has an invalid combination.

To react to a failed initialization in your page (for example, hide the button), use data-td-script-init-failed-callback, or catch the rejection of await window.tronDesigner.getInitializing() — see Loading the integration script. More checks are in Debugging and error handling.

That's it: the editor runs on your page and you get the print job GUID back.

Next steps

• Loading the integration script — all script tag attributes and the initialization sequence.
• Integration concepts — launch methods, data modes, open modes and results.
• Integration recipes — copy-paste snippets for product pages, carts and order detail pages.
• Webhooks and the REST API — receive and download print jobs on your server.

See also

• window.tronDesigner — API reference
• Data attributes reference
• Examples