Player Event Framework

This document explains how Zype’s Player Event Framework enables web applications to listen for and respond to key player events generated by the Zype Player powered by Bitmovin.

Topics covered include:

• • What is a player event

  • Technologies used to dispatch player events

  • Event types supported

  • Player event structure and examples

  • Adding custom metadata to dispatched events

  • Dispatching logic and window targeting

  • How to listen for player events

What is a Player Event?

A player event is a structured message containing information about the current state or action of the video player.

For example:

• When a viewer presses play, a zype:play event is dispatched.

• When playback ends, a zype:complete event is dispatched.

These events can be listened for by applications to trigger analytics, UI changes, or any custom business logic.

Behind the Scenes: Technologies Used to Dispatch Player Events

CreateEvent (Legacy JavaScript Events)

In early implementations, Zype used the standard JavaScript event model (createEvent) to dispatch messages directly to the DOM. This approach worked only for JavaScript embeds and lacked cross-origin compatibility.

PostMessage (Current Implementation)

The Zype Player now uses the PostMessage API to broadcast events in a secure, cross-origin manner that works consistently across JavaScript and iFrame embeds.

Reference: MDN PostMessage Documentation

PostMessage enables the player to send events safely from the embedded player context to the parent window or same-page environment, depending on the embed type.

Browser Support: Fully supported across all modern browsers.

Browser Support for PostMessage

PostMessage has full support for modern browsers (graphic provided by MDN):

Supported Event Types

The following event types are currently supported by the Zype Player Event Framework:

Note: All Zype events are prefixed with zype: to differentiate them from other messages that may appear on your page (e.g., YouTube or Vimeo events).

Event Structure

Event data is sent as a string for compatibility across browsers. Use JSON.parse() to convert the message back to a JSON object.

Example:

{
"event": "zype:pause",
"id": "57ed77530983884e57000041",
"info": {
"playlist_id": "564f70754272692607270000"
}
}

Fields:

• event — The name of the event (zype:ready, zype:play, etc.)

• id — The ID of the video generating the event

• info — Optional object for custom metadata (e.g., playlist, app, or page context)

Adding Custom Metadata to Dispatched Events

You can attach custom metadata to player events using the info query parameter in the embed URL.

Example:

Output:

{
"event": "zype:play",
"id": "57ed77530983884e57000041",
"info": {
"page": "home"
}
}

This allows you to tie events to your own contextual data such as the page name, user session, or campaign ID.

Event Dispatching

Events are dispatched directly from the Zype Player powered by Bitmovin whenever a corresponding player event is triggered.

Internally, Zype maps Bitmovin player state changes to Zype event messages, for example:

player.on(bitmovin.player.PlayerEvent.Play, function() {
  eventManager.dispatch('zype:play');
});

player.on(bitmovin.player.PlayerEvent.Paused, function() {
  eventManager.dispatch('zype:pause');
});

player.on(bitmovin.player.PlayerEvent.Error, function() {
  eventManager.dispatch('zype:error');
});

player.on(bitmovin.player.PlayerEvent.SourceLoaded, function() {
  eventManager.dispatch('zype:ready');
});

player.on(bitmovin.player.PlayerEvent.PlaybackFinished, function() {
  eventManager.dispatch('zype:complete');
});

EventManager and Window Targeting

The Zype Player Event Framework manages event delivery using an internal EventManager, which determines how and where to send events depending on the embed type.

• iFrame Embeds:
  Events are sent from the iframe to the parent window using window.parent.postMessage().

• JavaScript Embeds:
  Events are sent to the current window context using window.postMessage().

How to Listen for Player Events

To listen for player events on your page, use the standard window.addEventListener method and filter for Zype event messages.

Example:

<script>
  window.addEventListener('message', receiveMessage, false);

  function receiveMessage(message) {
    if (message.origin.match(/zype\.com/)) {
      const data = JSON.parse(message.data);

      switch (data.event) {
        case 'zype:ready':
          // handle player ready
          break;
        case 'zype:play':
          // handle video play
          break;
        case 'zype:pause':
          // handle video pause
          break;
        case 'zype:error':
          // handle error
          break;
        case 'zype:complete':
          // handle playback complete
          break;
        case 'zype:adstart':
          // handle ad start
          break;
        case 'zype:adcomplete':
          // handle ad complete
          break;
      }
    }
  }
</script>

Event Origin

• For iFrame Embeds: The origin will be https://player.zype.com

• For JavaScript Embeds: The origin will match your current page domain

Always validate the message origin to ensure it’s coming from a trusted Zype player instance.

Summary

The Player Event Framework provides a consistent and secure way to interact with the Zype Player powered by Bitmovin, enabling custom analytics, automation, and UI behavior across embeds.

For additional details, refer to:

• Zype Web Player Migration Guide

• Bitmovin Player Events Reference