Input

  • Last updated on April 4, 2025
  • •
  • 7 minutes to read

The input object contains product properties for loading the editor. These properties allow you to retrieve products defined in Customer's Canvas in various ways. Let's take a look at them.

Conceptually, all types of inputs can be divided into the following:

  • For opening designs without PIM
  • For initialization using PIM data
  • For recovery scenarios
Note

If data in the input object is sufficient to initialize two or more scenarios, the first available scenario will be applied. At the same time, a warning will be logged to the console.

Working without PIM

Public template and mockup

Use this scenario when PIM integration is unnecessary. That is, when you need to work directly with templates and mockups to group them into products or you may not implement an e-commerce scenario at all.

You can load an editor based on public data stored in your tenant. If needed, upload only a design template by its designTemplateId. You can also specify preview mockups in this definition. 3D mockups will be displayed in the viewer, and 2D mockups will appear on the approval screen. Depending on the mockup type, pass mockup3dId with a single ID or previewMockupIds with an array of IDs. These mockups must be saved in public storage.

The input object for providing public designs and mockups has the following properties:

  • designTemplateId is the ID of a template stored in Assets > Designs. It's mandatory.
  • previewMockupIds is an array of mockup IDs for the approval screen from Assets > Images.
  • mockup3dId is a 3D mockup for the viewer from Assets > Mockups. It's passed only to <au-handy-editor-3d />, and if not specified, the 3D viewer will not be initialized.

A sample input of the Handy Editor with 2D preview mockups for the approval screen:

const input = {
    // ID of a template stored in assets, mandatory.
    "designTemplateId": "61cd31a43056bcc33e919927",
    // Array of mockup IDs for the approval screen from Images.
    "previewMockupIds": ["643d05f7c121897df4598271", "643d05fbc121897df4598277"] 
};

A sample input of the Handy Editor 3D with mockups for the viewer:

const input = {
    // ID of a template stored in assets, mandatory.
    "designTemplateId": "61cd31a43056bcc33e919927",
    // 3D mockup for the viewer from Mockups.
    "mockup3dId": "6527afc63507abfadd355226"
};

Private design and mockup

When the user has already edited a design template, the personalized design is saved in this user's private storage. If a design was generated through the Asset Generator service (parametric design use cases), it's also saved in private storage.

To access private storage, you will need the ID of the user who created the design and that user's token. Then, you can open the editor using the design ID.

You can also specify preview mockups in this definition. 3D mockups will be displayed in the viewer, and 2D mockups will appear on the approval screen. Depending on the mockup type, pass mockup3dId or previewMockupIds. We assume that these mockups are private.

The input object for providing private designs and mockups has the following properties:

  • designId is the ID of a design personalized by a user.
  • mockup3dId is a private 3D mockup generated for the viewer through the AssetGenerator API.
  • previewMockupIds is an array of mockup IDs for the approval screen.

This is how the input object may look like:

const input = {
    "designId": "66bcc31cd39271a43cc3e919",  // ID of a design personalized by a user.
    "mockup3dId": "6527afc63507abfadd355226" // Private 3D mockup generated for the viewer.
};

Working with PIM

Product reference

If you integrate Customer's Canvas with a standard e-commerce platform, like Shopify, you can load the editor based on a product ID from that system. In this scenario, Customer's Canvas uses the external product ID to link the product, as described in the Connecting products to an e-commerce system article.

To load an editor, pass the productReferenceId to the input:

  • productReferenceId is a product ID in an e-commerce system.
  • designVariantFilter applies additional filtering to designs, for example, by file name or by SKU.

This is how you can define the input object to bind external products from a standard e-commerce system to Customer's Canvas products:

const input = {
    "productReferenceId": "8255218868440", // External product ID.
    "productId": "414"                     // Customer's Canvas product ID.
};

PIM data

Use this approach with custom e-commerce integrations, when an external system knows the product ID from Customer's Canvas PIM module. In this case, you create products in Customer's Canvas and receive a list of products in the admin panel of your store. No product link is required here.

The input object has the following properties:

  • productId is a product ID in Customer's Canvas.
  • productVersionId is a number of the saved product instance.
  • productVariantId is a product variant ID. If skipped, all the variants will be obtained for managing in your application.
  • productFilterId is a filter ID to apply to the obtained product variant list.
  • designVariantFilter applies additional filtering to designs, for example, by file name or by SKU.

To load an editor, pass the productId and productVariantId to the input.

const input = {
    "productId": 114,         // Product ID in Customer's Canvas.
    "productVersionId": 1011, // Number of the saved product instance.
    "productVariantId": 22698 // Product variant ID.
};

Filtering designs

You can apply additional filtering to designs, for example, by file name, by folder, or by SKU.

The designVariantFilter used in the input supports the following filter types:

  • search is a file name substring.
  • designCustomFields is an object with key-value pairs defining a custom field with a required value.
  • designPath is a substring of the folder path in asset store.
  • options is an object with key-value pairs defining an option ID with an option value ID { opt_id: opt_value_id }.
  • sku is the product variant SKU.

This is how you can filter designs for a product variant by name and by custom fields.

const input = {
    "productId": 114,
    "productVariantId": 22698,
    "designVariantFilter": {
        "search": "card",                        // Filter by file name containing "card".
        "designCustomFields": {"public": "true"} // Filter by custom fields.
    }
};

Recovery strategies

Recovery scenarios are necessary when you need to restore the state of selected PIM options, design, and changes made to that design. This may be required in cases such as:

  • Returning to editing from the cart.
  • Complex scenarios where a template is edited in multiple editors sequentially.
  • When a design was created using the API from variant resources.

Recovery scenarios are necessary if you need to open a design in the editor that was created in an external system based on PIM data or to reopen a design previously created in it.

Note

In recovery scenarios, the productVersionId field is always mandatory. If missing, the editor will open the latest version of the product, which may not match the version in which the design was created.

Recovery using SKU

Recovery interface:

const input = {
    "sku": "product-sku", // SKU of the product variant.
    "designId": "private-design-id", // Private design ID.
    "productId": 123, // Product ID.
    "productVersionId": 456, // Product version ID.
    "productLinkId": 789, // Optional: Product link ID.
    "designVariantTemplateId": "public-design-id" // Optional: Public design ID from which the Design Variant was created.
};
Note

This scenario is not suitable for cases where different PIM variants reference the same SKU in the external system.

Recovery using variant ID

Recovery interface:

const input = {
    "productVariantId": 123, // Product variant ID.
    "designId": "private-design-id", // Private design ID.
    "productId": 456, // Product ID.
    "productVersionId": 789, // Product version ID.
    "productLinkId": 1011, // Optional: Product link ID.
    "designVariantTemplateId": "public-design-id" // Optional: Public design ID from which the Design Variant was created.
};

Note on the designVariantTemplateId field

The optional field designVariantTemplateId is used to indicate to the editor from which design variant the provided designId was created. Currently, the Handy Editor does not use this information, but it may be necessary to indicate the selected design variant in the user interface, similar to the Simple Editor.

If you initialize the editor with a template previously created in the Handy Editor, you can pass the event.detail.designVariantTemplateId field from the add-to-card event.

If you created the design via the API, you can use the information from the /api/storefront/v1/products/{id}/variant-designs endpoint. The designId field of the variant you need is what you require for this case.

Was this page helpful?
Back to top Copyright © 2001–2024 Aurigma, Inc. All rights reserved.