Adobe Experience Manager (AEM)

This guide will walk you through how to send approved creative assets from Adobe Experience Manager (AEM) into an advertiser’s Koddi creative library. Your backend uploads the approved image file to Koddi for hosting on Koddi’s CDN. For in-room/onboard screens, also package the same approved image into the publisher’s local content bundle.

Your team builds the AEM controls and backend integration. Campaign operators select creatives and associate them with ad groups in Koddi. AEM does not need campaign or ad group IDs.

Publishing model

Create the advertiser-owned creative with its asset and validity fields, upload the approved image bytes, and verify the result before approval. Koddi uses the uploaded image for the creative preview and connected ad delivery.

Publisher CDN fields are optional supporting metadata. They do not replace the image upload. For in-room/onboard delivery, the publisher distributes the same approved source image separately and resolves it locally by asset ID, version, and rendition.

Integration flow

flowchart TD
    A[Select approved asset and advertiser] --> B[Freeze version and validity]
    B --> C[Create advertiser creative]
    C --> D[Upload image to Koddi]
    D --> G[Verify creative and preview]
    B --> H{Package for in-room/onboard}
    H -->|Yes| I[Build and distribute image bundle]
    I --> J[Track installation per target]

Step 1: Configure the Koddi connection

Use the management API base URL and authorization value supplied by Koddi. The documented base URL is:

https://koddi.io/console/v1

Store the following in trusted backend configuration, separately for test and production:

SettingPurpose
API base URLKoddi management API environment
Member group IDScope for advertiser and creative calls
Koddi API credentialAdvertiser lookup, creative reads/writes, and image upload
Publisher timezoneFor asset validity timeframes
Allowed asset foldersAEM content the integration can read
Advertiser access rulesAdvertisers each author or group can select

Store credentials in a secret vault or encrypted backend configuration. The AEM browser interface calls your backend; only the backend calls Koddi with the integration credential. Add approval permission only when the integration is authorized to approve creatives.

Access requirements

System or identityAccess required
KoddiNo AEM account or inbound AEM access for this push integration
Publisher backendRead approved AEM metadata; read approved image bytes for upload and in-room/onboard packaging
Backend status writerWrite integration-owned mapping/status fields in AEM or the integration database
Koddi integration API accountRead advertisers; create, read, and update creatives; upload images; write asset and validity fields
Publisher distribution serviceRead approved image files, build bundles, and distribute them to target devices

Step 2: Connect the AEM backend

For AEM as a Cloud Service:

  1. Create an Adobe App Builder project and separate test and production workspaces.
  2. Configure the selected AEM Assets API with OAuth Server-to-Server credentials and the appropriate product profile.
  3. Authorize the technical identity for the advertising asset folders.
  4. Verify metadata retrieval and, where needed, downloading the approved rendition.
  5. Deploy backend handlers for advertiser lookup, publishing, status, and retry.

Follow Adobe’s OAuth Server-to-Server setup. Keep Adobe and Koddi credentials separate.

For other releases, use the version supplements.

Step 3: Add the AEM publishing controls

Implement these controls in the customer’s authoring interface:

ControlBehavior
AdvertiserSearch Koddi names; save the native advertiser ID
Destination URLClick-through URL
RenditionApproved image size and format for the placement
Asset metadataSource asset ID and any publisher CDN ID or URL
VersionImmutable approved publication version
Valid from / valid toDisplay window entered in the publisher's timezone
Package for in-room/onboardEnqueue a separate publisher content bundle job
Publish / retryStart or resume a durable publishing job
StatusShow Koddi publication and device installation separately

For Cloud Service, the AEM Assets View extension provides an author panel when the required entitlement and enablement are available. Otherwise, add these controls to the existing author workflow. No public Adobe marketplace submission is needed for the customer’s internal implementation.

Persist selections in custom AEM metadata or an integration database keyed by immutable asset identity. The controls and metadata are customer-built.

Step 4: Load advertiser names from Koddi

Call Advertisers from the backend:

GET /member_groups/{memberGroupId}/advertisers
Authorization: {Koddi-provided authorization value}

Display name and advertiser_id; persist advertiser_id. Parse the response envelope returned by the environment and handle pagination when present. Filter destinations using your author access rules and advertiser status.

Use a folder-level advertiser default with an authorized per-asset override. Revalidate the advertiser on the backend for every publish. Moving an AEM asset to another folder must not silently move an existing creative to another advertiser.

Step 5: Prepare a publication job

After advertising approval, capture one immutable snapshot containing the selected advertiser, rendition, click destination, six asset fields, and publisher timezone.

Validate content rights, completed rendition processing, MIME type, dimensions, source access, advertiser permissions, and validity dates before creating the job. AEM processing completion alone is not advertising approval.

Use a durable queue and persist progress after every Koddi operation. For large file transfers, run the upload in a worker sized for the rendition and runtime limits.

Step 6: Define the creative and validity contract

Core creative fields

SourceKoddi field
Selected advertiseradvertiserId in the URL path
Connection member groupmemberGroupId in the URL path
Asset titlename
Image classificationmedia_type
Click destinationurl
Ad copytext, or "" when not applicable

Asset and validity fields

Include these fields in the creative Create and Update requests and return them in Get Creative.

FieldTypeMeaning
ext_asset_idString, optionalStable external source identity, normally the immutable AEM asset ID
cdn_asset_idString, optionalPublisher CDN identifier
cdn_urlString, optionalPublisher-hosted image URL for traceability or configured connected fallback
versionString, optionalImmutable approved publication version for the rendition
valid_fromISO 8601 timestamp, optionalStart of permitted display, inclusive
valid_toISO 8601 timestamp, optionalEnd of permitted display, exclusive

Keep the click destination url, publisher image cdn_url, and Koddi-hosted image URL separate. The publisher CDN ID and native Koddi creative ID also identify different records.

For in-room/onboard rendering, resolve ext_asset_id, version, and rendition to the exact installed image. The local image and the uploaded Koddi image must come from the same approved source snapshot.

Step 7: Publish through the Koddi creative endpoints

All paths below are relative to the configured management API base URL and require the Koddi Authorization header.

ActionMethodEndpoint
CreatePOST/member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives
Upload filePOST/member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives/{creativeId}/image_upload
Read and verifyGET/member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives/{creativeId}
UpdatePATCH/member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives/{creativeId}
Approve, when authorizedPOST/member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives/{creativeId}/approval

Create the creative with its asset and validity fields

Call Create Creative:

POST /member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives
Authorization: {Koddi-provided authorization value}
Content-Type: application/json
{
  "name": "Winter offer landscape",
  "media_type": "image",
  "url": "https://www.example.com/winter-offer",
  "text": "",
  "ext_asset_id": "urn:aaid:aem:6b8a727b-a51c-4dac-b078-64cf2741cf22",
  "cdn_asset_id": "winter-offer-v3-landscape",
  "cdn_url": "https://cdn.example.com/ads/winter-offer/v3/landscape.jpg",
  "version": "3",
  "valid_from": "2026-12-01T00:00:00-05:00",
  "valid_to": "2027-01-01T00:00:00-05:00"
}

Omit cdn_asset_id and cdn_url when the publisher has no separate CDN mapping. Save the returned native creative ID immediately. Creating this JSON record does not upload the image or complete publication.

Update creative metadata (if needed)

Use Update Creative with the saved creative ID. Omitted fields remain unchanged.

PATCH /member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives/{creativeId}
Authorization: {Koddi-provided authorization value}
Content-Type: application/json
{
  "name": "Winter offer landscape revised",
  "version": "4",
  "valid_from": "2026-12-15T00:00:00-05:00",
  "valid_to": "2027-01-01T00:00:00-05:00"
}

Apply the version and approval rules in Step 10. Keep a revised publication ineligible until the exact image and complete metadata have been verified; a metadata update alone does not complete it.

Upload the image file

Download the approved AEM rendition on the backend. Validate it, then call Upload Creative Image:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: ${KODDI_AUTHORIZATION}" \
  --header 'Content-Type: image/jpeg' \
  --data-binary @approved-rendition.jpg \
  "${KODDI_API_BASE}/member_groups/${KODDI_MEMBER_GROUP_ID}/advertisers/${KODDI_ADVERTISER_ID}/creatives/${KODDI_CREATIVE_ID}/image_upload"

Use image/png for PNG files. This endpoint takes raw file bytes. It is separate from the JSON creative call and is not an image retrieval URL.

Verify and approve

Call Get Creative using the endpoint table above. Verify advertiser ownership, asset metadata, version, validity, uploaded image, and the UI preview. Mark publication complete only after both the creative record and image upload have been verified.

When the integration is authorized to approve, call Creative Approval:

POST /member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives/{creativeId}/approval
Content-Type: application/json
{
  "approval_status": 2,
  "comment": "Approved AEM publication verified"
}

Approval values are 1 pending, 2 approved, and 3 denied. Otherwise, leave approval to the Koddi operator. Approval does not bypass the validity window.

Step 8: Return the image in Winning Ads

The publisher calls Winning Ads:

POST https://{clientname}.koddi.io/auction-engine/winning_ads

Koddi's response will include the following fields (as needed):

Response valuePurpose
ext_asset_idIdentify the original AEM asset and resolve local content
cdn_asset_idIdentify the image in the publisher’s CDN
cdn_urlRetrieve the image from the publisher’s CDN
versionSelect the exact approved asset version
valid_fromStart of permitted display, inclusive
valid_toEnd of permitted display, exclusive

Return publisher CDN fields when populated on the creative. Keep the Koddi-hosted image URL separate from cdn_url. The creative’s url remains the click-through destination.

Rendering behavior

Delivery environmentImage selection
Connected web or appRender the Koddi-hosted image or publisher CDN image according to the placement’s configured delivery policy
In-room/onboardResolve ext_asset_id, version, and rendition to the installed bundle image
Local image unavailableUse an eligible matching CDN image when connectivity and publisher policy allow; otherwise show publisher default content

All image locations must represent the same approved version.

Supplements for other AEM versions

All supplements use the same Koddi endpoints, mandatory image upload, field contract, publisher timezone rules, and in-room/onboard bundle workflow. Only the AEM interface, authentication, and job trigger change.

These are customer implementation plans. Validate the installed release, service pack, runtime, and Adobe support coverage before deployment. Cloud-hosted AEM or Adobe Managed Services is not automatically AEM as a Cloud Service.

AEM 6.5 LTS

AreaCustomer implementation
Author interfaceAdd advertiser selection, rendition, validity, and in-room/onboard controls to the supported author dialog or metadata interface
TriggerCustom Java OSGi workflow process step after advertising approval
Source accessDedicated AEM service identity for an internal module; authenticated deployment-supported asset access for an external worker
WorkerPersist the job, then run Koddi calls asynchronously outside the author request
SecretsWorker secret vault or protected backend configuration
StatusStore Koddi mapping and separate bundle/device outcomes in AEM integration fields or the job database

Compile the module against the installed LTS release and supported runtime. Use Adobe’s LTS workflow extension guidance.

Test cluster concurrency, restarts, folder permissions, rendition access, and credential rotation. Preserve source IDs and Koddi mappings during upgrades.

AEM 6.5

  1. Add the publishing controls to the existing author interface. Populate advertiser names through the backend Advertisers call.
  2. Add a deployment-compatible workflow step after approval. Submit an authenticated job containing the frozen source identity, advertiser, rendition, validity, and packaging flag.
  3. Acknowledge the job only after durable storage. Run Koddi calls in external middleware to keep remote transfers out of the approval request.
  4. Read approved metadata and renditions using the installation’s supported authentication and asset access method.
  5. Create the creative with its asset and validity fields, upload the approved image file, and verify the preview through the same Koddi endpoints. Build in-room/onboard bundles as separate jobs and write status back through the supported interface.

Use Adobe’s AEM 6.5 workflow extension guidance. Test on the actual service pack, JVM, proxy, and trust-store configuration. Keep mappings and the Koddi client independent of AEM so an upgrade replaces the source adapter without recreating creatives.

AEM 6.4 or earlier

Use maintained external middleware for Koddi API calls, credentials, mappings, and retries. Keep changes inside the older AEM installation small.

RequirementImplementation
Source handoffExisting publication export, compatible workflow hook, or explicit export action
Asset identityStable source ID and approved version that survive moves and renames
Advertiser routingBackend advertiser selector, controlled folder mapping, or authenticated middleware screen
Image uploadSecure export or retrieval of the approved image bytes for the mandatory Koddi upload
In-room/onboardExport the approved image bytes and manifest metadata for the separate bundle job
StatusExternal job dashboard, with AEM writeback only through a supported interface

Prove metadata extraction, rendition access, authenticated handoff, and HTTPS connectivity before automating. Use an approved internal bridge when the old runtime cannot securely connect to middleware; retain TLS validation.

AEM 6.4 and earlier are legacy releases outside Adobe’s published standard support periods. Confirm any contractual coverage using the Adobe support matrix. Validate each installation with an end-to-end pilot covering creative creation, image upload, preview verification, retries, validity, withdrawal, and local bundle expiry.


Did this page help you?