Create and install a Custom View

Overview

The Merchant Center includes several built-in applications by default for managing entities such as Products, Categories, and Customers. While these applications offer robust functionality, you may encounter use cases that they do not cover. In such cases, you can extend the Merchant Center using a customization—either a Custom Application or a Custom View.

Custom Applications and Custom Views offer distinct user experiences and are suited for different use cases. We recommend that you read the Merchant Center Customizations overview before starting this tutorial to understand how each customization type works within the Merchant Center.

In this tutorial, we'll walk you through how to create a Custom View to extend the functionality of a built-in application in the Merchant Center.

Learning goal

At the end of this tutorial, you will have a Custom View that is:

• Hosted on Vercel.
• Accessible in the Merchant Center for your specific Organization and team(s).
• Displays Channels from your Composable Commerce Project.

To get you there, we'll help you set up your development environment, deploy your Custom View to Vercel, and configure and install it in the Merchant Center. Once installed, you will be able to access your Custom View from inside one of the built-in applications.

Prerequisites

Before you start, make sure that you have the following:

• A Merchant Center account

• A commercetools Composable Commerce Project with a few Channels added to it

• A Vercel account

• Basic knowledge of React as well as some experience working with web applications

• Node.js installed (version 18.x, recommended >=20)

• A Node.js package manager such as yarn, pnpm, or npm

  Yarn PnP is not supported.

Instructions

Create the Custom View

To get started, open your terminal of choice and create a Custom View using the create-mc-app package. This package automatically sets up a pre-configured starter template.

npx @commercetools-frontend/create-mc-app@latest \
  my-new-custom-view-project \
  --application-type custom-view \
  --template starter

You may be prompted to install the latest version of the @commercetools-frontend/create-mc-app package. If this happens, press the y key, then the Enter key to continue.

Set configuration values

Next, you will be asked to provide basic information about your Custom View and commercetools Project. Be sure to take note of the values that you provide as you will need them later in the tutorial.

1. For the initial project key for local development, enter your unique commercetools Project key, then press Enter.

2. For cloudIdentifier, type the cloud identifier for the region where your commercetools Project is located, then press Enter.

   By default, the starter template is configured to use the Composable Commerce Project hosted in the Europe (Google Cloud, Belgium) region. If your Project is hosted in another region, you will need to set the cloudIdentifier according to the list of supported cloud identifiers.

At this point, the starter template will be downloaded and the Custom View will be configured with the values you provided. You may also notice that the package downloads the required dependencies. This can take a few minutes.

After everything is installed and configured, you will see a message in your terminal letting you know that the Custom View has been created.

Start the local development server

Now, let's start the local development server which lets you test your Custom View locally without needing to deploy it:

1. Navigate to the folder that contains your Custom View project:

   cd my-new-custom-view-project

2. Start the server by issuing the start command:

   yarnpnpmnpm

   yarn start

Your browser will open a new tab pointing to the local development address of the Custom View at http://localhost:3001.

At this point, you will be redirected to the login page of the Merchant Center. When this happens, enter your Merchant Center account credentials, then click Sign in. Once you're authenticated, you will be brought back to the local development server and shown a page that simulates the rendering of your Custom View as if it was within a page in the Merchant Center.

Here's what the local preview looks like:

To open your Custom View and see how it is presented, click Open the Custom View.

Configuration

The configuration file for your Custom View is named custom-view-config.mjs and is located in the root directory of your Custom View project.

Inside the configuration file, you can see some of the properties and values that we've previously set, along with some new ones.

On the local preview, you can see that the following settings have been configured:

Let's go over a few of these fields to better understand them.

Permissions

Permissions define how much access your Custom View should have to your Composable Commerce Project. In the configuration file, the oAuthScopes field uses the HTTP API scopes to define permissions. It is best practice to only give the minimum amount of permission needed to accomplish your use case(s).

For this Custom View, we want to view and manage Channels, so we need the view_products and manage_products scopes. These two scopes are already defined in the starter template so you don't need to do anything else.

Locators

Locators define where your Custom View should be displayed within one or more built-in applications. In the Custom View configuration file, locators contains a list of location identifiers with each one following the pattern <application>.<view>.<subview>.

In our case, the locators field of the configuration file has the value ['products.product_details.general'], this means that the Custom View should be displayed in the Products application, on the Product Details page and within the General tab.

To view a complete list of possible locations and their identifiers, see Locators.

Size

The size of your Custom View is determined by the typeSettings.size field in the configuration file. Depending on your use case, you can modify this setting to provide the appropriate amount of space for your required functionality.

To learn more about panel sizing, see design guidelines.

Registration

At this point, you have a Custom View that you can interact with locally, but the Merchant Center doesn't know about it yet. Let's change that by configuring and adding the Custom View to the Merchant Center.

Initial configuration

First, set the initial configuration:

1. Open the Merchant Center and log in using your credentials.
2. Click the profile icon and select Manage organizations & teams.
3. Select the Organization for which you wish to configure a Custom View.
4. Click the Custom Views tab.
5. Click Configure Custom Views.
6. Add a contact email address for the developer or maintainer of the Custom View.

Add the Custom View

Next, add the Custom View:

7. Click Add a Custom View.
8. Enter the following details:
   • Custom View name: My Channels View
   • Custom View URL: enter a placeholder value like https://test.com. We'll update this later after we deploy the Custom View.

Set permissions and menu options

Now, let's add these scopes to the Merchant Center, then configure some additional settings:

9. In the Permissions > Default group section, add the scopes to the following fields:

   • OAuth Scopes for View: add the view_products scope.
   • OAuth Scopes for Manage: add the manage_products scope.

10. In the Custom View Menu section, enter or select the following values:

    • Link label: enter View Channels.
    • Entry points: select Product general page.
    • Custom Panel type, select Extended Custom Panel.

11. Click Register Custom View.

After registering your Custom View, you will be shown the Custom View ID. You will need this identifier in the next step when we deploy your Custom View.

Deployment

Your Custom View is now installed locally on your machine and registered in the Merchant Center, however, it's not yet accessible there. To see it in the Merchant Center, you need to host the Custom View externally. In this section, we will walk you through how to deploy your Custom View to Vercel, a popular cloud hosting platform.

Configure and deploy using Vercel

To deploy to Vercel, do the following:

1. Create a Git repository and add the files from the my-new-custom-view-project folder to the root directory.

   If you created a local repository, you need to push those changes to the remote repository before proceeding to the next step.

2. Visit your Vercel dashboard and click Add New..., then select Project.

3. Import your Git repository into Vercel and proceed to configure the project settings.

4. In the Build & Output Settings section, make the following changes:

   • Framework Preset: Create React App
   • Build Command: yarn build
   • Output Directory: public

   

5. Click Deploy.

Your Vercel project will now create a deployment. Verify the deployment has the Ready status before proceeding.

Update the configuration

Next, we need to update the configuration file with information about the Custom View and where it is hosted.

Make the following changes to the custom-view-config.mjs file:

1. Add the Custom View ID (that you received after adding the Custom View to the Merchant Center) to the env.production.customViewId field.

2. Add the Vercel production URL of your deployed project to the env.production.url field. Be sure to include https:// before your URL.

   Don't use the Deployment URL from the Vercel dashboard since this value changes each time your project builds. Instead, use one of the URLs listed under Domains.

   Examplejson

   {
     "env": {
       "production": {
         "customViewId": "hxkhrl1i312sys6rjh1e6n3",
         "url": "https://<project>.vercel.app"
       }
     }
   }
   The preceding code snippet shows example values. You will need to provide your own values for customViewId and url.

3. Save the file and then push the changes to your remote repository.

Since Vercel is connected to your repository, it automatically starts a new deployment. Verify that the latest deployment has the Ready status before continuing to the next section.

Install the Custom View in the Merchant Center

Let's move the Custom View to the Ready state and install it:

1. Open the Merchant Center and log in using your Merchant Center credentials.
2. Click the profile icon and select Manage organizations & teams.
3. Select the Organization for which you wish to configure a Custom View.
4. Click the Custom Views tab.
5. Click Configure Custom Views.
6. Select your Custom View.
7. Update the Custom View URL with your Vercel project URL that you previously added to your configuration file.
8. Click Save.
9. Click the State dropdown, select Ready and confirm.
10. Select the Organization where the Custom View should be installed, then click Continue.
11. Scroll to the Projects access section, select Install for selected projects only and choose your desired Project.
12. Click Save.

Your Custom View is now installed in the Merchant Center for the Project that you specified. Let's verify that everything works by opening the Custom View:

1. Click Back to project to return to the Merchant Center homepage.
2. Select your Project from the Project dropdown.
3. From the Merchant Center main menu, go to Products > Product list.
4. Select any product from the list to open the product detail page.
5. Click the Custom View link My Channels View to open the Custom View.

Here's what the Custom View looks like when opened:

Nice work! You have successfully installed a Custom View in the Merchant Center.

Summary

In this tutorial, you have learned how to create, deploy, and install a Custom View in the Merchant Center.

To learn more about what you can do with Custom Views, we recommend the following resources within the Merchant Center Customizations documentation:

• Development overview - Learn development concepts for building and working with customizations.

• Merchant Center API - Learn about the Merchant Center API and how it helps you connect to commercetools APIs.

• Integrate with your own API - Learn about integration, authentication, and local development when using your own APIs.