API Integration Guide

Choose Your Integration Option

DS Templates supports two integration approaches. Select the one that best fits your platform.

Feature Comparison

Account Hierarchy SHARED

Every partner integration uses a three-tier account model. Only the outer two tiers hold OAuth credentials of their own.

integrator_admin        (one per partner, credentials issued by DST)
    │
    │  POST /api/v1/users/provision
    ▼
integrator_user         (one per partner customer - holds no credentials)
    │
    └─▶ admin subuser   (created by the same call - holds the credentials)
            │
            │  POST /api/v1/subusers
            ▼
        subuser         (end-user that owns saved templates)

Base URLs

All paths in this guide are relative to your integrator-specific white-label host. For a partner whose white-label host is templates.example.com:

Your white-label host is configured by DS Templates during onboarding: you point a CNAME record at our servers and we issue and renew the SSL certificate. Once registered, all API and embed routes resolve under that domain. To set up or change a white-label host, contact your DS Templates integration contact.

Authentication SHARED

All /api/v1/* endpoints are protected by OAuth 2.0 using the client_credentials grant. You exchange a client_id and client_secret for an access token, then attach that token to subsequent requests as a Bearer token.

Tokens are short-lived (one hour). Refresh tokens are not issued for the client_credentials grant - when an access token expires, request a new one with the same credentials.

Token Endpoint

POST /api/v1/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=<your_client_id>&
client_secret=<your_client_secret>

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "scope": "templates:read templates:write"
}

{
    "error": "invalid_client",
    "error_description": "Client authentication failed",
    "message": "Client authentication failed"
}

Available Scopes

The integrator_user account holds no credentials of its own: subusers:manage sits on the admin subuser created alongside it. Calling an endpoint with a token that lacks the required scope returns 403 Forbidden; no token, an expired token or an invalid token returns 401 Unauthorized.

Using a token

GET /api/v1/my-templates HTTP/1.1
Host: templates.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

For embedded routes under /embed/* (the template editor and module configuration iframes), you may also pass the token as a ?token=... query parameter on the iframe URL. The platform validates it on the first request and re-uses it for subsequent requests within that iframe.

Once you have an access token it is safe to pass it to a browser where needed (for example to load the editor iframe); because of the one-hour lifetime you typically fetch a fresh token per editor session. Cache tokens against the client_id.

Example: full token flow

# 1. Exchange credentials for an access token
ACCESS_TOKEN=$(curl -s -X POST https://templates.example.com/api/v1/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=01HRX...' \
  -d 'client_secret=s3cr3t...' \
  | jq -r .access_token)

# 2. Call an API endpoint with the token
curl -s https://templates.example.com/api/v1/my-templates \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq .

Provisioning SHARED

With your integrator_admin credentials (issued during onboarding) you provision one integrator_user per customer. The returned credentials are what your customer record stores, and what you later use to provision subusers under that customer.

{
    "email": "customer-42@partner-cms.example",
    "organisationId": "ORG-12345"
}

{
    "userId": "01HRX...",
    "email": "customer-42@partner-cms.example",
    "organisationId": "ORG-12345",
    "clientId": "f1c2d3e4...",
    "clientSecret": "9a8b7c6d...",
    "created": true
}

Rotate an account secret

{
    "userId": "01HRX...",
    "clientId": "f1c2d3e4...",
    "clientSecret": "5e4d3c2b..."
}

Subuser Management SHARED

A subuser is the account that ultimately edits templates and owns saved work. Each customer's admin subuser (returned by POST /users/provision) provisions one subuser per end-user in your CMS. All routes require a Bearer token from that admin subuser's credentials, with subusers:manage scope.

If the caller has the right scope but is not itself a provisioned subuser of an integrator_user (credentials generated outside the normal provisioning flow), endpoints return 403 with {"error": "Caller is not a provisioned subuser"}.

Create subuser

{
    "email": "alice@partner-cms.example",
    "firstName": "Alice",
    "lastName": "Andersson",
    "scopes": ["templates:read", "templates:write"],
    "permissions": {
        "templateEditor": {
            "elementPositioning": true,
            "elementAnimation": true,
            "elementColor": true,
            "elementColorPicker": true,
            "fontSize": true,
            "fontType": true,
            "fontColor": false,
            "fontStyling": false
        }
    }
}

{
    "userId": "01HRX...",
    "email": "alice@partner-cms.example",
    "firstName": "Alice",
    "lastName": "Andersson",
    "clientId": "abc123...",
    "clientSecret": "xyz789...",
    "scopes": ["templates:read", "templates:write"],
    "permissions": { "templateEditor": { /* ... */ } },
    "created": true
}

Access scopes

The scopes array decides whether the subuser can only view templates in the editor or also save changes. It is independent of the permissions.templateEditor UI toggles.

Only templates:read and templates:write are assignable; any other value is rejected with 400. A view-only subuser opens the same editor, but the controls are disabled and the save endpoint rejects writes server-side. This is the correct lever for a "reader" subuser: the templateEditor toggles only hide UI affordances and do not make a subuser read-only. Change scopes later with PATCH.

List subusers

{
    "subusers": [
        {
            "userId": "01HRX...",
            "email": "alice@partner-cms.example",
            "firstName": "Alice",
            "lastName": "Andersson",
            "clientId": "abc123...",
            "scopes": ["templates:read", "templates:write"],
            "permissions": { "templateEditor": { /* ... */ } }
        },
        {
            "userId": "01HSY...",
            "email": "bob@partner-cms.example",
            "firstName": "Bob",
            "lastName": "Brown",
            "clientId": "def456...",
            "scopes": ["templates:read"],
            "permissions": { "templateEditor": null }
        }
    ]
}

Get single subuser

Update subuser

{
    "firstName": "Alice",
    "lastName": "Andersson-Williams",
    "scopes": ["templates:read"],
    "permissions": {
        "templateEditor": {
            "fontColor": true
        }
    }
}

Rotate subuser secret

{
    "userId": "01HRX...",
    "email": "alice@partner-cms.example",
    ...
    "clientId": "abc123...",
    "clientSecret": "4f3e2d1c..."
}

Delete subuser

Editor Permissions

The permissions.templateEditor object controls which UI affordances are exposed inside the editor. For the standard toggles, true exposes the control and false hides it. Defaults are permissive: omit the object for full access, and any field you leave out keeps its exposed default.

These flags are pure UI gating inside the editor iframe and do not affect API access. Align your own partner-side UI with the flags you set. To make a subuser read-only, use scopes instead.

Template Library SHARED

Three endpoints power the template-picker and "My Templates" views. All require templates:read. The two catalogue endpoints (/templates, /template-categories) accept your integrator_admin token as well as a subuser token; /my-templates needs a subuser token.

[
    {
        "categoryName": "Information",
        "translations": {
            "nl_NL": "Informatie",
            "en_GB": "Information",
            "de_DE": "Informationen",
            "fr_FR": "Informations"
        },
        "items": [
            {
                "name": "Office welcome screen",
                "slug": "info_welcome_screen",
                "isRealtime": false,
                "dynamicDuration": false,
                "isPrivate": false,
                "imagePath": "https://common.digitalsignage-templates.com/template_previews/nl/info_welcome_screen.jpg",
                "thumbnailPath": "https://common.digitalsignage-templates.com/template_previews/nl/info_welcome_screen_converted.webp",
                "editorUrl": "https://templates.example.com/embed/template-editor/new/info_welcome_screen",
                "previewUrl": "https://templates.example.com/template/info_welcome_screen/preview",
                "modules": [
                    { "name": "Welcome module", "slug": "welcome-module" }
                ]
            }
        ]
    }
]

Custom templates

Templates built for one specific customer (in their house style) are returned in a separate category, Huisstijl templates. Each item carries a userIds array listing the main users (customers) it is linked to. A link to a main user covers all of its subusers, including subusers added later. A customer can deny a template to specific subusers; those are listed in excludedSubuserIds.

If you passed an organisationId when provisioning a customer, it is listed in organisationIds, so you can match a template to your own customer record without storing our userId. Pass it as well when you ask DS Templates for a custom template: it is how we find the customer when linking the template to their account.

The category is left out entirely when there are no custom templates for the token, and a template is not returned to the token of a subuser that is denied access to it.

{
    "categoryName": "Huisstijl templates",
    "translations": { /* ... */ },
    "items": [
        {
            "name": "Acme lobby screen",
            "slug": "acme_lobby_screen",
            /* ... */
            "isPrivate": true,
            "userIds": ["01HRX..."],
            "organisationIds": ["ORG-12345"],
            "excludedSubuserIds": []
        }
    ]
}

Template Categories

[
    {
        "name": "Information",
        "translations": {
            "nl_NL": "Informatie",
            "en_GB": "Information"
        }
    }
]

Saved Templates (My Templates)

[
    {
        "id": "01HRX...",
        "name": "Reception screen - Q2",
        "orientation": null,
        "aspectRatio": "16:9",
        "url": "https://templates.example.com/template/01HRX...",
        "createdAt": "2026-04-12T08:30:00+00:00",
        "modifiedAt": "2026-05-19T14:02:11+00:00",
        "thumbnailUrl": "https://...",
        "thumbnailCreatedAt": "2026-05-19T14:02:13+00:00",
        "videoUrl": null,
        "videoCreatedAt": null,
        "duration": 15,
        "modules": [
            { "name": "Welcome module", "slug": "welcome-module" }
        ],
        "latestVersionId": "01HSY...",
        "versions": [
            { "id": "01HRX...", "modifiedAt": "2026-04-12T08:30:00+00:00" },
            { "id": "01HSY...", "modifiedAt": "2026-05-19T14:02:11+00:00" }
        ]
    }
]

Template Versioning

DS Templates retains every saved version. The id at top level is the root (original); each save creates a new child in versions[]. latestVersionId is always the most recent.

• For rendering on screens: pass whichever version ID you want to display. Different screens can show different versions (e.g. a campaign's v3 in the lobby while v2 stays in meeting rooms).
• For editing: always pass latestVersionId. The editor clones the version you give it into a new child on save, so editing an older version creates a divergent branch.

Module Catalogue SHARED

Some templates embed modules: independent feature areas that need their own setup (a Bundeling connection, a SolarEdge API key, a list of calamities, a poll, …). Each module exposes a configuration UI as an iframe (see Module iframes). This endpoint returns the catalogue so your CMS can present them.

{
    "baseUrl": "https://templates.example.com/embed/modules/%s?token=%s",
    "categories": {
        "simple-credential": [
            {
                "name": "Bundeling",
                "link": "bundeling-module",
                "translations": { "nl_NL": "Bundeling module", "de_DE": "Bundeling-Modul" }
            },
            { "name": "Education", "link": "education-module", ... },
            { "name": "Humly", "link": "humly-module", ... },
            { "name": "Remote Device Management", "link": "mdm-module", ... },
            { "name": "Smart Event Manager", "link": "sem-module", ... },
            { "name": "SolarEdge", "link": "solar-edge-module", ... }
        ],
        "manual-entry": [
            // Birthday, Calamity, Events, Internal News, Meeting Room,
            // Menu Board, Poll, Presence, Welcome
        ],
        "oauth": [
            // Google, LinkedIn, Microsoft, TeamLeader
        ]
    }
}

const baseUrl    = response.baseUrl;                                  // from /api/v1/modules
const moduleLink = response.categories['simple-credential'][0].link; // "bundeling-module"
const token      = await getAccessToken();                             // subuser token

const iframeSrc = baseUrl.replace('%s', moduleLink).replace('%s', token);
// → "https://templates.example.com/embed/modules/bundeling-module?token=eyJ..."

{
    "fileName": "office-front.jpg",
    "title": "Office building, exterior",
    "source": "<integrator-key>"
}

{
    "fileName": "intro.mp4",
    "title": "Showroom intro reel",
    "source": "<integrator-key>",
    "duration": 30
}

{
    "logos": [
        { "filename": "primary-logo.png", "sortOrder": 0 },
        { "filename": "secondary-logo.png", "sortOrder": 1 }
    ],
    "colors": {
        "color1": "#0F4C81",
        "color2": "#F4C430",
        "color6": "#222222"
    }
}

{
    "logos": [
        { "sortOrder": 0, "filename": "primary-logo.png" },
        { "sortOrder": 1, "filename": "secondary-logo.png" }
    ],
    "colors": {
        "color1": "#0F4C81",
        "color2": "#F4C430",
        "color3": null,
        ...
        "color6": "#222222",
        ...
        "color20": null
    }
}

Editor Iframe SHARED

The template editor is a full editing UI hosted by the platform and embedded as an iframe in your CMS. Your CMS controls the surrounding chrome (save button, back link, status overlays) and exchanges postMessage events with the iframe to drive saves and read state.

# Create a new template from a catalogue entry ({slug} from /api/v1/templates)
https://templates.example.com/embed/template-editor/new/{slug}?token={access_token}

# Edit an existing template ({id} = latestVersionId from My Templates)
https://templates.example.com/embed/template-editor/edit/{id}?token={access_token}&source=<integrator-key>

<iframe
    id="template-editor"
    src="https://templates.example.com/embed/template-editor/edit/01HRX...?token=eyJ...&source=<integrator-key>&locale=nl_NL"
    style="width:100%;height:100vh;border:none"
    sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
></iframe>

The editor needs allow-scripts, allow-same-origin and allow-forms; allow-popups is required for media dialogs that open in a new window.

Save lifecycle

1. User clicks Save in your CMS chrome; your CMS posts DST_EDITOR_SAVE to the iframe.
2. Editor replies with DST_SAVE_STARTED: show a spinner.
3. Editor posts either DST_SAVE_COMPLETE (with the saved templateId and a media summary) or DST_SAVE_ERROR (with an error and, for validation failures, an errors list).

DST_SAVE_COMPLETE.media lists every external-media fileName the saved template references, split into images and videos. Use it to mark those files as "in use" in your CMS so they are not deleted from under the template.

{
    "templateId": "01HRY...",
    "message": "Template saved",
    "media": {
        "images": ["office-front.jpg", "team-photo.png"],
        "videos": ["intro.mp4"]
    }
}

Save errors

Module Iframes SHARED

Each module from the module catalogue exposes its own configuration UI as an iframe. Unlike the editor, module iframes do not use a postMessage protocol: they are server-rendered pages that the user interacts with directly.

https://templates.example.com/embed/modules/{link}?token=<subuser-token>

<iframe
    src="https://templates.example.com/embed/modules/birthday-module/?token=eyJ..."
    sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
></iframe>

{link} is a link value from GET /api/v1/modules. You set token once on the initial src; an embedded script forwards it on every in-iframe link, form submit and AJAX call, so your parent CMS does not need to participate. token must be a subuser access token. Each module additionally requires per-feature user permissions configured by DS Templates. A 401 inside the iframe means the token expired: reload the src with a fresh one.

Module categories

OAuth Module Setup SHARED

The oauth modules connect a template to a third-party service on the customer's behalf. Before the in-iframe "Connect" button works, someone has to register an OAuth application with the provider and wire its redirect URI and credentials to the platform. The runtime (popup handshake) needs nothing from your CMS.

In both models the redirect URI is registered in the provider's developer console and points at https://<platform-host>/embed/modules/<module-link>/authorize, where <platform-host> is the host from baseUrl in GET /api/v1/modules.

LinkedIn

1. In the LinkedIn Developer Portal, create (or reuse) an app for the customer's organisation.
2. On the Products tab, request the Pages Data Portability API product (grants r_dma_admin_pages_content). Approval can take time, so request it early.
3. Register the redirect URI https://<platform-host>/embed/modules/linkedin-module/authorize, including the clientId query parameter that LinkedIn's embed flow carries.
4. In the module iframe, the customer pastes the app's client id and secret and clicks connect.

LinkedIn DMA tokens have a server-side lifecycle of their own, so a healthy-looking connection can occasionally return a 401 and need a re-connect. This is expected LinkedIn behaviour.

Microsoft

Create one Entra app registration per service (permissions differ per service, and separate apps keep each customer's consent scoped):

Per app: account type multi-tenant; a Web redirect URI of exactly https://<platform-host>/embed/modules/microsoft-module/authorize (no query string, no trailing slash); a client secret; and the permissions above, all Delegated, never Application. Add only what is listed: Entra puts every consented permission into live tokens.

Google

Both clients can live in one Google Cloud project. Enable the Google Calendar API (Calendar) and the Google Analytics Data API and Admin API (Analytics). Configure the OAuth consent screen as External with the scopes above, then create one Web application client per integration with the redirect URI https://<platform-host>/embed/modules/google-module/authorize (no query string, no trailing slash). Each user holds one Google account per integration.

Registering your credentials

For Microsoft and Google you register credentials yourself. These routes need an integrator_admin token with oauth-apps:manage; a subuser token is rejected.

{
    "clientId": "55f919ac-1f4e-4d2e-9a77-0c3b1f9a7e21",
    "clientSecret": "your-entra-client-secret",
    "tenantId": "common"
}

{
    "target": "MS_SHAREPOINT",
    "configured": true,
    "clientId": "55f919ac-1f4e-4d2e-9a77-0c3b1f9a7e21",
    "clientSecret": "********f3a9",
    "tenantId": "common",
    "createdAt": "2026-09-22T11:04:19+00:00",
    "updatedAt": null
}

PostMessage Reference

Every window.postMessage event exchanged between your parent CMS and the platform's iframes. The editor and playback protocols live in different iframes; media resolution runs alongside either. Module iframes use no postMessage protocol.

Origin validation: the platform's iframes check event.origin against trusted origins before processing incoming messages, except DST_RENDERER_MEDIA_URL_RESPONSE, which is accepted from any origin. Your CMS should likewise validate the iframe's origin against the URL it loaded. The platform posts to the event.origin of the most recent incoming message, or '*' before any message has been received.

Editor Protocol

Events for the editor iframe at /embed/template-editor/...

Editor to Parent

The editor also emits three notification events that need no reply; ignore them unless you want to react:

Parent to Editor

Event listener example

const ORIGIN = 'https://templates.example.com';
const editor = document.getElementById('template-editor');

window.addEventListener('message', (event) => {
    if (event.origin !== ORIGIN) return;

    switch (event.data.type || event.data.msg) {
        case 'DST_EDITOR_READY':
            console.log('Editor ready');
            break;

        case 'DST_SAVE_COMPLETE':
            console.log('Saved:', event.data.templateId);
            refreshUserTemplates();
            break;

        case 'DST_SAVE_ERROR':
            console.error('Save failed:', event.data.error);
            break;
    }
});

// Trigger save from your CMS UI
function triggerSave() {
    editor.contentWindow.postMessage(
        { type: 'DST_EDITOR_SAVE' }, ORIGIN
    );
}

Playback Protocol

For templates in playback mode via /template/{slug}/preview?playlist=true. Without ?playlist=true the template auto-plays standalone.

Template to Parent

All events are sent as window.parent.postMessage({ msg, … }, '*'). startTime and stopTime are ms epoch; playDuration is in ms.

Parent to Template (raw strings)

Minimum playback flow

parent: load <iframe src="/template/{slug}/preview?playlist=true" />
iframe -> parent: { msg: "DST_TEMPLATE_LAZY_LOAD" }
iframe -> parent: { msg: "preRenderFinished" }
iframe -> parent: { msg: "DST_TEMPLATE_DURATION", duration: 30 }
parent -> iframe: "initIntroAnimation"
iframe -> parent: { msg: "DST_TEMPLATE_PLAY", startTime: 173... }
... template plays ...
parent -> iframe: "exitIntroAnimation"
iframe -> parent: { msg: "DST_TEMPLATE_STOP", playDuration: 30000 }
parent: tear down or swap iframe

The DST_TEMPLATE_DURATION step only happens for dynamic-duration templates. If the parent never sends 'initIntroAnimation', the template never starts playing and emits no DST_TEMPLATE_* events (intros, ticking content and videos don't run). If it never sends 'exitIntroAnimation', the template plays indefinitely; there is no platform-side timeout.

iframe -> parent: { type: "DST_RENDERER_MEDIA_URL_REQUEST",
                   fileNameWithExtension: "office.jpg" }
parent -> iframe: { type: "DST_RENDERER_MEDIA_URL_RESPONSE",
                   fileNameWithExtension: "office.jpg",
                   mediaUrl: "https://your-cdn.example/uploads/office.jpg" }
iframe: updates all img.src, video.src, and inline-style references

Error Handling SHARED

Every JSON endpoint uses the same error shape: { "error": "Human-readable description" }. The HTTP status carries the semantics.

Common error messages

These are the canonical error strings the API returns. Treat the HTTP status as the source of truth.

Authentication and authorisation

Provisioning (POST /users/provision)

Subuser management

For the /api/v1/integrator/oauth-apps errors, see OAuth module setup.

Library and branding

Template editor save

The editor save endpoint wraps errors in a success envelope:

{
    "success": false,
    "error": "Validation failed",
    "errors": [
        "The first headline must not be empty.",
        "Brand color 1 must be a valid hex code."
    ]
}

The embedded editor always saves via XHR, so you always get the JSON envelope with a 400 on validation errors; check success. The editor's DST_SAVE_ERROR postMessage passes the errors array through verbatim - render it as a list under your save button.

Rendering (GET /template/{id})

Validation error shapes

Two slightly different shapes depending on context:

JSON-API endpoints (/api/v1/...) - a single error string:

{ "error": "email is required" }

Editor-iframe save (/embed/template-editor/...) - JSON wrapped in success envelope (see above).

What to retry vs. surface

Rendering Templates SHARED

Once a subuser has saved a template, embed it on a digital signage screen by loading the rendering URL in an iframe and driving its playback lifecycle via postMessage.

Required: integrator host

Saved templates created via the partner API may only be rendered from a host the platform recognises as one of your integrator domains. You are issued a production and a staging host at onboarding:

<integrator-key> is the same identifier you pass as source to the editor. A request from any other host (including templates.example.com itself) returns 400: "API templates must be served from a recognized integrator domain."

Required: trackingId

Every render request must carry a ?trackingId= query parameter, or it returns 400: "trackingId is required for this template." It is a stable identifier for the device displaying the template (e.g. screen serial number, device UUID), used for hourly usage counting and deduplication. You do not need to register it ahead of time.

• One trackingId per screen, not per render - reusing is correct and expected
• Do not generate a fresh ID per render - that inflates counters
• Do not derive from end-user PII

Recommended: ?playlist=true

Without ?playlist=true, the template auto-plays on window.load: no preRenderFinished, no way to start or stop it, no DST_TEMPLATE_* events. Useful for thumbnails, not for screens. With it, the template enters parent-driven mode: pre-renders, emits preRenderFinished, then waits for 'initIntroAnimation'. See the Playback Protocol.

Optional query parameters

The preview URL accepts locale, aspectRatio and playlist too (use ?playlist=true for animated in-CMS thumbnails). Preview HTML is cached per (slug, locale); saved-template rendering is not cached, so to pick up changed data (a new calamity, new brand colours) simply reload the iframe.

<iframe
    src="https://<integrator-key>.ds-templates.com/template/01HRY...?trackingId=screen-A4F2&playlist=true&locale=nl_NL"
    sandbox="allow-scripts allow-same-origin"
    allow="autoplay"
></iframe>

allow="autoplay" is needed for any template that contains video, otherwise the browser blocks playback until user interaction. No cookie or token is needed on the render path.

Parent-side render loop

const RENDER_HOST = 'https://<integrator-key>.ds-templates.com';

function renderSlide({ templateId, durationFallbackMs }) {
  return new Promise((resolve) => {
    const iframe = document.createElement('iframe');
    iframe.src = `${RENDER_HOST}/template/${templateId}` +
                 `?trackingId=${screenId}&playlist=true&locale=${locale}`;
    iframe.sandbox = 'allow-scripts allow-same-origin';
    iframe.allow = 'autoplay';

    let templateDurationMs = null;
    let stopTimer = null;
    const stop = () => iframe.contentWindow.postMessage('exitIntroAnimation', '*');

    const onMessage = (event) => {
      // Option 1: answer media resolution requests from the same iframe
      if (event.data?.type === 'DST_RENDERER_MEDIA_URL_REQUEST') {
        iframe.contentWindow.postMessage({
          type: 'DST_RENDERER_MEDIA_URL_RESPONSE',
          fileNameWithExtension: event.data.fileNameWithExtension,
          mediaUrl: resolveMediaUrl(event.data.fileNameWithExtension),
        }, '*');
        return;
      }
      switch (event.data?.msg) {
        case 'preRenderFinished':
          iframe.contentWindow.postMessage('initIntroAnimation', '*');
          stopTimer = setTimeout(stop, templateDurationMs ?? durationFallbackMs);
          break;
        case 'DST_TEMPLATE_DURATION':
          // Dynamic-duration template told us how long it expects to play
          templateDurationMs = event.data.duration * 1000;
          if (stopTimer) { clearTimeout(stopTimer); stopTimer = setTimeout(stop, templateDurationMs); }
          break;
        case 'DST_TEMPLATE_STOP':
          window.removeEventListener('message', onMessage);
          if (stopTimer) clearTimeout(stopTimer);
          resolve();
          break;
      }
    };

    window.addEventListener('message', onMessage); // before the iframe loads
    document.body.appendChild(iframe);
  });
}

• Prefer DST_TEMPLATE_DURATION when it fires, but always keep a fallback timer: static-duration templates never emit it. The dynamicDuration flag on /api/v1/templates tells you up front which kind a template is.
• Wait for DST_TEMPLATE_STOP before tearing down the iframe, so the template can clean up.
• Install the media-resolution handler before the iframe loads. The first request is sent during pre-render; a late listener misses it and the placeholder never resolves.

Conventions SHARED