Menu
Menu Sheet Overlay
Search
Search Sheet

Integrating Salesforce Commerce Cloud

    In this guide you will learn how to integrate your PWA with Salesforce Commerce Cloud.

    Mobify provides an Salesforce Commerce Cloud (SFCC) cartridge and connector that simplifies integration:

    Before you begin #

    Before following these instructions you should:

    Integration

    To complete integration with SFCC you must:

    1. Install the cartridge
    2. Create an OCAPI client
    3. Update OCAPI settings
    4. Set up the connector in your project

    Install the cartridge

    The cartridge adds the Mobify Tag and Mobify Service Worker to your SFCC site.

    Download the cartridge from the LINK Marketplace. Follow the installation instructions included with it.

    You must login with your SFCC account to view and download the cartridge!

    Once you’ve installed it, verify the Mobify Tag and service worker are present on your site.

    Create an OCAPI client #

    The client allows the connector to communicate with SFCC using OCAPI.

    Create a new OCAPI client. Note its client ID. It is need to configure OCAPI settings and the connector.

    Update OCAPI settings

    Settings control which OCAPI resources can be used by the connector.

    1. Login to the SFCC Business Manager.
    2. Select Administration > Site Development > Open Commerce API Settings.
    3. Select Shop and the relevant Site ID. Record the Site ID. It is needed to set up the connector!
    4. Open the settings in an editor. Update the client_id.
    5. Copy the contents of your settings into the field and Save.

    If you are using extensions with the connector, you may need additional settings.

    Set up the connector

    Configuring the connector tells it how to talk to your SFCC site.

    In the Web SDK, the connector is configured and registered with Integration Manager in web/app/init-sfcc-connector.js. Update it with your siteID and clientID from earlier.

    Open web/app/main.jsx and remove the other connectors. Import the one we set up:

    - import initConnector from './init-merlins-connector'
    - import initConnector from './init-stub-connector'
    + import initConnector from './init-sfcc-connector'
    
    initConnector()
    

    You’re done! Great job! 🙌

    Your PWA should now be integrated with SFCC.

    Verifying it worked

    To verify, load the PWA and confirm it gets data from SFCC.

    1. Start the development server by running npm start in the web folder.
    2. Open a web browser and activate mobile emulation.
    3. Copy Preview URL from your console and open it in your web browser.
    4. Ensure the Site URL is set to your SFCC site’s homepage over HTTPS.
    5. Hit Preview!

    If everything worked correctly, you should see the PWA load your site:

    Troubleshooting

    npm start doesn’t work!

    After previewing, the PWA doesn’t load!


    Authentication/JWT #

    We use JSON Web Tokens (JWT) for authentication with Salesforce Commerce Cloud. The details of how JWT authentication works in SFCC are documented in this document.

    The Connector for SFCC automatically manages requesting a JWT token when a sessions starts and then submits and renews the token as needed.

    Note: Authentication using JWT does not work correctly in Safari for sites that require Basic HTTP authentication. Safari uses the Basic authentication header instead of the JSON Web Token, which causes requests to the API to fail. To fix this issue, disable basic HTTP authentication for the site.

    Utility Functions #

    There are a number of utility functions that you may find useful if you need to extend the Connector for SFCC. They simplify interacting with SFCC OC APIs by taking care of things like authentication tokens (JWT) and cart management automatically.

    Note: If you are extending the Connector for SFCC we strongly recommend using these functions instead of implementing similar functionality from scratch.

    The functions are organized into a set of broad categories below.

    Authentication #

    getAuthToken(): string

    Retrieves the auth token from browser storage.

    Note: You almost never need to use this function directly because the Request Functions manage the authorization token automatically.

    storeAuthToken(authToken: string)

    Stores the auth token to browser storage. This function stores the auth token using the best available method (currently it tries session storage first and falls back to using a cookie).

    Note: You almost never need to use this function directly because the Request Functions manage the authorization token automatically.

    deleteAuthToken()

    Deletes the auth token from browser storage.

    Note: You almost never need to use this function directly because the Request Functions manage the authorization token automatically.

    getAuthTokenPayload(authToken: string): object

    Returns an object built using the given serialized auth token. The SFCC documentation provided in the Authentication/JWT section details the various pieces of data that the auth token contains.

    getCustomerData()

    Returns the customer data portion of the currently-stored authorization token. SFCC packs some extra customer data into the authorization token (such as a Customer ID) and this function returns that data unchanged.

    SFCC documentation does not specify what this object contains in all scenarios. The best way to discover what it contains is to call this function after setting up a session and authenticating and then execute console.log(getCustomerData()) and inspect it in the Javascript console.

    isUserLoggedIn(authorization) -> boolean

    Returns true if the given authToken represents a logged in user, false otherwise.

    initSfccSession(authToken: string): Promise<Array<string>>

    Initializes an SFCC session using the provided authToken. This function returns a Promise that resolves to an array of headers to use in subsequent API requests (session headers).

    initSfccAuthAndSession()

    Initializes an SFCC session and authorization token (re-using an existing authorization token if a valid one was previously created). This function will also refresh a saved authorization token if it has expired.

    Requests #

    makeApiRequest(path: string, options: object): Promise<object>

    Executes an API request to the specified path and returns Promise that resolves with the server’s results. The resolved object is the Response object returned by the fetch API and is documented here.

    Note that this method only takes a path instead of a full URL because the connector manages building the full URL based on the configured Site ID.

    makeApiJsonRequest(path: string, body: object, options: object): Promise<object>

    Makes a request to the SFCC API and serializing the body as JSON and deserializing the result from JSON. This function delegates to makeApiRequest and then deserializes the response as JSON.

    checkForResponseFault(responseJSON: string): string

    Checks the given response JSON object and throws if it contains a fault (error). If the response does not contain a fault, the response is returned unchanged. This is useful for using this method in a Promise chain without any extra work when the response is not a fault.

    For example:

    // Returns a Promise that resolves with current cart data, or throws if an error occurs
    return makeApiJsonRequest('/cart', {}, {method: 'GET'})
        .then(checkForResponseFault)
        .then((cart) => {
            // update cart in the UI
        })
    

    makeUnAuthenticatedApiRequest(path: string, options: object): Promise<object>

    Exactly the same as makeApiRequest but explicitly doesn’t set any authorization headers. This is useful if you need to make an API call outside of the current session/user.

    Basket/Cart Management #

    deleteBasketID()

    Deletes the currently-saved basket ID from browser storage.

    getBasketID(): string

    Retrieves the currently-saved basket ID from browser storage

    storeBaskedID(basketID: string)

    Stores the given basket ID to browser storage

    createBasket(basketContents: object)

    Creates a new basket on the SFCC server with the given contents. This function will take care of using an existing Basket ID, if one has been previously created and saved, or create a new one, if needed.

    createNewBasket() => (dispatch)

    [Thunk Action] Deletes and creates a new basket carrying over existing cart contents to the newly created basket.

    fetchCartItemImages() => (dispatch)

    [Thunk Action] Fetches product images for items that are in the cart and don’t already have them.

    requestCartData(noRetry: boolean): Promise<object>

    Fetches cart data from SFCC for the current cart. When noRetry is set to false the process will retry if the server returns an HTTP 404 Not Found error.

    handleCartData(basket: object): Promise

    Processes the provided cart data and dispatches it to the Redux store. This will also dispatch fetchCartItemImages at the end to ensure that all items in the cart have an associated image. The returned Promise resolves when all work is completed. The resolved value is undefined.

    isCartExpired(basket: object): boolean

    Checks if the given cart contents contains a fault that signals an expired cart. Returns true if the given cart (basket) is expired, false otherwise.

    updateExpiredCart(basket: object)

    Check if the users cart has expired, if it has create a new one and throw an error otherwise return the cart object


    Terminology #