Events API (postMessage)

When a VCMS component is embedded via iframe into your platform, the component can forward user interactions (clicking "More", clicking a video) to the parent page using the browser-native window.postMessage, letting your platform decide how to handle them.

Cross-origin safe: an iframe and its parent can communicate even on different origins — this is the standard use of postMessage.

---

Two modes

Enable by adding the events parameter to the embed URL:

Mode	URL param	Behavior
Emit only	?events=1	The component does not navigate; it only emits events to the parent. Your platform handles them (open a player in a new window, use your own router, show a modal, etc.).
Navigate + emit	?events=nav	The component navigates to the portal itself (full page) and emits the event to you (for analytics).
Disabled	(no events)	Default: the component navigates itself with target="_top" and emits nothing.

events=nav waits about 120ms after emitting before navigating, so your listener (e.g. analytics) runs first.

Embed examples

<!-- Emit only: your platform fully controls the interaction -->
<iframe src="https://vcms-qa.acorners.com/strip?platform=1&events=1"
        width="100%" height="300" frameborder="0" scrolling="no"></iframe>

<!-- Navigate + emit: the component navigates to the portal itself; you only track -->
<iframe src="https://vcms-qa.acorners.com/strip?platform=1&events=nav"
        width="100%" height="300" frameborder="0" scrolling="no"></iframe>

The events parameter works on both the strip /strip and the full page /embed.

---

Message format

Every event is an object sent via window.parent.postMessage(payload, '*'). All events carry source: 'vcms' — use it to filter so you don't confuse them with other message events on the page.

interface VcmsEvent {
  source: 'vcms';
  type: 'video:click' | 'more:click';
  // remaining fields depend on type, see tables below
  [key: string]: unknown;
}

---

Event list

video:click — the user clicked a video

Field	Type	Notes
source	'vcms'	Fixed value
type	'video:click'	Event type
videoId	string	Video ID
title	string	Video title
watchUrl	string	Full URL of that video's player page (autoplays when opened)

{
  "source": "vcms",
  "type": "video:click",
  "videoId": "dcfc79f8-5650-4f6f-9416-3161e33f7af6",
  "title": "APB Brand Trailer",
  "watchUrl": "https://vcms-qa.acorners.com/watch/dcfc79f8-5650-4f6f-9416-3161e33f7af6"
}

more:click — the user clicked "More"

Field	Type	Notes
source	'vcms'	Fixed value
type	'more:click'	Event type
url	string	Full URL of the video center "All" page

{
  "source": "vcms",
  "type": "more:click",
  "url": "https://vcms-qa.acorners.com/"
}

---

Integration (listening on the parent page)

On the page that embeds the iframe, add a message listener and switch on type:

<script>
  window.addEventListener('message', (e) => {
    // 1) Only accept VCMS events
    if (!e.data || e.data.source !== 'vcms') return;

    // 2) (Recommended) verify the origin for extra safety
    // if (e.origin !== 'https://vcms-qa.acorners.com') return;

    switch (e.data.type) {
      case 'video:click':
        // e.g. open the player in a new window
        window.open(e.data.watchUrl, '_blank');
        // or: record analytics
        // track('video_click', { id: e.data.videoId, title: e.data.title });
        break;

      case 'more:click':
        // e.g. navigate to the video center
        location.href = e.data.url;
        break;
    }
  });
</script>

Which mode should I use?

• Want to control what happens after a click yourself (open a new window, route inside your SPA, show a confirm dialog first) → use events=1 and handle watchUrl / url in your listener.
• Just want to record what the user clicked and let the component navigate → use events=nav; your listener only tracks, the component navigates itself.

---

Security & notes

• Filter on source: always check e.data.source === 'vcms' first — the page may have other postMessage traffic.
• Verify e.origin (recommended): in production, add a check like e.origin === 'your VCMS portal domain' to prevent spoofing.
• Hotlink protection: your domain must be on the allowed-referrer whitelist (contact us to enable it), otherwise videos/thumbnails return 403.
• Autoplay: watchUrl attempts to autoplay when opened; the browser's autoplay policy may require muting or a prior user interaction — this is a browser-level constraint.
• targetOrigin: the component sends with '*', so the receiver must validate e.data.source (and optionally e.origin).

---

Live demo

The "Teaching" page in the VCMS admin has a live simulation at the bottom under "Event integration": it embeds an events=1 component, and clicking "More" or a video shows the received event JSON in real time on the right — along with copy-paste embed code and listener code.