Commercetools

Commercetools allows you to create powerful, highly customized commerce experiences while building a profitable, sustainable brand.

This integration allows business users to build personalized landing pages and storefronts by repurposing product content from your Commercetools product catalog. It also enables developers to use their preferred front-end tools to build these applications.

This section covers how to configure and use this integration.

Create API client

In order to configure a connection to Commercetools, you need to create an API client. This gives you the settings that will enable Uniform to use the Commercetools API:

1. Log into the Commercetools Merchant Center.

2. Navigate to Settings > Developer Settings.

3. Click Create new API client.

4. Provide a name.

5. Under Scopes, make the following selections:

   • Categories > View
   • Products (all) > View
   • Products (published) > View

6. At the bottom of the screen, in the download your credentials section, switch to Environment Variables (.env).

   About this step

   Copy the values that are displayed.

Configure integration

This section describes how to add the Commercetools integration to your Uniform project.

1. Log into Uniform.

2. Navigate to Settings > Integrations.

3. Add the integration for Commercetools.

4. Enter the required fields:

   Field	Commercetools environment variable
   API Url	CTP_API_URL
   Auth URL	CTP_AUTH_URL
   Client ID	CTP_CLIENT_ID
   Client Secret	CTP_CLIENT_SECRET
   Project Key	CTP_PROJECT_KEY

5. Enter the optional fields, if applicable:

   Field	Description
   Locale	Sets the locale for product titles Canvas users see in product fields.
   Currency Code	Sets the currency displayed to Canvas users on products.

6. Click Save.

Add parameter to Canvas component

This integration adds custom parameter types for Canvas components. The following parameter types are available:

Commercetools Product

This parameter type is used when the user wants to select a single product for a parameter.

Commercetools Product List

This parameter type is used when the user wants to select multiple products for a parameter.

Add parameter support to front-end component

When a user sets a value on a Commercetools parameter, Uniform doesn't store product details. It only stores settings that the front-end code can use to retrieve the relevant product details.

You don't have to write the code to retrieve the product details yourself. Uniform provides a component called an enhancer that handles this logic. You just need to add the enhancer to your application. Each parameter type has its own enhancer.

1. Add the following environment variables to your .env file:

   Variable name	Commerce tools value
   CTP_PROJECT_KEY	Project key
   CTP_CLIENT_SECRET	Client secret
   CTP_CLIENT_ID	Client ID
   CTP_AUTH_URL	Auth URL
   CTP_API_URL	API URL

2. Add the following npm package to your application:

   Yarn

   yarn add @uniformdev/canvas-commercetools

   pnpm

   pnpm add @uniformdev/canvas-commercetools

   npm

   npm install @uniformdev/canvas-commercetools

3. Add the following file:

   /lib/commercetoolsEnhancer.js

     import getConfig from 'next/config';
     import { ApiRoot, createApiBuilderFromCtpClient } from '@commercetools/platform-sdk';
     import { createClient } from '@commercetools/sdk-client';
     import { createAuthMiddlewareForClientCredentialsFlow } from '@commercetools/sdk-middleware-auth';
     import { createHttpMiddleware } from '@commercetools/sdk-middleware-http';
     import { createCommercetoolsEnhancer } from '@uniformdev/canvas-commercetools';
     import fetch from 'node-fetch';
   
     const commercetoolsAuthUrl = process.env.CTP_AUTH_URL;
     const commercetoolsProjectKey = process.env.CTP_PROJECT_KEY;
     const commercetoolsClientId = process.env.CTP_CLIENT_ID;
     const commercetoolsClientSecret = process.env.CTP_CLIENT_SECRET;
     const commercetoolsApiUrl = process.env.CTP_API_URL;
   
     if (!commercetoolsAuthUrl) {
       throw new Error('CTP_AUTH_URL env not set.');
     }
   
     if (!commercetoolsProjectKey) {
       throw new Error('CTP_PROJECT_KEY env not set.');
     }
   
     if (!commercetoolsClientId) {
       throw new Error('CTP_CLIENT_ID env not set.');
     }
   
     if (!commercetoolsClientSecret) {
       throw new Error('CTP_CLIENT_SECRET env not set.');
     }
   
     if (!commercetoolsApiUrl) {
       throw new Error('CTP_API_URL env not set.');
     }
   
     const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({
     host: commercetoolsAuthUrl,
     projectKey: commercetoolsProjectKey,
       credentials: {
         clientId: commercetoolsClientId,
         clientSecret: commercetoolsClientSecret,
       },
     });
   
     const httpMiddleware = createHttpMiddleware({
       host: commercetoolsApiUrl,
       fetch,
     });
   
     const ctpClient = createClient({
       middlewares: [authMiddleware, httpMiddleware],
     });
   
     const apiRoot: ApiRoot = createApiBuilderFromCtpClient(ctpClient);
   
     export const commercetoolsEnhancer = createCommercetoolsEnhancer({
       apiRoot,
       projectKey: commercetoolsProjectKey,
     });

4. Find the file where the EnhancerBuilder is used.

   About this step

   If your application is built using Next.js, this is probably in getStaticProps.

5. Add the following import statement:

   import { canvas_COMMERCETOOLS_PARAMETER_TYPES } from '@uniformdev/canvas-commercetools';
   import { commercetoolsEnhancer } from '../lib/commercetoolsEnhancer';

   About this step

   Be sure that the path to the enhancer file matches your environment.

6. Add your enhancer:

   const enhancers = new EnhancerBuilder()
     // ... other enhancers here ...
     .parameterType(CANVAS_COMMERCETOOLS_PARAMETER_TYPES, commercetoolsEnhancer);
   await enhance({ composition, enhancers, context: {});

   About this step

   This tells Uniform to apply the enhancer any time one of the Commercetools parameters is found in a composition.