Schema App Connector for AEM Overview

Adobe Experience Manager (AEM) is a comprehensive content management solution for building websites, mobile apps, and forms.

The Schema App Connector for AEM was created to serve a growing subset of our customers who host their websites on AEM. The connector allows our customers to get JSON-LD server-side, which increases schema markup deliverability and reduces client page rendering time. With this integration method, our customers are able to deploy up-to-date schema markup to their websites at scale.

Note: Currently, this option is only available to Enterprise Customers who have paid for AEM Configuration Services

TABLE OF CONTENTS

• Technical Design
  • Integration
  • JSON-LD Injection
    • Why the Scheduler runs on Author and Publisher
  • Headless AEM
• Permissions & Services
• Security Features
• Installation Guides
• Additional Resources

Technical Design

The Schema App connector for AEM locally caches your Schema Markup so it can be deployed with the rest of your content when the page is rendered. This provides greater assurance your schema markup will load in time for Search engines.

Integration

The first step in the process is integrating with AEM using one of the following methods:

• Classic AEM: Cloud (JavaScript)
• Classic AEM: On-Premise (JavaScript)
• Headless AEM: Cloud (JavaScript)
• Headless AEM: On-Premise (JavaScript)
• Crawler + AEM

If you choose to use the JavaScript option, AEM will inject highlight.js into your pages when you add the configuration to your site. If you chose the Crawler option, once the configuration is added to your pages you can start a crawl to begin deployment.

[Fig. 1] Initial Setup Flow

1. After installing the plugin, you (the AEM author) can log in to AEM, create a new configuration, and add the details you copied from Schema App.
2. Next, you will submit the details to Schema App to register the AEM URL.
3. Schema App will return a Success response if the account details and URL are correct.
4. You will add the newly created configuration to the respective sites where you want the plugin enabled.
5. Lastly, you will publish the AEM page where we have configured the plugin.

The Schema App AEM Connector is now ready to receive Schema Markup webhooks.

JSON-LD Injection

Once the registration is all set up, the process of inserting and updating JSON-LD can proceed.

[Fig. 2] JSON-LD Injection Flow

1. The Schema App Data API Scheduler runs on a predetermined schedule (default: every 30 minutes) on both Author and Publisher. Each instance independently fetches JSON-LD from Schema App and writes it to a schemaapp node under that page's jcr:content. Markup is not editorial content, so it does not wait for an author to publish the page. See Why the Scheduler runs on Author and Publisher.

2. Once a response is received from the DATA API call, if it's not blank we will find that page in AEM, and create a 'schemaapp' node under the page node and set the JSON-LD. If a node already exists then the JSON-LD is stored and updated.
   
   

3. After updating JSON-LD in the page node, we will make a call to the AEM dispatcher to clear the cache for that particular page. This request is sent from the Publisher instance as shown above.

4. Once a user visits the website URL (e.g. page1), a request first comes to the Dispatcher as we have already cleared the cache for page1, and redirects to the Publisher. In the Publisher, there is a JSP script (headlibs.jsp) that will conditionally insert the JSON-LD Schema Markup into the head tag of the page if the Schema App node exists under the page node. This leverages the apache sling framework that AEM is based on. This JSP is invoked only after setting up the Schema App configuration in Author instance upon plugin installation. Additionally, this injection only occurs for non-headless installations.

NOTE: When a page is published from Author, AEM replicates the Author jcr:content tree to Publisher. If Author did not also have a schemaapp node, that publish could remove or overwrite the Publisher copy. The scheduler therefore writes on Author as well, so a later content publish does not strip live markup.

Why the Scheduler runs on Author and Publisher

AEM developers often ask: if the Schema App node lives under jcr:content, why does the scheduler also run on Publisher? Wouldn't Author replicate that node whenever JSON-LD is updated?

Writing a node on Author does not replicate it. The schemaapp node is included in replication only when that page (or that node) is Activated. Schema markup is produced by Schema App on its own schedule, independently of authors publishing pages. Live HTML is rendered from Publisher JCR (then cached by Dispatcher), so Publisher must have current JSON-LD without waiting for a content publish.

The connector therefore writes JSON-LD locally on each instance:

• Publisher is the instance that serves the live site. The scheduler on Publisher fetches JSON-LD from Schema App and stores it under jcr:content/schemaapp on that instance. Dispatcher cache invalidation is also a Publish-side operation (flush agents under /etc/replication/agents.publish).
• Author keeps a matching schemaapp node so that when an author later publishes the page, AEM's replication of jcr:content does not overwrite or remove the Publisher copy. Author also uses this node for preview.

After saving the node, the connector may Activate the schemaapp path. On Author that can replicate the node to Publish; on Publish that is the standard Dispatcher flush pattern. Live markup does not depend on that Author-to-Publish hop succeeding, and it does not require a content publish workflow.

Headless AEM

For decoupled AEM, when a user requests a page, the request will be served by the front end (React JS or Angular JS). The AEM front end will call the page.model.json API and fetch the page content as JSON.

When the response is received from the API, scripts are created and added to the HTML header section. Subsequent API calls to the JSON API generate and insert the required Schema Markup on the page.

[Fig 3.] Example of Sample script

Cache Invalidation

In general, invalidating the dispatcher cache will not be necessary. Schema App will send a request when the markup is updated.

Permissions & Services

The below table highlights the permissions and services that will be required for the plugin to work efficiently.

User Permissions: Content-author access is required to create new Cloud configurations. No other special access is required.

Security Features

• The source of JSON-LD is validated by the Schema App connector to ensure that malicious scripts or JSON-LD can not be injected into a website.
• Schema App optimizes content visible on the web, primarily public data. The script is not able to change website content. See Schema App's Privacy Policy.
• Validation of metadata and content of JSON-LD

Installation Guides

• Classic AEM: Cloud (JavaScript)
• Classic AEM: On-Premise (JavaScript)
• Headless AEM: Cloud (JavaScript)
• Headless AEM: On-Premise (JavaScript)
• Crawler + AEM

Additional Resources

• AEM Troubleshooting and FAQs
• Data Flow and Security Overview