Mobify DevCenter

Salesforce Commerce Concepts: Session Bridging


Note: The Salesforce Commerce Concepts series is designed to dive into some of the more challenging topics you may encounter when working with Salesforce B2C Commerce.

In this lesson, we will dive headfirst into session bridging, which is one of the most challenging topics you may encounter when working with Salesforce B2C Commerce. We will walk you through the storefront, the session bridging problem it introduces, and some approaches to address that problem. By the end of the lesson, you will appreciate the advantages of working purely with OCAPI for all of your PWA’s data and functionality.

Essential prerequisites

To get the most out of this guide, make sure you:

  • If you’re not a backend developer yourself, you’ll need to make friends with one, as a lot of the tactics discussed in this guide require backend development expertise. Often, projects require changes to expose more data using requests to the Salesforce Commerce Cloud Open Commerce API, (OCAPI). The best case scenario is being able to work with a backend developer who understands the site’s OCAPI implementation. This will allow you to make changes to the site that will save you from having to scrape the data from desktop, or send multiple requests to get the same data.
  • Complete our initial Salesforce Connector setup steps.
  • Have Salesforce B2C Business Manager access for the development environment (not the production environment). This is very useful for debugging and testing certain kinds of issues, such as when the availability of a product changes.
  • Be able to access the Salesforce Documentation, so you can pause and review the underlying API when necessary.

OCAPI and the storefront

When working with Salesforce B2C Commerce, we need to consider both the Open Commerce API (OCAPI) and the storefront. Think of them as two different ways to interact with the same underlying data.

OCAPI, as its name suggests, provides an API that can be used to interact with this underlying data. With an API, maintenance is predictable. APIs are bound by contracts which require changes to be backwards compatible.

The storefront provides a website - this is the existing desktop website. If you wish to interact with the underlying data, you must use scraping to get data and submit HTML forms to update data. When using scraping, maintenance is unpredictable. When the HTML of a website changes, the integration must change with it.

In order to achieve a truly headless architecture, your PWA should rely exclusively on OCAPI for integrating with Salesforce Commerce.

However, there may be cases where the functionality present in OCAPI and the storefront is different. For example, some features may only be available on the storefront.

Whenever possible, those cases should be addressed by extending OCAPI. Custom endpoints should be created which add the missing functionality to OCAPI.

If this is not possible, then you will need to use both OCAPI and the storefront. This will require you to take some steps to sync the user’s state between the two code bases. In this tutorial, we will walk you through the most common syncing issues and possible solutions. Your implementation may be unique due to how your OCAPI is set up, but there’s a lot that can be applied across implementations.

Why would a PWA need to use the storefront?

There are two main reasons why your PWA may need to use the storefront in addition to OCAPI:

  1. Storefront functionality is not present in OCAPI, or the storefront works differently than OCAPI. For example, with features like PayPal, address verification and tax calculation, the functionality will only work with baskets that have been created by the storefront. These features may not work with baskets created by OCAPI. You may also encounter important storefront-only code being executed after an order is submitted, which is necessary to process the order correctly. In these cases, if you do not bridge the session, you will not be able to take an action through the storefront and have it update the basket you’re using in OCAPI.

  2. The PWA may not be loading for all pages across the site. If the user is able to navigate outside of the PWA, you will want their state to be synced so that any non-PWA pages display the correct information. As examples, you will want to make sure that they stay logged in across the site, and that their basket will work if the checkout isn’t included in the PWA.

To synchronize state between OCAPI and the storefront, we need to use the session bridge, which is a concept from Salesforce B2C Commerce.

Session bridging

A JSON Web Token (JWT) is used to persist a user’s session in OCAPI, while session cookies are used to persist a user’s session on the storefront. The session bridge allows us to sync states by turning a JWT into session cookies, or vice versa. This allows us to share the same session across both OCAPI and the storefront.

We will typically start by requesting the JWT from OCAPI first. When necessary, we will exchange the JWT for session cookies if we need to send requests to the storefront.

In a server-side rendered PWA, the user can no longer access the storefront directly. In this case, you may decide to use the session bridge to support existing payment integrations, such as PayPal and Apple Pay. To verify that the session bridge has been setup correctly, we suggest testing features between your current session and the existing storefront site. You can test your session bridge by using a code snippet like the one below.

If you paste this code into the console of the existing desktop page and then refresh the browser, it will put the desktop tab into the same session as the PWA.

fetch("$BASEPATH/sessions", {
method: "POST",
credentials: "same-origin",
headers: {
"Content-Type": "application/json",
"x-dw-client-id": $CLIENTID,
Authorization: $JWT

Wrap up

After reading this guide, we hope you can anticipate some of the common pitfalls when working with Salesforce Commerce, and start making informed decisions.

As a general takeaway, there are many challenges associated with session bridging. If and when possible, you can avoid many of these challenges by adding APIs and updating OCAPI implementations.

To continue learning about Salesforce Commerce concepts, check out our next lesson, on Checkout