Storefront Preview in Runtime Admin

Preview you PWA Kit storefront in Runtime Admin to verify how it looks based on shopper context including customer groups, date and time, source code triggers, and qualifiers. Use it to test changes to products, pricing, and marketing strategies in a staging environment before deploying to production, ensuring your site displays correctly for specific scenarios like upcoming sales or seasonal campaigns.

In addition, 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.

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.