---
title: "Initialization | Customer's Canvas Hub"
canonical: "https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/handy-editor/initialization/"
---

# Initialization

> In this article, you'll learn how to integrate the Handy Editor in your storefront and provide the initial data for the supported cases.

## Handy Editor 3D

If you need a 3D preview of the customized design, use the `handy-editor-3d` workflow element instead of `handy-editor`. The 3D version includes a built-in 3D viewer that synchronizes the edited design with the texture on a 3D model in real time. In all other respects, it is identical to the base version.

|Workflow Element|Tag|Script|Styles|
|---|---|---|---|
|Handy Editor|`<au-handy-editor>`|[workflow-elements/<wbr />handy-editor/<wbr />index.js](https://staticjs-aurigma.azureedge.net/libs/us/workflow-elements/handy-editor/index.js)|[workflow-elements/<wbr />handy-editor/<wbr />styles.css](https://staticjs-aurigma.azureedge.net/libs/us/workflow-elements/handy-editor/styles.css)|
|Handy Editor 3D|`<au-handy-editor-3d>`|[workflow-elements/<wbr />handy-editor-3d/<wbr />index.js](https://staticjs-aurigma.azureedge.net/libs/us/workflow-elements/handy-editor-3d/index.js)|[workflow-elements/<wbr />handy-editor-3d/<wbr />styles.css](https://staticjs-aurigma.azureedge.net/libs/us/workflow-elements/handy-editor-3d/styles.css)|

When you know that there will be no 3D preview, load the regular version to increase the loading speed. To pass a 3D mockup, use the `mockup3dId` property in the [input object](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/handy-editor/input.md#public-template-and-mockup).

Customer's Canvas supports the [following ways](#creating-the-input-object) 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
- Ordering multiple variants of a product (batch order)
- Recovering an editor session

## Prerequisites

1. Before embedding the Handy Editor on a page, create a product in your Customer's Canvas tenant as described in the [Creating a New Product](https://customerscanvas.com/docs/hub/admin-guide/pim/creating-products.md#creating-a-new-product) topic.
2. To configure the editor, create a workflow of the Workflow Elements type as described in the [Workflow Elements Overview](https://customerscanvas.com/docs/hub/admin-guide/workflows/workflow-elements.md) topic.
3. 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 [`GET /api/storefront/v1/tenant-info/applications`](https://customerscanvas.com/docs/hub/dev-center/api/storefront.md#tag/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](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements.md#integrating-workflow-elements)
- 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 [Workflow Elements](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements.md).

```html
<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:

```html
<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.

```js
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`](https://customerscanvas.com/docs/hub/dev-center/api/storefront.md#tag/products/GetPersonalizationWorkflow) as described in the [Starting personalization session](https://customerscanvas.com/docs/hub/dev-center/scenarios/online-store/starting-personalization-session.md). In the [Handy Editor Settings](https://customerscanvas.com/docs/hub/admin-guide/workflows/workflow-elements/handy-editor/settings.md) and [Handy Editor Resources](https://customerscanvas.com/docs/hub/admin-guide/workflows/workflow-elements/handy-editor/resources.md) 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](https://customerscanvas.com/docs/hub/admin-guide/settings/tenant.md).
- `storefrontId`: register your integration as described in the [Integrations Settings](https://customerscanvas.com/docs/hub/admin-guide/settings/integrations.md) 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](https://customerscanvas.com/docs/hub/dev-center/api/storefront/register-customers.md) topic.
- `user.token`: generate a token as described in the [Registering customers](https://customerscanvas.com/docs/hub/dev-center/api/storefront/register-customers.md) 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:

```json
{
    "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.

    ```js
    const input = {
        // ID of a template stored in assets, mandatory.
        "designTemplateId": "61cd31a43056bcc33e919927",
        // Array of mockup IDs for the approval screen from Mockups.
        "previewMockups": [
            { "surfaceIndex": 0, "mockupId": "643d05f7c121897df4598271" },
            { "surfaceIndex": 1, "mockupId": "643d05fbc121897df4598277" }
        ]
    };
    ```

- Loading by a product reference ID (standard e-commerce integrations like Shopify, WooCommerce).
 
    ```js
    const input = {
        // Product ID in your e-commerce system.
        "productReferenceId": "8255218868440",
        // Optional: filter designs by SKU or name.
        "designVariantFilter": {
            "sku": "SUP-BRD-001"
        }
    };
    ```
 
- Loading one of variants of a PIM product.
 
    ```js
    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.

    ```js
    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.
    };
    ```

- Ordering several variants of a product with quantities (batch order).

    ```js
    const input = {
        "productId": 114,         // Product ID in Customer's Canvas.
        "productVersionId": 1011, // Number of the saved product instance. Optional.
        "variants": [
            { "variantId": 22698, "quantity": 10 },
            { "variantId": 22699, "quantity": 5 }
        ]
    };
    ```

For the rest of the scenarios, refer to the [Handy Editor Input](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/handy-editor/input.md) 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.

```html
<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.

The following example demonstrates the complete initialization when you know the **product reference ID** (the product ID in your e-commerce system, e.g., Shopify or WooCommerce) and the **SKU** to filter the design variant:

```js
const input = {
    // Product reference ID from your e-commerce system.
    "productReferenceId": "8255218868440",
    // Optional: filter to load only the variant matching this SKU.
    "designVariantFilter": {
        "sku": "SUP-BRD-001"
    }
};

const config = {
    "configVersion": 2,
    "integration": {
        "tenantId": 12345,
        "storefrontId": 123456,
        "cchubApiGatewayUrl": "https://api.customerscanvashub.com",
        "user": {
            "id": "john.wood",
            "token": "fcmVhZCIsIlN0b3JlZnJvbnRVc2Vyc19mdWxsIiwiU3R..."
        }
    },
    "input": input,
    "settings": {
        "assetLibrary": {
            "images": {
                "enabled": false
            }
        }
    },
    "resources": {},
    "localization": { "language": "en" }
};

document.addEventListener("DOMContentLoaded", async () => {
    let handyEditor = document.getElementsByTagName("au-handy-editor").item(0);
    handyEditor.init(config);
});
```

Making the `input` a separate constant keeps the configuration object clean and allows you to switch between different initialization scenarios by simply replacing the `input` object.