Storefront Preview

You can use Storefront Preview to see how your Progressive Web App (PWA) Kit site will look based on context such as specified source code, customer groups, or a particular date or time. For instance, if you want to preview how your site will appear during an upcoming sale, you can use this feature.

Black Friday/Cyber Monday sales coming up? Preview your site changes in a staging environment. Then make sure your changes to things such as products, pricing, and marketing strategies work the way you expect before deploying your changes to production.

Storefront Preview is available in Runtime Admin. This guide explains how to configure, use, and troubleshoot Storefront Preview.

To use Storefront Preview, you must first:

  • Build your site using PWA Kit version 2.8.x or 3.2.x. Storefront Preview isn’t available in PWA Kit versions older than 2.8.x or 3.2.x. Upgrade your project to use PWA Kit 2.8.x or 3.2.x depending on your current major version.
  • Have access to the project in Runtime Admin in any role other than read only. If you don't have access, ask someone in a Managed Runtime (MRT) Admin role to help you with that.
  • Set up your site based on the functionality you want to validate in Storefront Preview. Examples:
    • Set up custom qualifiers using customer groups in Business Manager to apply rules for personalized pricing, products, or promotions.
    • To see a personalized shopper experience, set up source code that calls the Shopper Context endpoints. This is required because Storefront Preview uses context information for personalization.
    • Set up the pricing that you want to offer on a particular date. That way your specified pricing appears when you select that date in Storefront Preview.
  • Follow the configuration steps outlined in the Configure Storefront Preview section.
  • Configure your browser to allow third-party cookies on https://runtime.commercecloud.com.

You can use Storefront Preview with the latest versions of Chrome or Safari. Your browser must allow https://runtime.commercecloud.com to access third-party cookies. Storefront Preview won't work if you don't enable third-party cookies.

Learn how to enable third-party cookies for Chrome and Safari.
  • Data and experiences shown in Storefront Preview don't necessarily reflect the shopper experience. Shopper personalization requires the use of the Shopper Context API within your PWA Kit project. Learn more about Shopper Context.
  • Storefront Preview shows you storefront pages as they appear to a guest user on your site. For example, a guest user can see product or marketing content, pricing, promotions, product lists, or product display pages. You won't see content that a logged-in user sees, such as account information or a shopping cart.
  • Storefront Preview works on PWA Kit pages and not on Storefront Reference Architecture (SFRA) pages. However, you can use Storefront Toolkit Site Preview Tool in B2C Commerce to preview SFRA pages.

Follow these one-time configuration steps required for each site that uses Storefront Preview:

You must create a Shopper Login and API Access Service (SLAS) private client with the scopes sfcc.shopper-context.rw and sfcc.ts_ext_on_behalf_of for the B2C Commerce instances used by your storefront. Storefront Preview uses the SLAS private client to set the context in the storefront. The SLAS private client can be easily created using the SLAS Admin UI.

Follow the steps in the Authorization for Shopper APIs guide to create a SLAS private client for each B2C Commerce instance where you want to use Storefront Preview:

  • Select the app type BFF or Web App in the Which App Type will be used? field to create a private client.
  • Specify the scopes separated by a white space in the Enter the shopper scopes field: sfcc.shopper-context.rw sfcc.ts_ext_on_behalf_of

Copy the automatically generated client secret displayed at the top of the results page and the client ID so you can use them in the next step.

To create the MRT environment variables, call the MRT API endpoint projects_target_env_var_partial_update. Replace $SLAS_PRIVATE_CLIENT_ID and $SLAS_PRIVATE_CLIENT_SECRET with the values that you copied in step 1. Replace $CC_SHORT_CODE with the short code configuration value from Business Manager.

Calling this API redeploys your current deployed bundle. You must wait for the redeployment to finish before previewing your storefront. When the redeployment has successfully completed, the bundle appears underneath the heading Deployed Bundle in your project directory.

For additional information see MRT Environment Variables.

To use Storefront Preview with a storefront connected to your B2C Commerce instance, you must have one of these Account Manager user roles: Business Manager Administrator or Business Manager User. To verify whether you have one of these roles, check your roles in Account Manager.

If you don't have either of the required roles, follow these Granting Permissions instructions to add instances to your Account Manager user.

This step is only required for projects generated prior to the release of PWA Kit version 2.8.0 and 3.2.0.

For the communication between Runtime Admin and your storefront to work, establish a communications channel. This involves two steps:

  • To enable communication, render the StorefrontPreview component from the PWA Kit React SDK in your storefront. The StorefrontPreview component injects a script to establish communication with Runtime Admin. This script doesn't affect the performance of your storefront because it loads only when your storefront is running in Storefront Preview.
  • Wherever you render StorefrontPreview, you must define the getToken prop, which must return the access token of the current shopper.

If you have PWA Kit version 2.8.x, use the following code in your storefront to establish a communication channel. Add the StorefrontPreview component around your IntlProvider component in the _app/index.jsx file.

If you have PWA Kit version 3.2.x, use the following code in your storefront to establish a communication channel. Add the StorefrontPreview component around your IntlProvider component in the _app/index.jsx file.

  • This step is only required for projects generated prior to the release of PWA Kit version 2.8.0 and 3.2.0.
  • Starting with version 2.8.1 and 3.2.1, this step is done automatically in new projects.
  • This step is not required for projects using PWA Kit version 2.8.0 or 3.2.0, as the defaultPwaKitSecurityHeaders middleware does not exist in those versions.

To enable the communication channel, your storefront must:

  • Allow itself to be embedded in an iframe by Runtime Admin (runtime.commercecloud.com), and
  • Allow the script mentioned in step 4 to be loaded and executed.

Enable the communication channel by adding https://runtime.commercecloud.com to your Content Security Policy (CSP) frame-ancestors, connect-src, and script-src directives. To have this handled for you automatically, import and use the defaultPwaKitSecurityHeaders middleware provided by the pwa-kit-runtime package.

Follow these steps to use Storefront Preview:

  1. Open Runtime Admin in your browser and log in using your Account Manager credentials.

  2. Navigate to the project's environments page and click Preview Site next to the environment in which you want to preview your site.

    A new tab opens showing the storefront, with the Storefront Preview form on the left sidebar.

  3. (Optional) Choose the effective date and time for the context to preview. The date and time displayed is based on your computer's time zone and then converted to UTC time before sending the request that sets the context. If you don't specify a date and time, the preview reflects the current date and time.

  4. (Optional) Enter the source code that triggers the promotion (campaign assignment) and price books (assigned to source code group) for the context you want to preview.

  5. (Optional) Enter the custom qualifiers that apply to the personalized prices, products, or promotions set up in Business Manager. The custom qualifier keys must be unique. You can define up to 20 custom qualifiers.

  6. Click Preview.

    You can now navigate the storefront using the context you want to preview.

    For easier sharing, the URL in the browser tab is updated to include the context values.

Sometimes you have to interact with the previewed storefront to see the expected behavior. For example, you can click a particular size of clothing to see any applicable discounted price.

If you experience any issues with Storefront Preview, you can enable Storefront Preview logs in your MRT environment. This prints extra logs when you click the Preview button to help you debug the issues.

To enable Storefront Preview logs, add the MRT environment variable STOREFRONT_PREVIEW_DEBUG=1 to your MRT environment.

You can use MRT tail logs to read the Storefront Preview logs.

This section provides suggested solutions for common errors that you might encounter while using Storefront Preview.

Depending on your browser, you may encounter different behavior when third-party cookies aren't enabled.

  • Chrome: A modal appears stating "Preview is not enabled on this storefront", and the storefront displays a SecurityError.
  • Safari: A modal appears stating "Failed to initialize Storefront Preview", and the storefront isn't visible.

Cause: Your browser doesn't allow third-party cookies on https://runtime.commercecloud.com.

Suggested Solution: Update your browser settings and any extensions you may use to allow third-party cookies on https://runtime.commercecloud.com.

Error message when loading Storefront Preview: "Preview is not enabled on this storefront!"

Cause: The storefront is missing the script file that enables communication with Runtime Admin.

Suggested Solution: Follow the instructions shown in the error message window or complete the configurations in Step 4.

Response error message when clicking the Preview button:

Suggested Solution: Complete the configurations in Step 1 and Step 2.

Depending on your browser, you may encounter an error when you don’t have the correct Content Security Policy.

  • Chrome: A modal appears stating "Preview is not enabled on this storefront", and the storefront shows an error page stating "refused to connect".
  • Safari: A modal appears stating "Preview is not enabled on this storefront", and the storefront isn't visible.

Cause: Your storefront doesn’t permit Runtime Admin in its Content Security Policy.

Suggested Solution: Follow the instructions in Step 5 to correctly configure your Content Security Policy.

The initial page loaded by Storefront Preview is the domain configured as the External Hostname for the environment.

Cause: External Hostname isn't configured correctly in your environment settings.

Suggested Solution: Configure the External Hostname in the Advanced section of your environment settings to point to the correct domain.

Response error message seen when clicking the Preview button:

Suggested Solution: Complete Step 3.

Response error message seen when clicking the Preview button:

Cause: Incorrect values in the MRT environment variables SLAS_PRIVATE_CLIENT_ID and SLAS_PRIVATE_CLIENT_SECRET or wrong SLAS private client configuration.

Suggested Solution: Complete Step 1 and Step 2.