Session Tracking & Identifiers

This page explains how your application identifies users, orders, and sessions.

The TronDesigner Editor relies on metadata to bind a design session to your customer, your order, and your internal systems. This page explains how these identifiers work, how to pass and override them.

Core Identifiers Overview

Identifiers are grouped into three categories based on their purpose and how they persist in the system:

Group

Key Fields

Purpose

Persistence

Customer

customerIdentity, customerEmail

Identifies the unique user profile.

Permanent. Tied to the user's cloud-stored Logo Gallery.

Order

orderCode,
orderItemCode

Links the design to a transaction.

Print Job Only. Saved only within the resulting design file.

Custom

customProperties
(JSON)

Your internal metadata (IDs, flags, markers).

Passthrough. Stored in the Print Job and returned to you.

Customer Identity & Global Context

These properties define who is using the editor. Setting these globally ensures that every time the Editor opens, it knows which logo gallery to load.

The Identity Rule: The customerIdentity (and the resulting customerGUID) is used to load the user's personal Logo Gallery. Always provide a consistent ID (e.g., your Primary User Key) to ensure the customer sees their previous uploads every time they return. If you change this, the user loses their uploaded logos.

Properties:

  • customerIdentity: Your internal unique ID for the user (required for gallery persistence).

  • customerPerson: Full name of the user.

  • customerEmail: User's email address.

  • customerCompany: Company name.

TronDesigner generates a unique CustomerGUID based on the customerIdentity you provide. This GUID is used to identify users across sessions, enabling:

  • Logo gallery persistence: Users see their uploaded logos every time they return.

  • Personal assets: Access to previously used designs or images.

  • Audit & tracing: Tracking user activity for support or analytics.

  • Consistent identification: The user stays "logged in" across multiple different product pages.

Setting via HTML Data attributes

Add these to the main integration script. This is ideal for static user sessions.

Example
<html>
  <head>
    <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-customer-identity="1234567890"
      data-td-customer-person="User A"
      data-td-customer-company="Company"
      data-td-customer-email="userA@company.com"
    ></script>
  </head>
  <body>
    ...
  </body>
</html>

Setting via JS API

setCustomer(user) re-runs the customer initialization with new data. Use this for Single Page Applications (SPAs) where the user might log in after the page has loaded.

Example
//// Updates the global context for all future editor sessions
window.tronDesigner.setCustomer({ 
  customerEmail: "userA@company.com", 
  customerIdentity: "1234567890",
  customerPerson: "User A",
  customerCompany: "Company" 
});

getCustomer() returns the currently stored CustomerDTO from initialization. This is useful if you need to verify which user context the Editor is currently using before opening a session.

Example
const customer = window.tronDesigner.getCustomer();

Reinitialization Behavior When setCustomer() is called, the Editor context is reset. Note the following behavior:

  • Identity Shift: If a different customerIdentity is provided, a new CustomerGUID will be generated, and the user will switch to a different Logo Gallery.

  • Storage Sync: The browser's Local Storage is immediately updated with the new identity to maintain the session through page refreshes.

  • Session Readiness: The new customer context is applied instantly to the next Editor session (the user does not need to reload the page).

Overriding customer data for a print job

When creating a print job, it is possible to override the customer data without saving them to customer local storage and the TronDesigner back-end. They will only be used in this particular print job.

Use this when you want to label a print job with specific data (e.g., a specific shipping branch) without permanently changing the User's profile in TronCloud.

Override of customer properties is only possible via the JavaScript API:

Example
window.tronDesigner.openDesigner({ 
  ...restOfEditorArgs,
  customer: { 
    customerIdentity: "...", 
    customerEmail: "john@company.com" 
  } 
});

Order Identifiers

These values link a specific design (Print Job) to a business transaction (a shopping cart item, a quote, or an ERP order). They do not affect the user's profile.

  • orderCode: Your primary order ID.

  • orderItemCode: The specific line item in the cart.

  • orderTitle: A human-readable label for the design.

Example
window.tronDesigner.openDesigner({ printJob:{
  customer: { 
    orderCode: "ORD-2024-15151", 
    orderItemCode: "ITEM-002", 
    orderTitle: "Sport Bottle 10000200" } 
}});

Custom Properties

Custom properties are "passthrough" metadata. TronDesigner does not process them; it simply stores them and returns them to you when the design is finished.

customProperties is a container, in the HTML attribute, you have to pass it as a JSON string.

Example
customProperties: { 
  key1: "value1", 
  key2: "value2" 
}

  • Custom properties are returned unchanged.

  • Use them to store your own metadata, flags, session markers.

  • Useful for internal routing or tracking.

Passing custom data to the Editor

Example
window.tronDesigner.openDesigner({
  printJob: {
  /* ...rest of properties */
  customProperties: { 
    cartLineId: "CL-882",
    campaign: "SPRING24",
    region: "EU"
  } 
}});

What you get back When the user finishes the design, the onSave or onOrder callback (and your configured Webhooks) will include these exact IDs. This allows your backend to automatically match the print-ready file to the correct order line.

Example
// Returned unchanged via JS event / webhook:
{
  printJobGuid: "...",
  customProperties: {
    cartLineId: "CL-882",
    campaign: "SPRING24",
    region: "EU"
  }
}

Next Steps