Introducing Adobe Experience Manager’s New Headless Extension for Adobe Commerce PWA Studio

Authors: Mark J. Becker, Markus Haack, and Jody Arthur.

Jaemi Bremner
Jun 10 · 10 min read

This is the first part of a series of the new headless architecture for Adobe Experience Manager. In this post, Adobe Experience Cloud introduces its Adobe Experience Manager Headless Extension for PWA Studio that enables developers to leverage headless architectures to build app-like experiences for their customers that are fast, secure, and delightful on any device, mobile or desktop.

Adobe Experience Manager provides the most innovation-friendly content tools in the market. Adobe Experience Manager enables you to more easily use and reuse your content across the web, mobile, and emerging channels such as IoT devices. Now, Adobe is introducing a new extension that enables Adobe Experience Manager authors to manage rich content and commerce experiences for the progressive web apps (PWAs) they build in PWA Studio by Adobe Commerce, powered by Magento.

In this blog, we’ll discuss how these powerful tools can be used together to create unparalleled customer experiences and show you an example you can implement today.

Progressive web apps are the future of digital commerce

PWA Studio leverages headless architecture, which separates the front-end shopping experience from the back-end systems via APIs. This type of architecture gives developers enormous flexibility in how they build for different sales channels extending beyond what their commerce platform or content management system (CMS) provides.

Integrating headless content from Adobe Experience Manager into your PWA Studio application

Content Fragments are pieces of content with a predefined structure that allows them to be consumed in a headless way using GraphQL as API in different formats (e.g. JSON, Markdown) and independently rendered. Content fragments include all the data types and fields required for GraphQL to ensure your application only requests what is available and receives what is expected. The flexibility they provide in terms of how they are structured makes them perfect for use in multiple locations and over multiple channels.

Designing the structure you need is easy with the Content Fragment Model Editor within Adobe Experience Manager. The main challenge to integrating Adobe Experience Manager Content Fragments (or any other data) with your PWA Studio application is fetching data from multiple GraphQL endpoints. This is because out of the box, PWA Studio works with a single Adobe Commerce GraphQL endpoint.

Figure 1: How Apollo Client within PWA allows you to fetch product data and Adobe Experience Manager Content Fragments from different GraphQL endpoints.

To enable data fetching from multiple sources, you can customize the Apollo GraphQL client used by PWA Studio to route queries made by React components to the appropriate GraphQL endpoint. Each React component in the PWA that needs to fetch data can define a target in the query context with each query it issues. Apollo GraphQL client reads the context and routes the query to the appropriate destination.

This integration pattern combined with your content makes a wide range of use cases possible. Adobe Experience Manager Content Fragments can be used for many different scenarios where structured content pieces are needed to enrich a PWA, including:

  • Product Enrichments: Enrich product display and product detail views with extra structured content such as related product information or articles, extra attributes, etc.
  • Store Finder: Brands with physical stores can use Content Fragments to improve customer experiences by building a store finder into their PWA that provides store locations and directions, hours of operation, and contact information.
  • Customer Service: Just like a brick-and-mortar store, an online store needs a customer service area to provide essential information such as FAQs, payment & delivery information, contact forms, etc.
  • Documents: Content Fragments in combination with Adobe Experience Manager Assets can be used to make reference documents available on a PWA, such as product manuals and guidelines, datasheets, security information, release notes, or other product-related documents.
  • Blog Content: Content Fragments can also be used to display engaging content including text and images in a dedicated blog section of a PWA.
  • Product Release Notes: Content fragments are useful for providing changelogs detailing product updates and bug fixes for apps, too.

Getting started with an example use case

Prerequisites for this implementation include having a cloud-based or local instance of Adobe Experience Manager and Adobe Commerce available. You will also need to have your PWA Studio project ready or quickly create one yourself based on the Venia sample storefront.

All code discussed in this example can be found in the PWA Studio Extension for Adobe Experience Manger headless on GitHub. This extension contains some sample React components that will display blog posts based on Content Fragments which are included as an Adobe Experience Manager content package as well.

Step 1: Setting up the GraphQL Endpoint in Adobe Experience Manager

{aem-publish}/content/graphql/global/endpoint.json

2. To make the endpoint accessible, you’ll need to change some configurations in Adobe Experience Manager. The first configuration enables Cross-Origin Resource Sharing (CORS) and adds an exception to the origin filter so that your client-side application can access the endpoint, even if it runs on a different domain. Similarly, the second configuration is required to add an exception for the referrer filter. You can find full examples of both configurations in the config package within the extension repository.

3. To configure the CORS, use the com.adobe.granite.cors.impl.CORSPolicyImp configuration.

4. Set the allowedorigin property to the full hostname of your PWA application.

5. To configure the Apache Sling Referrer Filter use the following configuration: org.apache.sling.security.impl.ReferrerFilter.cfg.json

6. Set the allow.hosts property to the hostname of your PWA application.

  • Example: venia.magento.com

7. The last and most important piece to enable the GraphQL endpoint and deliver data is to add the Content Fragment models and Content Fragments.

For this example, we prepared some models and fragments in the content package within the extension repository which you can add to your project. Be aware that because the GraphQL schema exposed by the Adobe Experience Manager GraphQL endpoint relates directly to the Content Fragment models, any change in the models needs to be considered in the frontend code as well. You can access the Content Fragment model editor via the Tools menu within Adobe Experience Manager.

Figure 2: UI for the Content Fragment Model Editor in Adobe Experience Manager.

Step 2: Set up Extension in PWA Studio App

yarn add — dev file:{path-to-extension-repo}/aem-cfm-blog-extension/extension 

We recommend using the local version, as this lets you apply changes directly in the extension as you need them. In the future, the extension will also be available via npm public registry and can be added using the following alternative command:

yarn add — dev @adobe/pwa-studio-aem-cfm-blog-extension

2. In the next step, we adapt the Apollo GraphQL client to support the routing of requests to different endpoints. Since PWA Studio extensions can’t directly adapt the Apollo client, the extension provides a wrapper that you can apply in src/index.js of your PWA Studio application:

import { linkWrapper } from ‘@adobe/pwa-studio-aem-cfm-blog-extension’;

// …
<Adapter apiBase={apiBase} apollo={{ link: linkWrapper(apolloLink) }} store={store}>

We invite you to have a closer look at this customization by checking out the linkWrapper.js file in the extension repository. This is also the location you can adapt if you want to integrate even more backend systems. In the same context, let’s have a quick look at how the React components use Apollo Client to send queries to Adobe Experience Manager:

const addBlogToNavigation = require('@adobe/pwa-studio-aem-cfm-blog-extension/src/addBlogToNavigation');function localIntercept(targets) {
addBlogToNavigation(targets);
}

As you can see in this code snippet, the components provide a target attribute to the query context which can be picked-up by the Apollo link component. If no target attribute is provided in the context, GraphQL requests will be sent to the default location which is Adobe Commerce.

3. To display blog posts in the PWA, we need to define a blog section. The extension contains a React component called BlogIndexPage which takes care of showing a list of all recent blog posts and another component called BlogPostPage, which displays the full version of a single blog post. The extension uses the PWA Studio extensibility framework to register two routes that point to these two components. The registered routes are:

FIgure 3: Registered Routes

Now, to allow a visitor to get to the Blog section, a Blog entry should be added as an item to the navigation components. You can apply this customization by adding the following code to your local-intercept.js file which should normally be present in the root folder of your PWA Studio application:

const addBlogToNavigation = require(‘@adobe/pwa-studio-aem-cfm-blog-extension/src/addBlogToNavigation’);function localIntercept(targets) {addBlogToNavigation(targets);}

4. The Apollo client as customized by the extension expects the GraphQL endpoint of Adobe Experience Manager to be at {pwa-hostname}/endpoint.json. To map the endpoint to this location, you can customize the Unified Progressive Web App Response Definition (UPWARD) configuration of your PWA Studio application.

a. First, add the AEM_CFM_GRAPHQL variable to the .env file in the root folder of your project and adapt it to point to your Adobe Experience Manager Content Fragment GraphQL endpoint, but without the endpoint.js suffix.

Example: AEM_CFM_GRAPHQL={aem-publish}/content/graphql/global

b. Now you can use this variable for a proxy resolver within your UPWARD configuration. A sample UPWARD configuration could look like this:

response:
resolver: conditional
when:
- matches: request.url.pathname
pattern: ^/endpoint.json(/|$)
use: aemProxy
default: veniaResponse
aemProxy:
resolver: proxy
target: env.AEM_CFM_GRAPHQL
ignoreSSLErrors: true
status: response.status
headers: response.headers
body: response.body

Strictly speaking, the UPWARD configuration is optional if CORS is configured on the Adobe Experience Manager side. However, we recommend hiding the actual Adobe Experience Manager GraphQL endpoint behind UPWARD or a similar reverse proxy.

After following these steps, you should now see a new navigation entry in your PWA that leads you to the new Blog page. The page will load recent blog entries from Adobe Experience Manager and display them as a list. When you click on a list item, you get to the full version of the blog post.

Figure 3: The end result of our example using Content Fragments to display blog posts in a dedicated blog section of a PWA.

Preparing your PWA to consume headless content from Adobe Experience Manager

For communication between the PWA and multiple backend services, there are two main integration architectures that we can recommend:

  • Request routing on the level of Apollo client as we used it in our example is the easiest solution to ensure your PWA can communicate with multiple backend services. It does not require any additional services, nor does it have any performance or latency impact. However, it must be implemented for every client that consumes data from your headless backends.
  • If you have a lot of different touchpoints (e.g. PWA, mobile app, in-store screens) that consume data, you should consider an architecture that uses GraphQL federation within a Backend for Frontend (BFF) service. Applying this pattern allows all your clients to communicate with a single GraphQL endpoint that is exposed by a service (BFF) that sits in between your clients (PWA) and the backend systems. This BFF can use GraphQL federation to combine schemas from different endpoints into a single one. This schema can be dynamically extended if you decide to add further backend services and it’s transparent to the clients, meaning the clients do not need to know about the backend services directly. However, there are some clear disadvantages of this architecture, including the latency introduced by the additional hop and the requirement for adding an additional service, which increases the overall complexity of your project.

After deciding on the right architecture for your project, you can start creating your custom schema based on Content Fragment models, fill it with data and create React components that consume and render it. In the blog post extension, you will find examples of all the different aspects you need to kickstart your application.

This is just one of the many possible use cases the Adobe Experience Manager Headless Extension for PWA Studio makes possible. In future posts, we’ll illustrate more ways that you can leverage headless architectures to build app-like experiences for your customers on any device that is fast and secure.

Follow the Adobe Tech Blog for more developer stories and resources, and check out Adobe Developers on Twitter for the latest news and developer products. Sign up here for future Adobe Experience Platform Meetups.

Resources

  1. Adobe Commerce
  2. PWA Studio
  3. Adobe Experience Manager Headless Content Management System (CMS)
  4. Getting Started with PWA Studio
  5. PWA Studio on GitHub
  6. PWA Studio’s Extensibility Framework
  7. PWA Studio Extension for Adobe Experience Manager Headless on GitHub
  8. Adobe Experience Manager Headless Tutorials
  9. GraphQL Overview
  10. Introduction to Apollo Client
  11. Headless Content Delivery Using Content Fragments with GraphQL
  12. Adobe Experience Manager GraphQL API for Use with Content Fragments
  13. Understand Cross-Origin Resource Sharing (CORS)
  14. OSGi Configuration Settings
  15. Unified Progressive Web App Response Definition (UPWARD)
  16. Single Page Application (SPA) Editor Overview

Adobe Tech Blog

News, updates, and thoughts related to Adobe, developers…