Initialization

  • Last updated on August 1, 2024
  • •
  • 7 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

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

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

Prerequisites

  1. Before embedding the Handy Editor on a page, create a product in your Customer's Canvas tenant as described in the Creating products topic.

  2. To configure the editor, create a workflow of the Workflow Elements type as described in the Overview 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 TenantInfo_GetApplicationsInfo.

    This URL will look as follows:

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

Adding an editor to a page

There are two methods to integrate an editor:

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 US tenant with the Handy Editor deployed.

Important

The environment of the Workflow Elements must match the environment of your tenant. So, if your tenant is deployed on the EU servers, specify EU here.

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, which takes integration settings, product properties, and parameters of the workflow element in the config in the following format:

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

All these objects except integration and input are usually taken from workflow files in your tenant. You can retrieve a workflow file specified for a product by using the endpoint Products_GetPersonalizationWorkflow as described in Opening products for editing. In the Settings and 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 or https://api.customerscanvashub.com, depending on where your tenant is hosted, in the EU or US environment.
  • user.id: register your users as described in the Registering customers topic.
  • user.token: generate a token as described in the Registering customers topic.

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..."
        }
    }
}

Creating the input object

The input contains product properties to load the product into the editor. These properties allows you to retrieve products defined in Customer's Canvas in four ways. Let's take a look at them.

Public design and mockup

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.
  • mockup3dId is a 3D mockup for the viewer from Assets > Mockups.
  • previewMockupIds is an array of mockup IDs for the approval screen from Assets > Images.

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

const input = {
    "designTemplateId": "61cd31a43056bcc33e919927",
    "previewMockupIds": ["643d05f7c121897df4598271", "643d05fbc121897df4598277"]
};

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

const input = {
    "designTemplateId": "61cd31a43056bcc33e919927",
    "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 this 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 Asset Generator API.
  • previewMockupIds is an array of mockup IDs for the approval screen.

This is how the input object may look like:

const input = {
    "designTemplateId": "61cd31a43056bcc33e919927",
    "mockup3dId": "6527afc63507abfadd355226"
};
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": "404"                     // 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,
      "productVersionId" = 1011,
      "productVariantId" = 22698
};
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",
        "designCustomFields": {"public": "true"}
    }
};

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. The complete list of the supported CSS variables is in the Styling topic.

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 get the editor's container through document.getElementsByTagName. Note that you can call the methods of a workflow element only after loading its script.

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": {}
    });
});
Was this page helpful?
Back to top Copyright © 2001–2024 Aurigma, Inc. All rights reserved.