--- schema_version: "1" id: 00fbdd67cec5dabdbf9cb16d8dab80bfdef686a12ba81de5ce7110917deebdca title: Storefront Preview in Runtime Admin collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/storefront-preview.md canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.html source_site: developer.salesforce.com content_type: documentation content_hash: c43a0849fb1dd06a22017509457ea2b50f2b5b07cddc904fbadfff53c093863c products: - Composable Storefront - Salesforce APIs --- # 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. **tip:** Storefront Preview is available in Runtime Admin, but we recommend you preview the storefront in Business Manager, which requires less setup. See [Preview Your Storefront in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview-bm.md). ## Sample Usage This video shows an example of how to preview your storefront. ::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/Gu7QtjU1ykQKQ99CnSMwGi" title="Storefront Preview in a PWA Kit Site" type="vidyard"} ## Prerequisites To use Storefront Preview, first: ### Have the Required PWA Kit Version Build your site using [PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html) 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. ### Complete this Additional Setup - Have access to the project in [Runtime Admin](https://runtime.commercecloud.com/) 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api-personalized.html#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](https://help.salesforce.com/s/articleView?id=cc.b2c_using_session_custom_attributes.htm&type=5) and [customer group IDs](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_customer_group.htm&type=5) 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html). 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](#configure-storefront-preview) section. - Configure your browser to allow third-party cookies on `https://runtime.commercecloud.com`. ### Integration with a Third-Party CMS 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](#4-add-the-storefrontpreview-component-to-your-storefront) and [Integrate with a Third-Party CMS](#integrate-with-a-third-party-cms). **note:** The function you write to integrate with a third-party CMS must be asynchronous. This will help to avoid unexpected results when you preview your site. ## Supported Browsers 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. **tip:** Learn how to enable third-party cookies for [Chrome](https://support.google.com/accounts/answer/61416?hl=en&co=GENIE.Platform%3DDesktop) and [Safari](https://support.apple.com/guide/safari/enable-cookies-ibrw850f6c51/mac). ## Considerations - 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html). - 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](https://help.salesforce.com/s/articleView?id=cc.b2c_using_the_site_preview_tool.htm) to preview SFRA pages. ## Configure Storefront Preview 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 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) 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. For CLI client creation, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-shopper-apis.md#slas-admin-ui-create-a-slas-client). ### 2. Create MRT Environment Variables with the SLAS Private Client details and the Commerce API Short Code To create the MRT environment variables, call the MRT API endpoint [projects_target_env_var_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/commerce-api-configuration-values.html#short-code) from Business Manager. You can also use Runtime Admin to manage environment variables. See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.html). Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md): ```bash export MRT_API_KEY="$MOBIFY_API_KEY" npx @salesforce/b2c-cli mrt env var set \ "CC_SHORT_CODE=$CC_SHORT_CODE" \ "SLAS_PRIVATE_CLIENT_ID=$SLAS_PRIVATE_CLIENT_ID" \ "SLAS_PRIVATE_CLIENT_SECRET=$SLAS_PRIVATE_CLIENT_SECRET" \ --project my-storefront --environment staging ``` Alternatively, use the API: ```bash curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/env-var/" \ --request 'PATCH' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header "Authorization: Bearer $MOBIFY_API_KEY" \ --data "{ \"CC_SHORT_CODE\": {\"value\": \"$CC_SHORT_CODE\"}, \"SLAS_PRIVATE_CLIENT_ID\": {\"value\": \"$SLAS_PRIVATE_CLIENT_ID\"}, \"SLAS_PRIVATE_CLIENT_SECRET\": {\"value\": \"$SLAS_PRIVATE_CLIENT_SECRET\"} }" ``` **note:** 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. ### 3. Confirm that your Account Manager user has access to the B2C Commerce instance 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](https://account.demandware.com/). If you don't have either of the required roles, follow these [Granting Permissions instructions](https://help.salesforce.com/s/articleView?id=000391212&type=1#GrantPerms) to add instances to your Account Manager user. ### 4. Add the StorefrontPreview component to your storefront **note:** - This step is only required for projects generated prior to the release of PWA Kit version 2.8.0 and 3.2.0. - If you want to integrate Storefront Preview with a third-party CMS, you must add the `onContextChange` prop to the StorefrontPreview component. Note that `onContextChange` is available in only PWA Kit version 3.6.x or later. If you already added the StorefrontPreview component to your storefront, see [Integrate with a Third-Party CMS](#integrate-with-a-third-party-cms). 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](#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.** ```jsx // app/component/_app/index.jsx import StorefrontPreview from 'pwa-kit-react-sdk/storefront-preview' const App = () => { // Optionally, include an asynchronous function such as handleContextChange to integrate with a third-party CMS. const handleContextChange = async (newContext) => { console.log('Context changed:', newContext) } return ( window.localStorage.getItem('token')}> ... ) } export default App ``` **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.** ```jsx // app/component/_app/index.jsx import {StorefrontPreview} from '@salesforce/commerce-sdk-react/components' const App = () => { const {getTokenWhenReady} = useAccessToken() // Optionally, include an asynchronous function such as handleContextChange to integrate with a third-party CMS. const handleContextChange = async (newContext) => { console.log('Context changed:', newContext) } return ( ... ) } export default App ``` ### 5. Update the storefront Content Security Policy headers **note:** - 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 doesn't 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. ```js // app/ssr.js // Using PWA Kit version 3.6.x import {getRuntime} from '@salesforce/pwa-kit-runtime/ssr/server/express' import {defaultPwaKitSecurityHeaders} from '@salesforce/pwa-kit-runtime/utils/middleware' // Using PWA Kit version 2.8.x import {getRuntime} from 'pwa-kit-runtime/ssr/server/express' import {defaultPwaKitSecurityHeaders} from 'pwa-kit-runtime/utils/middleware' const runtime = getRuntime() const {handler} = runtime.createHandler(options, (app) => { // Set default HTTP security headers required by PWA Kit / Storefront Preview app.use(defaultPwaKitSecurityHeaders) // ... ``` ## Integrate with a Third-Party CMS **note:** `onContextChange` is available in only PWA Kit version 3.6.x or later. If you already [added the StorefrontPreview component to your storefront](#4-add-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](#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.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 3.6.x or later, use the following code and add the onContextChange prop in the `_app/index.jsx` file.** ```jsx // app/component/_app/index.jsx import {StorefrontPreview} from '@salesforce/commerce-sdk-react/components' const App = () => { const {getTokenWhenReady} = useAccessToken() // Include an asynchronous function such as handleContextChange to integrate with a third-party CMS. const handleContextChange = async (newContext) => { console.log('Context changed:', newContext) } return ( ) } export default App ``` ## Preview Your Storefront See [Sample Usage](#sample-usage) for a video that shows how to preview your storefront. Follow these steps to use Storefront Preview: 1. Open [Runtime Admin](https://runtime.commercecloud.com/login) 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. **note:** 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. ## Debug Storefront Preview 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#environment-variables) `STOREFRONT_PREVIEW_DEBUG=1` to your MRT environment. You can use [MRT tail logs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#tail-logs-on-managed-runtime) to read the Storefront Preview logs.