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

Progressive web applications (PWAs) use next-generation web technology standards to deliver app-like user experiences through mobile and desktop devices that are fast, secure, and responsive. PWA Studio is a collection of tools and examples that developers can use to build feature-rich, high-performance e-commerce storefront PWAs.

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

Out of the box, PWA Studio integrates seamlessly with Adobe Commerce via GraphQL providing unlimited options for creating innovative and engaging storefronts and other digital experiences.

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.

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

In the following example, we’ll showcase a blog extension that defines Adobe Experience Manager content for headless consumption using Content Fragments and displays the content in your PWA in a dedicated blog section.

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

1. Follow the Content Fragments documentation to enable a GraphQL endpoint for your Adobe Experience Manager project. Your setup might vary. However, for this example, the endpoint should be available at:

{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.

• Example: https://venia.magento.com

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.

Step 2: Set up Extension in PWA Studio App

1. First, you’ll add the extension to your PWA Studio project. You can add the extension from a local version by checking out the GitHub repository and running the following command:

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:

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:

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.