menu
Menu
Mobify DevCenter
search_icon_focus

Commerce Integrations

Introduction

Commerce Integrations is an SDK that provides a data layer for working with ecommerce backends. It’s based on an interface module, CommerceConnector, that defines a standard set of methods for common actions and data access across different backends. The SDK also includes prebuilt connector classes (SalesforceConnector and HybrisConnector) that implement the CommerceConnector interface to communicate with popular ecommerce backends. You can create your own custom implementation of the interface for other backends, and you can customize the existing connectors by extending and overriding their methods. It also includes the ScrapingConnector that you can use as a starting point accessing data on an existing website.

The SDK is distributed via NPM (@mobify/commerce-integrations).

Commerce Integrations

Commerce Integrations provide a layer of abstraction between your PWA and your site’s ecommerce backend.

Backend flexibility

Commerce Integrations gives you flexibility with your ecommerce backend. You can add new apps that use the same connector code or change ecommerce backends without making extensive changes to your application code!

For example, imagine you were using Salesforce B2C Commerce. You’d use the SalesforceConnector to talk to it like this:

import {SalesforceConnector} from '@mobify/commerce-integrations/dist/connectors/sfcc'
const connector = SalesforceConnector.fromConfig({
basePath: 'https://zzrf-001.sandbox.us01.dx.commercecloud.salesforce.com/s/RefArch/dw/shop/v20_4',
defaultHeaders: {
'x-dw-client-id': 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
}
})
// Application code accesses the backend using the connector:
connector.getCategory('root').then((category) => {
console.log(category)
})

Later, if you wanted to transition to another backend, you would just update your connector. Your application code remains the same:

import {HybrisConnector} from '@mobify/commerce-integrations/dist/connectors/hybris
const connector = HybrisConnector.fromConfig({
basePath: 'https://hybris.merlinspotions.com/rest/v2/apparel-uk/',
catalogId: 'apparelProductCatalog',
catalogVersionId: 'Online',
})
// Same application code
connector.getCategory('root').then((category) => {
console.log(category)
})

Essential concepts

To write a connector that successfully communicates with your backend, it’s important that you understand the following before proceeding:

Implementing interfaces

To use the Commerce Integrations SDK correctly, you should be familiar with how interfaces work.

An interface defines the signature of a class including its method names, expected arguments and return values. An interface does not define how those methods should work. That’s where you come in! You implement the connector by writing code for all the methods that the connector interface defines.

To reduce bugs later, write your connector methods so that they perform data-centric fetches, not page-centric fetches. For example, rather than storing page-centric content in your state management system, store raw data, such as products and categories so that you can reuse the data on any page and avoid any duplication of the data.

Important: A common mistake is to add new methods to the connector rather than implementing the methods of the CommerceConnector interface. This limits your ability to switch between ecommerce backends in the future.

Writing isomorphic JavaScript

The CommerceConnector methods are intended to be run on both the server-side and the client-side. This means you’ll need to write isomorphic JavaScript, meaning JavaScript that can run both on the server and in a web browser.

Follow these rules to ensure that your connector runs in both contexts:

  1. You must inject the window object into the connector’s constructor
  2. You must access any browser globals on this.window within the connector
  3. Avoid using any browser-specific API, such as the window object

By following these rules, you can swap window for a JSDOM instance, essentially giving you an API that you can use to build applications outside of the browser.

Installation

First, install Commerce Integrations using npm:

npm install @mobify/commerce-integrations --save

Next, import the connector that corresponds to your backend:

Mobify’s connector classes implement the CommerceConnector interface using their respective backend APIs. SalesforceConnector uses the Open Commerce API (OCAPI) client, and HybrisConnector uses the Hybris OCC client. These prebuilt connectors will require some modifications to work with the unique configuration of your backend systems.

If your site uses a backend other than Salesforce or SAP Hybris, you can implement our CommerceConnector interface as a starting point for scraping your existing site, or using another API. You can also combine multiple connectors to facilitate a transition from one backend to another or from scraping to APIs.