DocumentationExperience Cloud KCS

Configure environment-specific PDF Embed API Client IDs with a shared site structure in AEM as a Cloud Service

Last update: September 4, 2026

This article explains how to configure environment-specific PDF Embed API Client IDs in Adobe Experience Manager (AEM) as a Cloud Service while maintaining a shared /content/site and /conf/site structure. To fix this, store a placeholder in the shared PDF Viewer configuration, override the clientId value with a Cloud Manager environment variable, and validate the resolved value at runtime for each environment.

Description description

Environment

  • Adobe Experience Manager as a Cloud Service
  • Adobe Experience Manager Sites PDF Viewer component
  • Development, Stage, and Production environments
  • Shared /content/site and /conf/site structures

Issue/Symptoms

When the same /content/site and /conf/site structures are used across Development, Stage, and Production environments, each environment can require a PDF Embed API Client ID that matches its serving domain. The configuration must provide the correct runtime value without duplicating content or configuration packages.

  • The PDF Embed API Client ID is authorized for a domain, not for an environment name alone.
  • The PDF Viewer component retrieves the clientId from Sling Context-Aware Configuration at /conf/<site>/sling:configs/com.adobe.cq.wcm.core.components.internal.services.pdfviewer.PdfViewerCaConfig.
  • Using the wrong environment or domain value can cause the wrong Client ID to be applied at runtime.

Cause

The shared Sling Context-Aware Configuration contains the base clientId value, but it does not select a different value solely from the AEM run mode. The Sling Context-Aware Configuration Override Provider can override the clientId with a Cloud Manager environment variable, allowing the same content and configuration structure to be deployed across environments.

Resolution resolution

Follow the steps below to resolve the issue:

  1. Place one shared PDF Viewer CA-Config node in the content package at /conf/site/sling:configs/com.adobe.cq.wcm.core.components.internal.services.pdfviewer.PdfViewerCaConfig, and set clientId to a placeholder value (for example, __NOT_OVERRIDDEN__) to prevent accidental use if the override fails.

  2. Configure the Sling Context-Aware Configuration Override Provider:

    • Add a factory configuration for org.apache.sling.caconfig.impl.override.OsgiConfigurationOverrideProvider to the appropriate run-mode folders, such as config.author.dev/, config.author.stage/, and config.author.prod/.
    • For Publish instances, add the configuration to the corresponding folders, such as config.publish.dev/, config.publish.stage/, and config.publish.prod/, as needed.
    • Configure the override for the PDF Viewer clientId property to use the quoted environment-variable reference "$[ env:PDF_EMBED_CLIENT_ID] ".
    • Keep the quotation marks around the environment-variable reference. Without them, the override is ignored.

  3. In Cloud Manager, define PDF_EMBED_CLIENT_IDfor each target environment:

    • Set the environment-specific PDF Embed API Client ID.
    • Use the Step Applied option to apply the value to Author or Publish when different values are required.

  4. Deploy the content and configuration packages through the approved Cloud Manager deployment process.

  5. After deployment, verify that the correct Client ID is applied by checking the rendered page or the resolved configuration at runtime.

Note: The JCR node continues to display the placeholder value. The runtime value is supplied by the Cloud Manager environment variable; this is expected.

recommendation-more-help
experience-cloud-kcs-help-kbarticles