Prepare for frontend integration
Prepare tenant data, product assets, and other values before you start the integration process. Use this checklist to collect everything you need for the first test.
- Tenant data: tenant ID, environment, Customer's Canvas URL, and API Gateway URL
- OAuth2 credentials for backend API calls
- Assets (design templates, optionally, mockups)
- Workflow file (editor configuration) and processing pipeline (file rendering configuration)
- A test product with connected designs
- A storefront integration
This article uses a business card product with a Shape option and two values: Square and Rectangle. The product uses alternative designs for these shapes and does not require mockups for the first test.
Some of these entities may already exist in your tenant, but this article explains how to prepare them from scratch.
Prerequisites
- Admin access to a Customer's Canvas Hub tenant
- A storefront URL for the integration
Collect tenant details
Find your tenant ID and the Customer's Canvas URLs to use for API calls and editor initialization.
Go to Settings > Tenant and copy the tenant ID.
Identify the tenant environment from the URL you use to open Customer's Canvas Hub:
| Environment | Customer's Canvas URL | API Gateway URL |
|---|---|---|
| US | https://customerscanvashub.com | https://api.customerscanvashub.com |
| EU | https://eu.customerscanvashub.com | https://api.eu.customerscanvashub.com |
| AU | https://au.customerscanvashub.com | https://api.au.customerscanvashub.com |
Frontend examples use these values as integration.tenantId, integration.cchubUrl, and integration.cchubApiGatewayUrl.
See Tenant.
Create OAuth2 credentials for your backend
Register your app and get credentials for backend API calls.
Go to Settings > External apps, select Create, and use Client Credentials for backend-to-backend API calls.
Configure as few permissions as possible. These permissions are sufficient for the storefront scenarios in this section:
| Resource | Permission |
|---|---|
| Assets | Read |
| Private assets | Full |
| Projects | Full |
| Products | Read |
| Pipeline artifacts | Read |
| Storefront users | Full |
| Storefront configuration | No Access |
| Tenant users | No Access |
| Tenant configuration | Read |
Copy the Client ID and Secret key. Store them in your backend configuration, for example, in an .env file for a Node.js or Python backend. Do not expose these credentials in frontend code or share them with unauthorized people.
See External apps and Authentication in Customer's Canvas Hub.
Add business card designs
Go to Assets > Designs and create or import the designs that customers personalize. Organize them in a separate folder to distinguish test files from the production templates you add later.
For this test product, prepare at least two designs: one for the square card and one for the rectangular card. Use one of these approaches:
- Create templates from scratch, as explained in Creating a new design.
- Import templates from InDesign files as explained in Importing from InDesign.
- Download these three test business cards and upload them to your tenant. The archive contains one square and two rectangular templates.
Use the last approach to proceed with fewer steps.
See Designs.
(Optional) Add mockups only when your flow needs them
A simple business card test can start without mockups. If you need storefront thumbnails, editor backgrounds, or approval previews, add mockups in Assets > Mockups and connect them to the product later.
See Mockups.
Create a workflow file
Although you may hard-code editor configuration, the recommended approach is to create one or more Workflow Files (editor configurations) and connect them to products. This lets you adjust settings without changing code and use different configurations for different products.
Go to Products > Workflows, select Create > New blank workflow, and set Type to Workflow Elements.
For a basic Handy Editor workflow, start with this configuration:
{
"configVersion": 2,
"component": "handy-editor",
"tagName": "au-handy-editor",
"settings": {},
"resources": {}
}
Save the workflow file.
Alternatively, create a workflow file from a template.
Create a Processing Pipeline
A Processing Pipeline specifies what to do with the design after a customer submits an order. Create a default pipeline for now. Return to this subject later, after you have a working application.
Go to Projects > Pipelines, select Create, choose Create from an existing template, and select the Default Pipeline.
See Order processing pipelines.
Prepare a PIM product
If your tenant does not have a product yet, or you want to inspect product configuration, prepare a product to use with the editor.
Create a product and options
Go to Products, select Create new, and create a product such as Business card. On the General tab, select the Workflow Elements workflow and a processing pipeline.
Then, go to the Options tab. Select Manage options, then select Add option. Create an option, for example, Shape, with values Rectangle and Square.
You may also switch to the Variants tab and add unique placeholder SKU values.
After you create the options, go to the Designs tab and select the checkbox for the Shape option. This tells the system that the design template depends on the selected value of this option.
If you have mockups, go to the Mockups tab and do the same.
Save the product and return to the product list page.
See Creating products and Editing options.
Connect designs
In the product list, select the product ellipsis, then select Asset connections. On the Designs tab, select Add file and choose the business card designs.
For each design, select the product ellipsis, select Edit, and apply the matching Shape value. Connect the square design to Square and the rectangular designs to Rectangle.
If you use templates attached to this article, connect both rectangular designs to the Rectangle option value.
See Connecting assets to products.
Connect mockups if you added them
In Asset connections, open the Mockups tab, add the mockups, select the mockup type, and specify the pages they apply to.
See Connecting assets to products.
Create a storefront integration
Register your storefront integration. Create separate storefronts for development, QA, and production environments, and for different installations, for example, Shopify and WooCommerce sites or storefronts for different clients.
Go to Settings > Integrations, select Create New, choose the Custom integration type, enter the storefront name (e.g. Sandbox app) and URL at Allow at (you may use http://localhost:<port>), then save the integration.
Copy the integration ID. Workflow Elements use this value as integration.storefrontId.
See Integrations.
Summary
Collect all values you need for your configuration and initialization code.
| Value | Where to get it |
|---|---|
| Tenant ID | Settings > Tenant > ID |
| Customer's Canvas URL | Tenant environment |
| API Gateway URL | Tenant environment |
| Storefront integration ID | Settings > Integrations > ID |
| OAuth2 Client ID and Secret key | Settings > External apps |
Additionally, depending on the editor and its input data type, you may need to provide:
| Value | Where to get it |
|---|---|
| Product ID | Products > ID |
| Design Template ID | Assets > Designs > a folder with design templates > Right-click > Properties, copy ID |
Now you are ready to add the editor to your code.