Initialization

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

In this article, you'll learn how to integrate the Handy Editor in your storefront and provide the initial data for the supported cases. We will assume that the workflow file contains a single workflow element in a file, handy-editor. If you need a 3D preview of the personalized design, you can only replace this name with handy-editor-3d in the following examples.

Workflow Element	Tag	Script	Styles
Handy Editor	`<au-handy-editor>`	workflow-elements/handy-editor/index.js	workflow-elements/handy-editor/styles.css
Handy Editor 3D	`<au-handy-editor-3d>`	workflow-elements/handy-editor-3d/index.js	workflow-elements/handy-editor-3d/styles.css

When you know that there will be no 3D preview, it is better to load the regular version to increase the speed.

Customers's Canvas supports the following ways to initialize the Handy Editor:

Opening a public design and mockups
Opening a private design and mockups
Opening by a product reference
Opening by PIM data
Recovering an editor session

Prerequisites

Before embedding the Handy Editor on a page, create a product in your Customer's Canvas tenant as described in the Creating products topic.
To configure the editor, create a workflow of the Workflow Elements type as described in the Workflow Elements topic.
To launch the Handy Editor, you need a URL linking to the Workflow Elements library. In the user interface, you can find this link through Settings > Applications > Workflow Elements URL. However, in real applications, get the application URLs by using the endpoint TenantInfo_GetApplicationsInfo.

This URL will look as follows:

https://staticjs-aurigma.azureedge.net/libs/<environment>/workflow-elements/handy-editor

Adding an editor to a page

There are two methods to integrate an editor:

Dynamically as described in the integration basics
Statically as described below

1. Add links to script and styles

Use the base URL from your tenant settings, the component name, and the script file names. To learn how to dynamically add these links, you can refer to the What are Workflow Elements.

<script defer src="https://staticjs-aurigma.azureedge.net/libs/us/workflow-elements/handy-editor/index.js"></script>
<link href="https://staticjs-aurigma.azureedge.net/libs/us/workflow-elements/handy-editor/styles.css" rel="stylesheet" type="text/css">

Here, we have hardcoded the us environment. This is the case when we use a tenant deployed on the USA servers.

Important

The environment of the Workflow Elements must match the environment of your tenant. So, if your tenant is deployed on the European servers, specify eu here. For Australian servers, specify au.

2. Add a tag to the page

When you know in advance the workflow element tag, you can statically add it as follows:

<body>
    <au-handy-editor></au-handy-editor>
</body>

3. Provide configuration parameters

To initialize the editor, use the workflowElement.init(config) method. This method accepts integration settings, product properties, and parameters of the workflow element in the config object.

const config = {
    "configVersion": 2,
    "settings": {},
    "resources": {},
    "integration": {
        "tenantId": <yourTenantId>,
        "storefrontId": <yourStorefrontId>,
        "cchubApiGatewayUrl": "<yourCchubApiGatewayUrl>",
        "user": {
            "id": "<userId>",
            "token": "<userToken>"
        }
    },
    "input": {},
    "localization": {}
}

The configVersion property informs the element about the interface (structure) of the configuration object. This field maintains compatibility with newer versions of the config in elements that were introduced earlier, such as the Simple Editor and CC Options. If this field is not specified, these components assume that the config version is equal to 1. However, the Handy editor only supports version 2 and does not support version 1.

The settings and resources objects are typically sourced from workflow files created in your tenant. You can retrieve a workflow file assigned to a product by using the endpoint GET /api/storefront/v1/products/{id}/personalization-workflow as described in Opening products for editing. In the Handy Editor Settings and Handy Editor Resources topics, you can learn how to define these objects.

Creating the integration object

The integration object has the following properties:

tenantId: take this from the tenant's settings.
storefrontId: register your integration as described in the Integrations topic.
cchubApiGatewayUrl: define either https://api.eu.customerscanvashub.com, https://api.au.customerscanvashub.com, or https://api.customerscanvashub.com, depending on where your tenant is hosted — in Europe, Australia, or the USA.
user.id: register your users as described in the Registering customers topic.
user.token: generate a token as described in the Registering customers topic.
externalImageStorage.url: define a web service URL.
externalImageStorage.token: provide an access token for the storage.

This is how the integration object may look like:

{
    "integration": {
        "tenantId": 12345,
        "storefrontId": 123456,
        "cchubApiGatewayUrl": "https://api.customerscanvashub.com/",
        "user": {
            "id": "john.wood",
            "token": "fcmVhZCIsIlN0b3JlZnJvbnRVc2Vyc19mdWxsIiwiU3R..."
        },
        "externalImageStorage": {
            "url": "https://api.external-storage.url",
            "token": "access_token_for_external_storage"
        }
    }
}

Creating the input object

The input contains properties to load products into the editor. These properties allow you to retrieve products defined in Customer's Canvas in several ways: opening designs without PIM, editor initialization using PIM data, and recovery scenarios.

Let's take a look at some of the scenarios:

Loading a public template and mockups.

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"]
};

Loading one of variants of a PIM product.

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

Recovering an editor session using SKU.

const input = {
    "sku": "SUP-BRD-001",                   // SKU of the product variant.
    "designId": "642d0e469793dc8d64460751", // Private design ID.
    "productId": 2429,                      // Product ID.
    "productVersionId": 456                 // Product version ID.
};

For rest the scenarios, refer to the Input topic.

4. Set up external styles

To redefine styles of the editor, add a <style> element to the page after the styles.css link and change the required CSS variables. For example, you may want to open the editor in the full screen mode.

<style>
    body { margin: 0; }
</style>

5. Load the editor

You can access the component's DOM element using document.getElementsByTagName. Note that methods of a workflow element can only be called after its script has been loaded.

document.addEventListener("DOMContentLoaded", async () => {

    let handyEditor = document.getElementsByTagName("au-handy-editor").item(0);

    handyEditor.init({
        "configVersion": 2,
        "integration": {
            "tenantId": 12345,
            "storefrontId": 123456,
            "cchubApiGatewayUrl": "https://api.customerscanvashub.com/",
            "user": {
                "id": "john.wood",
                "token": "fcmVhZCIsIlN0b3JlZnJvbnRVc2Vyc19mdWxsIiwiU3R..."
            }
        }
        "input": {
            "designTemplateId": "61cd31a43056bcc33e919927",
            "mockup3dId": "6527afc63507abfadd355226"
        },
        "settings": {
            "assetLibrary": {
                "images": {
                    "enabled": false
                }
            }
        },
        "resources": {},
        "localization": { "language": "en" }
    });
});