Responsive Vertical Video Player with Customizable Pause Ad Overlay

The Vertical Video Player is a lightweight, responsive 9:16 video experience built on the Zype Player. It includes support for a customizable pause-ad overlay that displays promotional artwork whenever playback is paused.

This guide walks through how to use, deploy, and customize the Vertical Video Player in your applications.

Important: To use vertical video playback, your content must be encoded using vertical (9:16) transcode presets in the Zype CMS. Vertical presets can be configured under Transcode Profiles in your account.

GitHub Source Repository

The full sample implementation for this player is available on GitHub:

Vertical Video Player Sample Repo
https://github.com/zype-samples/vertical-video-player

This Help Center article includes code snippets for clarity, but the full working files, including HTML, CSS, JavaScript, and configuration assets, are maintained in the repository above.

Features

• Responsive 9:16 Layout optimized for vertical/portrait content
• Dynamic Video ID Support using a configuration file or URL parameter
• Pause Ad Overlay that displays artwork when viewers pause playback
• Hide-Ad Control allowing users to dismiss the overlay during a pause session
• Smart Overlay Logic ensures overlays only appear after playback begins
• Modern, mobile-friendly layout with clean CSS and smooth transitions
• Pure HTML/CSS/JavaScript with no external frameworks required

Setup

1. Configure Your Video and API Key

In the repo, the config.js file defines your default video ID and API key:

const video_id = "your-default-video-id";
const api_key = "your-zype-api-key";

These values initialize the embedded Zype Player.

2. Add or Replace Pause-Ad Artwork

Swap out promo.png with your own asset, or update the src path in your HTML:

<img id="pause-ad" src="promo.png" alt="Paused" />

The overlay image appears automatically whenever the viewer pauses playback.

3. Deploy to Your Website or App

Host the contents of the repository on any web server or static hosting environment. The player requires:

• config.js to load before scripts.js
• All assets to be accessible over HTTP/HTTPS

Usage

Basic Usage

Open the vertical.html file from the repo to launch the player.
It loads the video specified in config.js.

Dynamic Video ID Override

You can override the ID using a URL parameter:

vertical.html?vid=YOUR_VIDEO_ID

Logic:

1. If a vid parameter exists, the player uses it.

2. If not, it falls back to the video_id defined in config.js.

Examples:

vertical.html
vertical.html?vid=68f7a8d6f93bd5efd2877a31
vertical.html?vid=

How It Works

Player Initialization

1. config.js loads first and defines configuration values.

2. scripts.js detects whether a vid URL parameter is present.

3. The player is initialized using either:

   • The URL parameter value, or

   • The default ID from config.js

Pause-Ad Overlay Logic

The overlay is intentionally never shown on initial page load.

It appears only when:

1. The viewer has pressed Play at least once

2. Playback is paused

Users may dismiss the overlay using the hide button. It reappears on the next pause event unless hidden again for that session.

Event Handling

The sample listens for Zype Player postMessage events:

if (event.data.event === "zype:play") {
  hideOverlay();
}

if (event.data.event === "zype:pause") {
  if (hasPlayedOnce) {
    showOverlay();
  }
}

Customization

Styling

All visual styles are contained in styles.css, including:

• Player container sizing
• Overlay positioning
• Hide-button design
• Responsive breakpoints

Pause-Ad Artwork

The overlay image is displayed:

• At ~90% of the player width
• At ~80% height (leaving room for player controls)
• Centered with a subtle drop shadow

Update dimensions in CSS as needed.

Hide Button

Positioned in the top-right corner above the overlay:

#hide-ad-btn {
  position: absolute;
  right: 10px;
  top: 10px;
}

Technical Details

Dependencies

• Zype Web Player (loaded via embed script)
• Vanilla JavaScript, HTML, and CSS only

Browser Support

All modern browsers that support postMessage.
Fully responsive for mobile and desktop.

Configuration Options

From config.js:

const video_id = "your-default-video-id";
const api_key  = "your-api-key";

URL Parameters

Product Placement & Timed Overlays (Advanced)

Future enhancements may support timed product placement using Zype Ad Timings.
By storing product metadata in ZObjects, you can define:

• Product relationships
• Time-based triggers
• Dynamic creative swaps

This enables highly targeted, time-coded overlays during specific moments in the video.

Troubleshooting

Player Is Not Loading

• Ensure config.js is included before scripts.js
• Verify video_id and api_key values are set
• Check browser console for JavaScript errors
• Confirm the video is published and accessible via Zype
• Confirm the API key has valid permissions

Pause-Ad Overlay Not Displaying

• Overlay will not display unless playback has started
• Confirm zype:pause events are being received
• Check console logs for event data

Pause-Ad Image Not Displaying

• Ensure the image file exists in your hosting path
• Confirm correct src path in HTML
• Verify CORS settings if hosting assets separately

License

This sample is provided as part of the Zype Player ecosystem. See the GitHub repository for license details.