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/v1Store the following in trusted backend configuration, separately for test and production:
| Setting | Purpose |
|---|---|
| API base URL | Koddi management API environment |
| Member group ID | Scope for advertiser and creative calls |
| Koddi API credential | Advertiser lookup, creative reads/writes, and image upload |
| Publisher timezone | For asset validity timeframes |
| Allowed asset folders | AEM content the integration can read |
| Advertiser access rules | Advertisers 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 identity | Access required |
|---|---|
| Koddi | No AEM account or inbound AEM access for this push integration |
| Publisher backend | Read approved AEM metadata; read approved image bytes for upload and in-room/onboard packaging |
| Backend status writer | Write integration-owned mapping/status fields in AEM or the integration database |
| Koddi integration API account | Read advertisers; create, read, and update creatives; upload images; write asset and validity fields |
| Publisher distribution service | Read approved image files, build bundles, and distribute them to target devices |
Step 2: Connect the AEM backend
For AEM as a Cloud Service:
- Create an Adobe App Builder project and separate test and production workspaces.
- Configure the selected AEM Assets API with OAuth Server-to-Server credentials and the appropriate product profile.
- Authorize the technical identity for the advertising asset folders.
- Verify metadata retrieval and, where needed, downloading the approved rendition.
- 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:
| Control | Behavior |
|---|---|
| Advertiser | Search Koddi names; save the native advertiser ID |
| Destination URL | Click-through URL |
| Rendition | Approved image size and format for the placement |
| Asset metadata | Source asset ID and any publisher CDN ID or URL |
| Version | Immutable approved publication version |
| Valid from / valid to | Display window entered in the publisher's timezone |
| Package for in-room/onboard | Enqueue a separate publisher content bundle job |
| Publish / retry | Start or resume a durable publishing job |
| Status | Show 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
| Source | Koddi field |
|---|---|
| Selected advertiser | advertiserId in the URL path |
| Connection member group | memberGroupId in the URL path |
| Asset title | name |
| Image classification | media_type |
| Click destination | url |
| Ad copy | text, or "" when not applicable |
Asset and validity fields
Include these fields in the creative Create and Update requests and return them in Get Creative.
| Field | Type | Meaning |
|---|---|---|
ext_asset_id | String, optional | Stable external source identity, normally the immutable AEM asset ID |
cdn_asset_id | String, optional | Publisher CDN identifier |
cdn_url | String, optional | Publisher-hosted image URL for traceability or configured connected fallback |
version | String, optional | Immutable approved publication version for the rendition |
valid_from | ISO 8601 timestamp, optional | Start of permitted display, inclusive |
valid_to | ISO 8601 timestamp, optional | End 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.
| Action | Method | Endpoint |
|---|---|---|
| Create | POST | /member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives |
| Upload file | POST | /member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives/{creativeId}/image_upload |
| Read and verify | GET | /member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives/{creativeId} |
| Update | PATCH | /member_groups/{memberGroupId}/advertisers/{advertiserId}/creatives/{creativeId} |
| Approve, when authorized | POST | /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_adsKoddi's response will include the following fields (as needed):
| Response value | Purpose |
|---|---|
ext_asset_id | Identify the original AEM asset and resolve local content |
cdn_asset_id | Identify the image in the publisher’s CDN |
cdn_url | Retrieve the image from the publisher’s CDN |
version | Select the exact approved asset version |
valid_from | Start of permitted display, inclusive |
valid_to | End 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 environment | Image selection |
|---|---|
| Connected web or app | Render the Koddi-hosted image or publisher CDN image according to the placement’s configured delivery policy |
| In-room/onboard | Resolve ext_asset_id, version, and rendition to the installed bundle image |
| Local image unavailable | Use 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
| Area | Customer implementation |
|---|---|
| Author interface | Add advertiser selection, rendition, validity, and in-room/onboard controls to the supported author dialog or metadata interface |
| Trigger | Custom Java OSGi workflow process step after advertising approval |
| Source access | Dedicated AEM service identity for an internal module; authenticated deployment-supported asset access for an external worker |
| Worker | Persist the job, then run Koddi calls asynchronously outside the author request |
| Secrets | Worker secret vault or protected backend configuration |
| Status | Store 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
- Add the publishing controls to the existing author interface. Populate advertiser names through the backend Advertisers call.
- Add a deployment-compatible workflow step after approval. Submit an authenticated job containing the frozen source identity, advertiser, rendition, validity, and packaging flag.
- Acknowledge the job only after durable storage. Run Koddi calls in external middleware to keep remote transfers out of the approval request.
- Read approved metadata and renditions using the installation’s supported authentication and asset access method.
- 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.
| Requirement | Implementation |
|---|---|
| Source handoff | Existing publication export, compatible workflow hook, or explicit export action |
| Asset identity | Stable source ID and approved version that survive moves and renames |
| Advertiser routing | Backend advertiser selector, controlled folder mapping, or authenticated middleware screen |
| Image upload | Secure export or retrieval of the approved image bytes for the mandatory Koddi upload |
| In-room/onboard | Export the approved image bytes and manifest metadata for the separate bundle job |
| Status | External 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.
Updated about 5 hours ago

