JavaScript Events and Player Config
MediaShield overviewFree + ProGet MediaShield →
Included in Free - Pro scripts listen to the same events.
The front-end player is plain JavaScript with no build step (assets/js/). It talks to add-ons through browser events and one config object.
Events
Section titled “Events”Events are CustomEvents. Unless noted they are dispatched on window.
window.addEventListener( 'mediashield:player-ready', function ( e ) { console.log( e.detail.videoId, e.detail.token );} );| Event | Target | Detail | When |
|---|---|---|---|
mediashield:player-ready |
window |
el, videoId, token, resumePosition, watermarkConfig, video, adapter |
A watch session has started and the player is wired up. The watermark, tracker, protection and ad scripts all key off it. |
mediashield:player-ready |
window |
el, videoId (0), adapter |
Fired without a session when the player has no video ID (nothing to track). Check token before using it. |
mediashield:access-denied |
window, cancelable |
el, videoId, reason |
POST /session/start was refused. Call event.preventDefault() to suppress the built-in overlay and draw your own. |
mediashield:concurrent-limit |
window |
el, videoId, message |
Session start was refused because the viewer is at the stream limit. |
mediashield:devtools-detected |
window |
strategy (debugger_timing; size_delta before 1.4.2) |
Developer tools were detected, before the beacon is sent. |
mediashield:ended |
the player element, bubbles | none | Playback reached the end. The playlist uses it to advance. |
mediashield:player-destroy |
window |
el |
A player element is being replaced (the playlist does this when it swaps in the next video). The tracker ends the session and the wrapper cleans up. |
mediashield:watermark-preview |
window (admin Settings screen) |
{ text, caption }, or null |
Since 1.4.2. Sets the words in the Watermark preview on MediaShield > Settings; null puts back the default name and IP. Pro sends it from its Watermark Fields. |
There is no mediashield:playlist-switch event. To react to a playlist moving on, listen for mediashield:player-destroy followed by the next mediashield:player-ready.
window.mediashieldConfig
Section titled “window.mediashieldConfig”Localized onto the player script by Settings::frontend_config() and filterable with mediashield_frontend_config.
| Key | Value |
|---|---|
restUrl |
mediashield/v1/ base URL. |
nonce |
wp_rest nonce. |
isLoggedIn, userId, loginUrl |
Current viewer and the login link for the overlay. |
requireLogin |
The ms_require_login setting. |
interval |
Heartbeat interval in milliseconds (30000). |
player |
speedControl, preventForwardSeek, keyboard, resume, sticky, endscreen, endscreenText, endscreenUrl, from the matching ms_player_* settings. A video’s own overrides are merged per player. |
messages |
Every viewer-facing string (login overlay, access denied, load failed, concurrent limit, resume prompt, ad labels and so on). Owner-edited messages are passed through untouched; defaults are translated. |
Protection settings travel separately, through mediashield_protection_config.
window.mediashieldRequest
Section titled “window.mediashieldRequest”A shared reader for failed requests, used by every MediaShield screen and the player since 1.4.2.
mediashieldRequest.readJSON( response )reads afetch()response as JSON and rejects with a plain error when the body is an error page (such as a 502) instead of JSON.mediashieldRequest.message( error, fallback )returns one plain sentence for the person: the network sentence when the server could not be reached or did not answer properly, otherwise the server’s own message, otherwisefallback.
Use it in add-on screens so a dropped connection never shows “Failed to fetch” or a JSON parser error.
Admin SPA filter
Section titled “Admin SPA filter”The admin app is a React app with hash routing. Add pages with the JavaScript filter mediashield_admin_routes (wp.hooks, not PHP). Route objects use hash, label, icon, component; see Extension Architecture.
Block editor slot
Section titled “Block editor slot”The MediaShield Video block renders one Slot named mediashield-video-access-controls in its inspector. Nothing in Free or the current Pro fills it yet, so it is available to add-ons.

