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.

In addition, you can integrate Storefront Preview with a third-party content management system (CMS). Let’s say, for example, that you have a holiday sale banner managed by your CMS. You can allow your CMS to recognize the current context, such as the effective date and time, so your site preview displays the correct content, such as the holiday sale banner for the specified time period.

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

This video shows an example of how to preview your storefront.

Storefront Preview in a PWA Kit Site

To use Storefront Preview, first:

Build your site using PWA Kit version 2.8.4 or newer or version 3.6.0 or newer. Storefront Preview isn’t available in PWA Kit versions older than 2.8.4 or 3.6.0. Upgrade your project to use PWA Kit 2.8.4 or 3.6.0 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.
• Enable shopper context in Business Manager.
• Set up your site based on the functionality you want to validate in Storefront Preview. Examples:
  • Set up custom qualifiers and customer group IDs 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.

Optionally, you can write a function if you want to integrate Storefront Preview with a third-party CMS. See Add the StorefrontPreview component to your storefront and Integrate with a Third-Party CMS.

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.

• 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 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:

• 1. Create a SLAS Private Client for your B2C Commerce instances
• 2. Create MRT Environment Variables with the SLAS Private Client details and the Commerce API Short Code
• 3. Confirm that your Account Manager user has access to the B2C Commerce instance
• 4. Add the StorefrontPreview component to your storefront
• 5. Update the storefront Content Security Policy headers

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. You can also use Runtime Admin to manage environment variables. See 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.

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.

Optionally, if you want to integrate Storefront Preview with a third-party CMS, you can add the onContextChange prop to the StorefrontPreview component. Note that onContextChange is available in only PWA Kit version 3.6.x or later. See Integration with a Third-Party CMS. In the examples below, we add the onContextChange prop and pass an asynchronous function to it named handleContextChange. You can replace the console.log statement in the handleContextChange function with your own logic to respond to context changes. Customize the handleContextChange function based on your specific requirements. The newContext parameter in the function will contain the updated context information.

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.6.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.

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.

If you already added the StorefrontPreview component to your storefront and now you want to integrate with a third-party CMS, add the onContextChange prop to the StorefrontPreview component. See Integration with a Third-Party CMS.

In the examples below, we add the onContextChange prop and an asynchronous function named handleContextChange. You can replace the console.logstatement in the handleContextChange function with your own logic to respond to context changes. Customize the handleContextChange function based on your specific requirements. The newContext parameter in the function will contain the updated context information.

If you have PWA Kit version 3.6.x or later, use the following code and add the onContextChange prop in the _app/index.jsx file.

See Sample Usage for a video that shows how to preview your storefront.

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 customer group ids set up in Business Manager. Separate each ID using a comma.

6. (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.

7. 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.

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.

While previewing your site after you added the onContextChange prop to the StorefrontPreview component, you may get error messages or unexpected results.

Cause: There may be an issue with the function called by the onContextChange prop.

Suggested Solution: Remove the onContextChange prop and the function it calls from the StorefrontPreview component. Then preview your site and see if the same issues occur. If they don’t, debug your function to resolve any errors. For example, you can:

• Add the onContextChange prop and the function it calls back to the StorefrontPreview component. See Integrate with a Third-Party CMS.
• Inspect the network activity while previewing your site and see if the fetch request is sending the expected data.

If you still have issues after removing the onContextChange prop and the function it calls, open a support case.

While previewing your site, content isn't displayed as expected and none of the above errors occur. For example, prices don't change based on the values you entered in Storefront Preview.

Cause: It's possible that you didn't complete one or more of the prerequisites.

Suggested Solution: Confirm that you've completed all of the prerequisites. If you did and you still encounter issues, open a support case.