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.