style
content

Building Integrations with AEM Edge Delivery Services

Edge Delivery Services is designed to be a content-first platform, but many websites require data-driven functionality such as server-side-generated content, authentication, integrations with protected APIs, and Identity Provider (IDP) connections. This document provides a guide to the available integration options and when to use each approach.

When building integrations with AEM Edge Delivery Services, the choice of runtime depends on your specific requirements:

For live traffic dependencies: Use Standard API integrations from the front-end OR Edge Workers available on your CDN.

For author-side operations: Use Edge Workers or Adobe App Builder actions for integrations that do not get invoked via live traffic.

For dynamic pages: Use the BYOM (Bring Your Own Markup) overlay approach. The BYOM overlay pattern is particularly powerful as it allows you to generate real pages with proper SEO, caching, and performance benefits while maintaining the flexibility of your chosen runtime. You can use your own custom worker or the OOTB json2html service if you want to convert from JSON to HTML.

For publish-based triggers: Use the audit log API method to get published content.

To embed content in non-AEM experiences: Use the aem-embed web component.

Standard API Integrations

These are simple, straightforward integrations where the front end (block or page-level code) calls an API, receives a response, and builds the DOM accordingly. Approximately 95% of integrations fall into this category.

Client-side JavaScript interacts with APIs to add dynamic functionality after the static site has loaded. This can include user authentication, e-commerce features (e.g., cart functionality), payment processing, search capabilities, and more.

This category also includes React components, Web Components, front-end widgets, and Martech plugins that call their respective API endpoints for similar purposes.

No additional setup is required beyond adding the appropriate code. However, if the API cannot be accessed directly from the front end or if you need to modify the request or response, you'll need to use Edge Workers to handle that logic.

Integration Runtime Options

When building integrations with AEM Edge Delivery Services, you have several runtime options to choose from. The choice depends on your specific use case, performance requirements, and whether you're serving live traffic or handling author-side operations.

Best for: Live traffic, dynamic content generation, authentication and authorization, middleware needed for secure API integrations

Edge Workers on your CDN provide the most performant and scalable solution for integrations that serve live traffic. They run at the edge, close to your users, ensuring minimal latency and high availability.

CDN edge worker examples:

Cloudflare Fastly Akamai AWS Cloudfront

Adobe App Builder

Best for: Author-side integrations, admin operations, background processing

Adobe App Builder actions is ideal for integrations that don't serve live traffic but handle author-side operations, admin functions, or background processing.

AEM Publish Tier Servlets

Traditional AEM servlets can be used for legacy integrations that require direct access to AEM APIs but only on the author-side.

Note: Do not use this option as a dependency for live traffic hitting your website or for long running processes / background processing.

Authentication and Authorization Examples

Edge Worker Authentication

Implement authentication check in Edge Workers on your CDN for the best performance and security:

// Example Edge Worker authentication example
export default {
  const isValidToken (request) {
	// Your authentication logic here (e.g., check for a valid cookie or token)
	return false; // For demonstration, assume unauthenticated
  }

  async fetch(request, env) {
	// Check authentication
	const authHeader = request.headers.get('Authorization');
	if (!authHeader || !isValidToken(request)) {
  	const loginPage = 'https://www.mysite.com/login';
  	// redirect them to the login page
      return Response.redirect(loginPage, 302);
	}
	// If authenticated, proceed to fetch the original resource or perform other actions
	return await fetch(request);
  }
};

IDP Integration

For Identity Provider integrations, edge workers can handle OAuth flows, JWT validation, and session management:

// Example IDP integration in an Edge Worker
async function handleOAuthCallback(request) {
  const url = new URL(request.url);
  const code = url.searchParams.get('code');
 
  // Exchange code for token
  const token = await exchangeCodeForToken(code);
 
  // Generate user-specific content
  const userContent = await generateUserContent(token);
 
  return new Response(userContent, {
	headers: { 'Content-Type': 'text/html' }
  });
}

Protected API Integrations

API Gateway Pattern

Use edge workers as an API gateway or middleware to protect your backend APIs. This also allows you not to expose any secrets or tokens needed to access the backend APIs:

// Example API gateway in Cloudflare Worker
export default {
  async fetch(request, env) {
	// Validate request
	if (!isValidRequest(request)) {
  	return new Response('Forbidden', { status: 403 });
	}
   
	// Add authentication headers
	const apiRequest = new Request(request);
	apiRequest.headers.set('X-API-Key', env.API_KEY);
   
	// Forward to protected API
	const apiResponse = await fetch(env.API_URL, apiRequest);
	const json = await apiResponse.json();
   
	return new Response(json, {
  	headers: { 'Content-Type': 'application/json' }
	});
  }
};

Dynamic Content Integration Patterns

Bring Your Own Markup (BYOM) Overlay

For dynamic content generation, we strongly recommend using BYOM as an overlay content source. This approach allows you to create a renderer (CDN Edge Worker, Adobe App Builder function, etc.) that generates Helix-compatible markup and serves it as an overlay to your primary content source.

Configuration Example:

  "content": {
	"source": {
  		"url": "https://acme.sharepoint.com/sites/aem/Shared%20Documents/website"
	},
	"overlay": {
  		"url": "https://your-renderer.acme.com/dynamic-content",
  		"type": "markup"
	}
  }

Benefits of this approach include the following:

JSON to HTML Service

Using the same BYOM approach, you can use the JSON2HTML service as an endpoint in your overlay configuration for creating dynamic pages with content coming from JSON endpoints. This service converts JSON responses to Helix-compatible HTML markup with some minimal configuration.

Integrations Based on Content Publish Trigger

To trigger third-party endpoints or workflows when content is published, the recommended approach is to use the Audit Log API. This API provides a reliable way to detect publish events by polling for audit log entries at regular intervals.

How It Works

Example: Using GitHub Actions

A practical implementation of this pattern using GitHub Actions can be found in the Helix Website repository.

You can adapt this approach to suit other environments or CI/CD systems (e.g., Jenkins, CircleCI, AWS Lambda).

Note: your site administrator can generate API Keys for you to interact with the Admin API.

Migration Guide

From Traditional AEM Servlets

If you're migrating from traditional AEM servlets to edge workers:

1. Identify Use Cases: Determine which servlets can be migrated. In most cases, content related servlets and services would most likely not need to exist anymore and you only need to focus on servlets or services used for integrations.

2. API Compatibility: Ensure your edge worker can access required APIs

3. Gradual Migration: Migrate one endpoint at a time

4. Testing: Thoroughly test each migrated endpoint

5. Performance Comparison: Compare performance before and after migration

https://www.aem.live/developer/byom

https://www.aem.live/blog/folder-mapping-deprecated

https://www.aem.live/blog/byom-content-overlays