Help needed?

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

Configuration changes to the Custom Application are not reflected immediately

The first time a user visits the Custom Application route in the Merchant Center, the proxy router fetches the configuration of the Custom Application to determine where to proxy the request to.

This configuration is cached for a certain time within the proxy router to reduce potential latency introduced by validating each incoming request. The cache is automatically updated at a regular interval (the default value is 30 minutes).

This implies that changes to the Custom Application configuration, for example the Application URL, are effectively applied according to the cache interval.

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 usually be accomplished using preview deployments, where you can inspect different versions of the Custom Application. As of now, the Merchant Center does not support this feature yet.

The only option to emulate this setup is to create multiple Custom Applications in the Merchant Center, each with a different entryPointUriPath.

However, the Custom Application must be configured to support dynamic values for the entryPointUriPath and build different versions of it.

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.

// 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);

Session token expiration

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

Limitations

Custom Applications have the following limitations:

OAuth Scopes cannot be changed in the Ready state

OAuth Scopes cannot be changed when a Custom Application is in the Ready state as it can be installed and used while in this state. You can change the list of OAuth Scopes assigned to the Custom Application permissions only in the Draft state when configuring the Custom Application in the Merchant Center.

To change the OAuth Scopes:

1. Move the Custom Application to the Draft state.
2. Update the list of OAuth Scopes.
3. Change the state to Ready.
4. Install the Custom Application again.

Project access is not automatically updated for newly created Projects

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.

Custom Applications can have only one set of permissions

Each Custom Application has a unique pair of user permissions assigned to them.

This restriction was an important step in being able to release Org-level Custom Application. For more information, see OAuth Scopes and user permissions.