This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Help needed?

This page documents known and recurring challenges with Custom Applications and potential solutions to them.

Something is not working as expected? Do you need general guidance? Do you have a technical question or are you simply looking for some advice?

We strongly encourage and recommend to use GitHub Discussions as a way of communicating with us (commercetools) and with the community. You can ask questions, share ideas, showcase your work, etc.

Additionally, we also recommend checking for existing GitHub Issues about similar problems you might have or opening a new one.

Browser support

commercetools officially supports the latest two versions of all major browsers (Google Chrome, Mozilla Firefox, Apple Safari, Microsoft Edge), unless otherwise noted.

The following browsers are not supported any longer:

  • IE 11 and below

It is recommended to always keep your browser up-to-date for security reasons.

Using a test or staging environment for my Custom Application

During the development cycle of new features for a Custom Application, it can be helpful to showcase or test those new features before publishing them to the production environment. This can be accomplished using deployment previews which allow you to inspect different versions of a Custom Application.

Legacy workaround

This approach is no longer recommended. Instead, you can use the deployment previews feature to have a simpler setup.

To emulate a Custom Application preview, create multiple Custom Applications in the Merchant Center, each with a different entryPointUriPath.

You must configure the Custom Application to support dynamic values for the entryPointUriPath and build different versions of it.

Setting up dynamic configurations of Custom Applications (per environment) is further explained in this section.

The same Custom Application can be deployed several times and have its configuration file set to use different entryPointUriPath values by taking advantage of environment variables for each deployment.

Let's say there are two deployments of the same application: A and B. We can assign an environment value for the entryPointUriPath property in its configuration.

{
"entryPointUriPath": "${env:ENTRY_POINT_URI_PATH}"
}

The ENTRY_POINT_URI_PATH environment variable can be provided in different ways.

For example:

  • as an inline environment variable when running a script command.

    ENTRY_POINT_URI_PATH=my-application-entry-point mc-scripts start
  • using a dotenv file.

    .env-ATerminal
    ENTRY_POINT_URI_PATH=my-application-entry-point
    mc-scripts --env .env-A start
  • by defining the environment variables in your CI service.

Using this pattern, different entryPointUriPath values can be defined for different environments:

  • A environment: my-application-entry-point
  • B environment: my-application-entry-point-test

With this setup, preview versions of the Custom Application can be deployed to the B environment and tested using the application my-application-entry-point-test entry point path.

However, besides using different entryPointUriPath values, the logic of verifying the user permissions in the Custom Application source code must also be adjusted accordingly.

As explained in this section, the permission names of a Custom Application are derived from the entryPointUriPath value. Therefore, when using different entryPointUriPath values, the permission names must also be changed.

We recommend using the helper function entryPointUriPathToPermissionKeys to compute the permission names from the entryPointUriPath.

Find more information on how to apply user permissions in the Permissions documentation.

In this scenario the entryPointUriPath value cannot be defined statically but it's injected using an environment variable.

Therefore, both server-side and client-side logic must be considered when reading the value from the source code.

// Make sure to import the helper functions from the `ssr` entry point.
import { entryPointUriPathToPermissionKeys } from '@commercetools-frontend/application-shell/ssr';
export const entryPointUriPath =
typeof window === 'undefined'
? process.env.ENTRY_POINT_URI_PATH
: window.app.entryPointUriPath;
export const PERMISSIONS = entryPointUriPathToPermissionKeys(entryPointUriPath);

The page keeps reloading itself

If the Merchant Center page keeps reloading itself when accessing a Custom Application, most likely, there's a misconfiguration of the entryPointUriPath. See Page reloading behavior for more information on debugging and solving this issue.

Session token expiration

In the browser, the session token is stored in a secure cookie named mcAccessToken and is valid for 30 days.

Granular permissions for local development

This feature is available from version 22.5.0 onwards.

This method requires additional configuration and setup and is only recommended for development teams with prior experience in Custom Application development and installation.

By default, developing a Custom Application requires you to be a member of the Administrators Team. However, for security reasons, your Organization might not be willing to grant administrator access to developers. In this case, an Organization can grant access using a regular team.

To enable this option, you must complete the following prerequisites in the Merchant Center (which can be done only with administrator rights):

  1. Configure the Custom Application in the Merchant Center

For local development the Custom Application does not have to be deployed, and Application URL is not relevant. Therefore, any acceptable value can be provided in the registration form.

  1. Assign the Application ID
  2. Install the Custom Application
  3. Create a team (or utilize an existing one)
  4. Obtain the teamId from the Merchant Center URL
  5. Invite users to the team
  6. Assign relevant permissions to the team

After completing these steps, you will have an applicationId and a teamId. You must provide these values for env.production.applicationId and env.development.teamId, respectively, in the Custom Application configuration file.

This process allows any member of the configured team to log in and perform local development for the Custom Application.

Limitations

Custom Applications have the following limitations:

Project access is not automatically updated for newly created Projects on AWS

When a new Project is created in the Organization, the Project cannot be accessed despite the Project access setting being configured to Install for all projects of this organization for an installed Custom Application.

To grant access, the Project access must be updated manually for the installed Custom Application.

This limitation applies specifically to Projects in AWS Regions.