1. Introduction

In an increasingly digital and interconnected world, flexibility is essential. Companies have to orchestrate seamless shopping experiences that meet the ever-changing needs of consumers. To do so, the option to combine various technologies and systems is of crucial importance. FirstSpirit Connect for Commerce is designed to meet exactly these requirements. With a strong emphasis on Composable Commerce, our solution offers a flexible architecture that empowers companies to tailor e-commerce solutions to their individual needs. Composable Commerce allows companies to seamlessly integrate and combine various components of their e-commerce ecosystem - from content management to shop systems to payment and shipping services.

Our solution supports content-driven commerce and shop-driven commerce, as well as combinations of the two. With the use of Microservices, API-driven, Cloud native, and Headless architecture (MACH), we enable organizations to stay agile and respond quickly to changing demands. Our platform allows a free choice of vendors and technologies and can be easily connected to various shop systems.

Effortlessly orchestrate content from multiple sources to create engaging shopping experiences. Improve your e-commerce strategy with ease and sophistication through FirstSpirit Connect for Commerce.

This documentation provides detailed guidance on how to use our solution in Composable Commerce scenarios. It will guide you through the integration, configuration, and use of our platform, helping to unleash the full potential of Connect for Commerce to meet all your e-commerce goals.

1.1. Challenges

1.1.1. Current challenges

Companies in the e-commerce sector face various challenges.

  • Content quality and relevance: Companies must ensure that the provided content is of high quality and meets the demands and interests of their target audience. It can be difficult to create and maintain relevant and engaging content, especially when a variety of products and audiences is involved.

  • Content consistency across channels: With the rise of different distribution channels, such as websites, social media, mobile apps, and marketplaces, it’s important to deliver consistent content across all of these channels. However, adapting and maintaining content for each channel can be challenging.

  • Personalization of content: Consumers increasingly expect personalized shopping experiences. Organizations need to be able to customize and deliver content based on their customers' behavior, preferences, and location. This requires an effective use of data and technologies for personalization.

  • Scalability and efficiency in content creation: With a growing product catalog and a variety of audiences, organizations need to ensure that they can create content efficiently and scalably without sacrificing quality. Manual processes can be inefficient and cause delays.

  • Content management and delivery: Effectively managing and organizing content is critical to ensure a seamless user experience. Organizations need powerful content management systems that allow them to easily create, edit, manage, and distribute content.

  • Compliance and legal requirements: Companies must ensure that their content complies with current legal requirements, in particular with respect to data protection, copyright, and product description. Compliance with these regulations can be complex and requires careful monitoring and updating of content.

1.1.2. Connect for Commerce solution

FirstSpirit Connect for Commerce allows the Crownpeak CMS FirstSpirit to be used in combination with any e-commerce shop system. Together they create a powerful overall system that combines the functional advantages of these systems and enables the delivery of modern and personalized content.

Editors have clear access to the shop system’s product catalog and can link it to editorial content, such as Interactive-Video. The content is maintained using an intuitive WYSIWYG interface provided by FirstSpirit, the FirstSpirit ContentCreator. Knowledge of the connected e-commerce shop system is not required for editing, as the ContentCreator provides all the necessary functionalities. The integration of additional connectors can expand the range of functions, e.g. DQM Connect facilitates compliance with industry-specific compliance rules and accessibility requirements.

In its default scope, Connect for Commerce provides functionalities for realizing complex use cases; example components and numerous out of the box solutions help to implement tailored solutions and achieve a functional MVP within a short time.

1.1.3. Advantages of Connect for Commerce

  • Our solution supports both content-driven commerce and shop-driven commerce as well as their seamless integration for maximum flexibility and adaptability.

  • By using microservices and an API-driven, cloud native, and headless architecture, we offer a future-proof and scalable platform that meets the requirements of modern e-commerce.

  • Companies benefit from an unrestricted choice of vendors and technologies to meet their individual needs and preferences.

  • Connect for Commerce allows an easy integration with any shop system to ensure smooth editorial processes and increase efficiency.

  • Content maintained in FirstSpirit extends product and category information to support a compelling shopping experience and informed decision-making.

  • Shop elements and editorial content are displayed simultaneously in the preview of FirstSpirit. This allows the editorial team to optimize the consistency and content quality.

  • Content can be easily delivered to different touchpoints for wide reach and maximum impact.

  • The reference implementations on GitHub are a valuable resource to accelerate and optimize the implementation and use of our solution.

  • Our platform provides enterprise CMS functionalities, including excellent performance and availability, reusable elements through templates, setting up sophisticated workflows, performant media management, and intuitive content maintenance through an easy-to-use Drag & Drop WYSIWYG interface without the need for code.

  • In addition, we integrate generative AI capabilities that help to automatically generate relevant and engaging content and increase content strategy efficiency.

1.2. Types of commerce

Various types of commerce exist in the e-commerce world:

  • E-commerce: Electronic Commerce refers to the purchase and sale of goods and services via the Internet. This includes B2C (business-to-consumer), B2B (business-to-business), and C2C (consumer-to-consumer) transactions.

  • M-commerce: Mobile Commerce refers to buying and selling goods and services via mobile devices such as smartphones and tablets. It includes websites optimized for mobile use, apps, and mobile payment systems.

  • Omnichannel Commerce: Omnichannel Commerce refers to the seamless integration of different sales channels, such as physical stores, online stores, mobile apps, and social media platforms, to provide a consistent shopping experience across all channels.

  • Social Commerce: Social Commerce uses social media platforms such as Facebook, Instagram, and Pinterest to facilitate the purchase and sale of products and services. It allows companies to interact directly with their customers and promote products to them.

  • Content-driven Commerce: Content-driven Commerce focuses on delivering relevant high-quality content to influence customers' purchasing behavior. This can be done through informative articles, product reviews, videos, and other content.

  • Shop-driven Commerce: Shop-driven Commerce focuses on the sales process and optimizing the shopping experience in the online store. This includes aspects such as website design, product presentation, navigation, and checkout processes.

  • Composable Commerce: Composable Commerce is a modular approach that allows companies to combine different technologies and services to create a tailored e-commerce solution. This allows for high flexibility and adaptability.

  • Headless Commerce: Headless Commerce separates the presentation layer (frontend) from the backend logic, allowing companies to flexibly delivery of content without compromising the backend system’s integrity.

  • Direct-to-Consumer (DTC) Commerce: Direct-to-Consumer Commerce refers to businesses that sell their products directly to end users without involving intermediaries or retailers. This allows companies to maintain direct contact with their customers and effectively communicate their brand message.

  • Subscription Commerce: Subscription Commerce allows companies to request recurring payments for services, digital content, or products on a regular basis.

Connect for Commerce generally follows a headless approach and makes all content available via CaaS. This makes it possible to support all commerce concepts. In the course of this document, the following concepts are discussed in detail.

1.2.1. Headless Commerce

At the center of Headless Commerce is an API-driven shop architecture. This means that the delivery layer, in this case the storefront, is disconnected from the shop backend. In such an architecture, the storefront is often a Progressive Web App (PWA), Single Page Application (SPA), or a combination of these. Content is queried and rendered on the client side. This way less data is transmitted for each page view as the website’s basic structure only needs to be transmitted once. Another advantage is the non-simultaneous retrieval of various data, which makes the relevant content available more quickly.

1.2.2. Static Commerce

The basis for the concept of Static Commerce is a shop system, which works according to the principle of Server Side Scripting (SSS). Examples of SSS technologies include PHP, Java Server Pages (JSP), and ASP/ASP.NET. These systems dynamically generate the required HTML for each request and page view, and thus differ from headless approaches. Since the content is compiled on the server side, it can be more easily processed by low-performance devices and crawlers, e.g. in the context of search engine optimization (SEO).

1.2.3. Shop-driven Commerce

Catalog-based online shops mainly focus on presenting and selling products or services online. The shop system has priority and determines the online shop structure. Connect for Commerce is used in this approach exclusively to enrich existing pages with content and provide additional pages.

1.2.4. Content-driven Commerce

In Content-driven Commerce, high-quality and relevant content is instrumentalized as a driving force for the sales process in order to promote product sales via digital channels. Content-driven Commerce requires an expedient integration of the content into the shopping process to offer customers the most valuable shopping experience possible. Connect for Commerce takes the leading role in the overall system and specifies the online shop structure and content.

Connect for Commerce supports both shop-driven and Content-driven Commerce and offers the opportunity to combine the best of both worlds.

2. Architecture

2.1. Low-level architecture

The figure Connect for Commerce low-level architecture illustrates how the individual components of Connect for Commerce interact in a Headless Commerce scenario. The components are explained in more detail below.

Connect for Commerce Low-level architecture diagram
Figure 1. Connect for Commerce low-level architecture

The image shows Connect for Commerce in a Headless Commerce scenario. Architectural differences between Headless and Static Commerce scenarios are explained in Target architecture and scenarios.

2.2. General components

The following components are integral parts of Connect for Commerce in addition to FirstSpirit. They are included by default in the Connect for Commerce cloud offering and are essential for using the Connect for Commerce Frontend API.

2.2.1. CaaS

Content as a Service (CaaS) functions as a central repository. In CaaS, the FirstSpirit content is persisted and provided in JSON format via an interface. When using CaaS Connect, saved content changes are automatically synced to CaaS in a predefined format. Media files are automatically stored in an Amazon S3 bucket.

2.2.2. Navigation Service

The Navigation Service provides routing and structural data to facilitate navigation in dynamic (web) applications. The structure is maintained in the FirstSpirit project and the routes are automatically generated by FirstSpirit. The Navigation Service module synchronizes all changes automatically.

2.3. Specific components

To use Connect for Commerce, additional components are required: the Connect for Commerce FirstSpirit module and independent microservices that make it possible to exchange and update different parts of the ecosystem without affecting other parts. The use of microservices depends on the scenario and use case.

2.3.1. Connect for Commerce module

The Connect for Commerce module requests product, category, and content data from the Bridge and displays it in the corresponding ContentCreator report. The data can be referenced in the report using the associated Data Access Plugins when creating content. In addition, the Connect for Commerce module enables communication between ContentCreator and FirstSpirit server to e.g. generate Shop-driven Pages.

2.3.2. Bridge

The Bridge retrieves the available product, category and content data from the shop system and makes it available to the Connect for Commerce module via an API. This can be a separate service or microservice, or a part of the shop backend.

2.3.3. Frontend API backend

The Frontend API backend connects the client (storefront) to CaaS and the Navigation Service to retrieve the editorial content and the FirstSpirit-managed page structure. To retrieve and transform data for the storefront, the Frontend API server npm-module is used, which is part of the Frontend API.

2.3.4. Shop backend

The shop backend is the shop system’s central part and provides, among other things, an API for retrieving products and categories.

2.3.5. Storefront

The storefront is the part of the shop system on the client side. It’s the shop’s visual representation in both the preview and the released view.

To edit content in the preview and to retrieve data from the Frontend API backend, the storefront uses the Frontend API client npm-module, which is also part of the Frontend API.

Shop backend and storefront are third-party applications. They are not included in the FirstSpirit Connect for Commerce package.

3. Data transmission

3.1. Frontend API

The Frontend API allows for an easy integration of Connect for Commerce functionalities into e-commerce projects. It adds functionalities to Connect for Commerce: generating product, category, and content pages as Shop-driven Pages and retrieving data from CaaS. Moreover, it enables the use of the preview function as well as editing content in the ContentCreator.

The Frontend API consists of two npm-modules:

Further information and examples can be found in the Frontend API documentation.

3.1.1. Frontend API server

The Frontend API server npm-module is part of the Frontend API, which retrieves content and structural data of FirstSpirit projects from CaaS and the Navigation Service to display them in the delivery layer. Based on the request, the Frontend API server detects whether preview or release content is queried.

The npm-module must be integrated into a backend service.

3.1.2. Frontend API client

The Frontend API client npm-module is the Frontend API server’s counterpart and also part of the Frontend API. The Frontend API client performs two tasks:

  • Integrating the Omnichannel Manager to enable editing preview content in the ContentCreator

  • Retrieving editorial and structural data using the Frontend API backend for visualization in the frontend

3.1.3. Frontend API backend

The Frontend API backend connects the storefront with CaaS and the Navigation Service to retrieve both the editorial content and the page structure managed by FirstSpirit. It uses the Frontend API server npm-module to retrieve, convert, and enrich data for optimized use in the frontend. It also hides the CaaS API keys from the client and validates the request source to enable edit mode in the preview.

A separate service for retrieving data from CaaS and Navigation Service can be implemented, or the reference implementation available on GitHub can be used.

3.2. Data flow

Within the whole system created with Connect for Commerce, the creation and maintenance of editorial content shifts to FirstSpirit. By providing shop content, it is possible to reference shop content within the maintained content.

Once the editorial content is released, it is automatically transferred to CaaS. CaaS then makes the content available to the connected shop system storefront.

The storefront retrieves the information and links it to the shop system’s information to deliver a combined view. The storefront is responsible for the display of all content both in the preview and in the final delivery. Connect for Commerce takes care of the mapping from the shop page to FirstSpirit objects.

Diagram describing the data flow of the overall system created with Connect for Commerce
Figure 2. Simplified data flow between the main systems

When implementing the storefront, a distinction must be made between Headless Commerce and Static Commerce scenarios:

  • In Headless Commerce scenarios, the integration is achieved by installing the Frontend API client as npm-module in the storefront. This allows the client to retrieve the data and display it in the browser.

  • For Static Commerce scenarios, in which the storefront uses Server Side Scripting (SSS), the Frontend API client is available as a script, which is integrated into the HTML. The request for editorial and structural data on the server must be made directly at the Frontend API backend. In this case, the script only allows the Omnichannel Manager’s integration and, thus, the editing of content in the ContentCreator.

Although PWAs and SPAs with Server-side rendering (SSR) render the HTML on the server, they are considered part of the Headless Commerce category.

After creating or maintaining editorial content in FirstSpirit, an automatic transfer to CaaS takes place. CaaS persists the content and makes it available in JSON format via a REST interface. The storefront receives this information and links it to the shop system content to deliver it in a combined view.

Querying CaaS content from the storefront can be achieved via a custom implementation. This solution must be adjusted to the connected shop system and is therefore different for each use case.

Regardless of the preferred form of transmission, however, the following points must always be taken into account:

  • Authentication

  • Retrieving data

  • Transforming data

  • Outputting data

  • Caching

Authentication

Querying data from CaaS requires an API key, which must be protected against unauthorized access. It has the status of a password and must be treated accordingly.

Retrieving data

When retrieving editorial content from CaaS, the correct data must be retrieved. It is therefore necessary to always be able to map product and category information used in FirstSpirit to real data in the shop system. This requires a mapping that is based on unique IDs and must already be specified by the Bridge. The IDs are stored in the form data of FirstSpirit elements and are transferred to CaaS. Based on the IDs, it is thus possible to retrieve the FirstSpirit data stored in CaaS as well as to link it to the shop data. Further details are provided in subchapters Mapping identifiers and Frontend API backend.

Structural information is stored in the Navigation Service. To implement a navigation, data requests must therefore be directed to the Navigation Service.
Transforming data

CaaS saves the data passed on to it in JSON format. As a first step of data processing, a transformation should be carried out, as the data is nested and contains unnecessary information. The data should be reduced to the essentials and transformed to a format that is optimal for the storefront. Linked information, such as media URLs, must be resolved correctly.

Outputting data

The storefront still handles the output of editorial content. The content is obtained from both the shop backend and CaaS. The storefront combines the data to deliver it in a combined view.

When outputting the data from CaaS, the information used in FirstSpirit must always match the real shop data. This applies not only to the correctness of the content itself, but also to its correct placement. Within the reference project FirstSpirit Connect for Commerce Reference Project, the editable areas of a shop page are represented by the content areas of a FirstSpirit page template. Sections can be added, each corresponding to a component of a shop page.

Caching

The content displayed in the storefront is dynamically retrieved from CaaS. Each call to the storefront thus generates a CaaS request. This can lead to a large volume of data. To avoid both performance issues and high cost for data traffic, we strongly recommend the implementation of a project-specific caching strategy.

3.3. Mapping identifiers

To ensure the correct linkage of shop system data to product and category information used in FirstSpirit, mapping between the two is required. The mapping must be based on unique IDs, e.g. the Stock Keeping Unit (SKU) of products. Mapping is relevant for both the Bridge and the data transfer in the frontend.

Diagram representing the described mapping of identifiers
Figure 3. Mapping of IDs between shop system and FirstSpirit

The IDs defined in the mapping are stored in the respective form data of a FirstSpirit element and transferred to CaaS each time it is synchronized. The FirstSpirit element can be either a page or e.g. a single teaser that references a specific product. The storefront can then use the additional product data from the shop system, depending on the implementation. CaaS persists the content created in FirstSpirit and makes it available to the connected shop system storefront.

The storefront continues to deliver the content it receives from the shop system backend. Using Connect for Commerce, the storefront can also access CaaS by using the Frontend API. The storefront links the information to the shop system data and delivers it in a combined view, depending on the implementation.

4. Editing pages in FirstSpirit

4.1. Page structure

Both in FirstSpirit and within a shop system, pages are based on the structure of different components. To combine editorial content from the two systems, these components must be coordinated.

In FirstSpirit, content is created using section templates. Their form can range from simple text to complex UI components. These sections are maintained on the pages within predefined content areas. A content area may include multiple sections. The number and position of content areas on the storefront’s various pages can be defined as part of the frontend implementation.

Within the reference project FirstSpirit Connect for Commerce Reference Project, the editable areas of a shop page are represented by the content areas of a FirstSpirit page template. They can be complemented with sections that correspond to the equivalent component of a shop page (see Figure Mapping between FirstSpirit page and page in the storefront).

FirstSpirit can thus be used to create components that are displayed within the editable areas of a shop page.

Diagram showing the mapping between FirstSpirit page and page in storefront
Figure 4. Mapping between FirstSpirit page and page in the storefront

4.2. Page types

Both in FirstSpirit and in the shop system, editorial content is maintained on a page-by-page basis. In this process, Connect for Commerce distinguishes between Shop-driven Pages and FirstSpirit-driven Pages.

FirstSpirit-driven Pages

FirstSpirit-driven Pages only exist in FirstSpirit and don’t have any associated page in the shop system. They are used to create content or campaign pages, which are not necessarily included in the shop system’s default scope.

Shop-driven Pages

FirstSpirit-driven Pages consist of a FirstSpirit page and its counterpart in the shop system. These can be e.g. the homepage, product pages, or category pages. The content maintained in FirstSpirit can supplement such page content or overwrite it.

4.3. Editorial changes

In FirstSpirit, a differentiation is made between the content’s preview and its released state. The CaaS Connect module reflects this differentiation in CaaS. The two states are accessible via dedicated CaaS URLs. They can be synchronized using actions within FirstSpirit. You can change the preview state by e.g. saving a section. The release state is only updated when a special release action is activated. Such an action can e.g. be part of a workflow. Any change other than the release action will only change the preview state. The preview only appears if the storefront is integrated into the ContentCreator.

The integration implemented with Connect for Commerce allows FirstSpirit to create and maintain editorial content, and to provide it using CaaS. The storefront continues to provide the page framework. Its editable areas integrate the generated components.

4.4. Preview

In the preview, the storefront is displayed in an iFrame in the ContentCreator. By using the Frontend API, the storefront can recognize when it is called up in the ContentCreator. In this case, content from the preview CaaS will be displayed. Content that has not yet been released can thus be viewed in the corresponding components directly in the storefront context.

You need to ensure that the storefront can be displayed in a frame in the ContentCreator, e.g. using a correct set-up of the HTTP Content Security Policy.
Animation showing content editing using Drag & Drop
Figure 5. Editing content using Drag & Drop

In addition, the Frontend API automatically integrates the Omnichannel Manager functionality into the storefront. The Omnichannel Manager is the interface between the storefront and the ContentCreator. It enables communication between FirstSpirit’s ContentCreator and the storefront within the iFrame, thus providing a WYSIWYG editor’s functionality. This enables maintaining and releasing content in the storefront context.

Diagram showing the preview’s operating principles in detail
Figure 6. The preview’s operating principles in detail

If you don’t use the Frontend API, you will need to dedicate time to integrating the Omnichannel Manager. Find out how in the Omnichannel Manager documentation.

5. Implementation

Before a project is implemented using FirstSpirit Connect for Commerce, a number of questions regarding the implementation should be clarified.

5.1. Preliminary decisions

5.1.1. Choosing an identifier

Mapping identifiers is a prerequisite for associating shop data with the content maintained in FirstSpirit. The loose linking via a single identifier ensures a high degree of flexibility, as it can be formed arbitrarily from the existing data within the shop architecture. Using a simple identifier facilitates a subsequent replacement of individual components. The identifier should be determined at the beginning of a project, as the development of the Bridge and the storefront builds on it. Both the current and target architecture play an important role in the decision.

Changing the identifier in the course of the project usually requires high effort in the affected project components. In addition, a migration of the data stored in FirstSpirit must take place to ensure that existing content remains correctly linked. Since the identifier persists in all components within FirstSpirit, side effects may occur. A possible result can be pages that can’t be located.

5.1.2. Bridge

The Bridge links Connect for Commerce to the shop system’s API and thereby establishes a connection between the two systems.

The implementation can be done in various ways, e.g. as a stand-alone service. In this case, the Bridge Commons npm-module included in the delivery can be used to implement a Bridge based on Node.js. The Bridge Commons minimize the implementation effort, such that only the functionalities specific to the shop system have to be added.

It is also possible to use other methods. In this case you can use services such as Netlify or a separate Kubernetes cluster to operate the Bridge.

If the Bridge is integrated into an existing application, it does not have to be operated as a separate service. In this case, however, one is usually bound by the application’s technology. Possible scenarios include a Bridge as part of a middleware or the backend within the shop architecture.

Since the Bridge itself does not store any data, little effort is required to exchange it over the course of a project. The identifier, however, must remain unchanged.

5.2. Planning

You can implement projects using Connect for Commerce in a number of ways. This means that there are no strict requirements for people involved in the implementation. Below, the different tasks and the required knowledge for their execution are illustrated.

5.2.1. Skills

A Connect for Commerce project usually consists of the following parts, which require adjustment.

shop system and storefront

The selected shop system or the selected storefront determine a specific technology. To integrate Connect for Commerce, the developer must have knowledge of these technologies as well as the architecture of these applications.

Correct data transmission must be guaranteed. One essential task is to create components for the content maintained in FirstSpirit to ensure correct presentation within the storefront.

Necessary knowledge to use the Frontend API is provided in the corresponding documentation.

If the Frontend API is used for the implementation in the frontend, the corresponding documentation provides the necessary information to become familiar with the issue.

Bridge implementation

To successfully implement a Bridge experience with implementing a service is necessary.

A detailed list of different possibilities is provided in the How-to: implementation of a Bridge.

FirstSpirit

To use a FirstSpirit project with Connect for Commerce, the project must be marginally customized using this guide. No in-depth knowledge of FirstSpirit is required for basic use. The delivery contains a FirstSpirit reference project, which includes the necessary adjustments as well as reference components. Depending on the specific project, other content areas and components can be defined.

More complex customizations require advanced FirstSpirit knowledge. More information is provided in the FirstSpirit documentation or in the FirstSpirit Template development guide. In addition, Crownpeak Technology GmbH offers training courses that can be booked on the website.

Finally

In addition, knowledge about the operation of shop system, storefront, and Bridge is required. The required skills strongly depend on the existing and required infrastructure.

5.2.2. Empirical values for an MVP

The following table illustrates the expected effort for creating a minimum viable product (MVP) for an integration. In this case, the MVP is defined as a basic, functional integration. The MVP is able to display content from FirstSpirit for Shop-driven Pages and FirstSpirit-driven Pages in the storefront in JSON format. It also allows editing using the Omnichannel Manager in the ContentCreator. Below, we distinguish between using the provided reference implementation and a fully custom development.

The following estimates are based on experience and may differ significantly from the actual effort required.
Task Reference implementation Custom implementation

Setting up a Bridge

1 day

1 week

Setting up the FirstSpirit project

1 day

1 week

Integration with the storefront

  • Integration Frontend API

  • Support for Shop-driven Pages

  • Support for FirstSpirit-driven Pages

  • Implementation of a component

1 day

 

  • 2 days

  • 3 days

  • 3 days

  • 3 days

5.3. Performance

Before implementing a FirstSpirit Connect for Commerce project, strategies should be considered to ensure long term high-performance operation. The following recommendations should be taken into account for project-specific implementations.

5.3.1. Indices

A large number of CaaS documents can extend the runtime of filter requests and thus affect the overall performance. To enable more efficient retrieval, indices for frequently used document attributes can be created in CaaS collections. By default, CaaS Connect includes pre-built indices for the Preview and Release collection. The Connect for Commerce module extends these with Connect for Commerce-specific indices.

To improve the performance of CaaS requests, the Connect for Commerce module creates an index in CaaS. The index consists of the keys page.formData.type.value, page.formData.id.value, locale.language and locale.country, which are necessary to identify a Shop-driven Page. The index is created for both the Preview and Release collection.

If the existing indices are not sufficient, it is possible to create your own indices. Further information can be found in the CaaS platform documentation.

5.3.2. Aggregations

Aggregations can be used to improve performance in case of a great number of CaaS documents. Aggregations transform the data according to the project requirements and optimize it for frontend requests. Pre-set aggregations are not included in the default scope. If necessary, aggregations can be implemented independently.

Detailed information on this topic can be found in the CaaS platform, RESTHeart and MongoDB documentation.

5.3.3. Caching

Implementing a caching strategy can minimize both latency and server load, ensuring better performance.

A caching strategy can be implemented at various points in the Connect for Commerce architecture. E.g., caching can be implemented on the client side in the storefront in a Headless Commerce scenario. In a Static Commerce scenario, the caching can also be integrated on the server side in the shop system backend. Depending on page content dynamics, individual content areas or even entire pages can be cached for reuse. In both cases, unnecessary Frontend API backend requests are avoided.

Another option is browser caching. In this case, website resources are cached using a cache control header.

5.3.4. Template development

When developing templates, using very deeply nested templates should be avoided, as they can affect the size of CaaS documents. It is therefore recommended to frequently carry out a template performance analysis.

For more information on the preview calculation analysis, see FirstSpirit Developer Documentation.

6. Target architecture and scenarios

FirstSpirit Connect for Commerce can be used in a variety of scenarios. The architecture is described below, as well as the use of the individual Connect for Commerce components within the architecture.

6.1. Headless Commerce

With Connect for Commerce, content can be integrated into Headless shop systems of various technologies.

Frontend API’s role with regards to the shop system and the storefront.

Diagram showing the Frontend API’s role in relation to the shop system and the storefront in a Headless Commerce scenario
Figure 7. Architecture diagram: Connect for Commerce Frontend API in a Headless Commerce scenario

6.1.1. Using the Frontend API

In the Headless Commerce scenario, the Frontend API client is integrated into the storefront. The API requests content and structure data from the Frontend API backend, combines it with data from the headless shop system, and then displays it in the storefront. This enables content editing in ContentCreator. The Frontend API backend connects CaaS and Navigation Service.

6.1.2. Preview

The Frontend API backend is used to decide which content is displayed. Either preview content or released data is then retrieved from CaaS and Navigation Service. For this purpose, the Frontend API client sends a specific HTTP header in its requests to the Frontend API backend. This makes it possible to display both states in the same storefront. The decision whether to display preview content is made based on the integration into the ContentCreator.

For interaction with the ContentCreator in the preview, the Frontend API provides hooks for which callbacks can be implemented, e.g. for reloading the view.

6.1.3. Display in the storefront

To display content, UI components need to be implemented according to the data structure generated by FirstSpirit. It may become necessary to transform FirstSpirit data to do this. The implementation depends on the frontend technology used in the storefront.

6.1.4. Hosting

The hosting for the Bridge, the Frontend API backend, and the storefront as individual applications depends a lot on the whole system’s requirements. To make sure that Connect for Commerce works well, factors such as scalability, performance, and resiliency should be considered before selecting a particular technology. Crownpeak Technology GmbH will host the FirstSpirit server, CaaS, and the Navigation Service. The offer’s particular terms are part of the contract.

Crownpeak Technology GmbH does not host the Bridge, the Frontend API backend, the shop system, or the storefront.

6.2. Static Commerce

Although Connect for Commerce generally takes a headless approach, content created in FirstSpirit can be integrated into systems that use static delivery on the commerce side.

The Frontend API’s role in relation to the shop system and the storefront:

Diagram showing the Frontend API’s role towards the shop system and the storefront in a Static Commerce scenario
Figure 8. Architecture diagram: Connect for Commerce Frontend API in a Static Commerce scenario

6.2.1. Using the Frontend API

Unlike in Headless Commerce scenarios, the storefront in a Static Commerce scenario is fully rendered on the shop system server. This means that the Frontend API client only handles the content editing and the interaction with ContentCreator. To interact with ContentCreator in the preview, the Frontend API provides hooks for which callbacks can be implemented. This way, the view on the server can e.g. be re-rendered after editing content. Data retrieval from CaaS and the Navigation Service takes place using the shop system server’s Frontend API backend. This is where the data is rendered and delivered.

For the integration into statically generated storefronts, the Frontend API client is available as a JavaScript file.

6.2.2. Preview

The preview in a Static Commerce scenario is identical to the Headless Commerce scenario.

6.2.3. Display in the storefront

The display in the storefront in a Static Commerce scenario is identical to the Headless Commerce scenario. The implementation depends on the SSS and template engine technology used.

6.2.4. Hosting

The hosting in a Static Commerce scenario is identical to the Headless Commerce scenario.

7. Use cases

In the course of a project, various situations can occur that require a certain course of action. Dedicated how-to guides are available for the following use cases.

8. Frequently Asked Questions

Can Connect for Commerce be operated on-premises?

Due to its Cloud-native architecture, Connect for Commerce is designed exclusively for operation in the Cloud. It’s therefore not possible to run Connect for Commerce in an on-premises environment.

Can existing integrations be migrated?

Existing integrations can be migrated for operation with Connect for Commerce. Migration strategies and the complexity are project-dependent. For more information, contact Customer Success Management or info-dach@crownpeak.com.

Which components are hosted by Crownpeak?

Crownpeak operates the FirstSpirit server, CaaS, and the Navigation Service in the Cloud. Crownpeak is also responsible for installing and updating the Connect for Commerce module and all related modules.

Attention: The Bridge, the Frontend API backend, the shop system, and the storefront are not hosted by Crownpeak.
The hosting of the individual components of the overall system depends heavily on the requirements of this system. To ensure optimal functionality of Connect for Commerce, factors such as scalability, performance, and resiliency should be considered before selecting a particular technology.

Hosting providers like Netlify can be a good platform for delivering high-performance and scalable microservices in modern Composable Commerce scenarios. The provision of sample Dockerfiles facilitates the start with Docker-based services such as AWS or Kubernetes. Note that the Dockerfiles are mere examples and must be adjusted to the individual requirements.

Which components are maintained by Crownpeak?

Crownpeak assumes product liability and maintenance based on the service agreements valid at the time of conclusion of contract. For Connect for Commerce, Crownpeak usually provides maintenance for the Connect for Commerce module and the Frontend API.

Maintenance for reference implementations provided by Crownpeak, including the reference project, the Bridge, the Frontend API backend service, and the storefront are the customer’s responsibility. This also applies to the shop system.

Which shop integrations does Connect for Commerce support?

Given the shop-agnostic implementation approach, Connect for Commerce can be integrated into any shop system, but also into self-implemented e-commerce systems or Product Information Management solutions. The basic requirement is a functioning API for catalog information in the shop system.

To minimize implementation effort, reference implementations are provided on GitHub. These can be used both out of the box, or as a reference for custom implementations.

Which reference implementations are available on GitHub?

For a static use case, a Spryker reference implementation is available. For a headless use case, the Salesforce PWA Kit reference implementation can be used.

Overview of reference implementations available on GitHub:

Bridges:

Storefronts:

Backend service:

Is the source code for the reference implementations open source?

The source code for all Connect for Commerce components published on GitHub is subject to the terms of Apache-2.0 license.

What is the expected implementation effort?

The implementation effort can vary greatly depending on the project and depends on various factors. A rough estimate can be found in the subchapter Empirical values for an MVP. Note that these are estimates which do not guarantee any actual implementation effort.

9. References

References for setting up FirstSpirit Connect for Commerce:

APIs:

Reference implementations on GitHub:

npm-modules and scripts:

Modules:

FirstSpirit Connect for Commerce is a product of Crownpeak Technology GmbH, Dortmund, Germany.
Only a license agreed upon with Crownpeak Technology GmbH is valid for using the module.

11. Help

The Technical Support of the Crownpeak Technology GmbH provides expert technical support covering any topic related to the FirstSpirit™ product. You can get and find more help concerning relevant topics in our community.

12. Disclaimer

This document is provided for information purposes only. Crownpeak Technology GmbH may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. Crownpeak Technology GmbH specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.