@zezosoft/react-player 1.0.2 → 1.0.4

package/README.md

@@ -10,7 +10,7 @@ A React video player by Zezosoft supporting HLS, MP4, DASH, preview thumbnails,
 - 💬 **Subtitles** — WebVTT with customizable styling
 - ⏭️ **Intro skip** — Skip intro button with configurable time range
 - 📺 **Episodes** — Next episode auto-play and playlist
-- 📢 **Ads** — Pre-roll, mid-roll, post-roll video ads
+- 📢 **Ads** — Pre-roll, mid-roll, post-roll (custom MP4 + Google IMA)
 - 📚 **Watch history** — Resume playback, progress tracking
 
 ## 📦 Installation
@@ -105,8 +105,16 @@ The player accepts four props: `video` (required), `style`, `events`, and `featu
 
 ### Ads (`AdConfig`)
 
+Custom MP4 ads and **Google IMA** (VAST/VMAP) can be used together. See **[docs/IMA_INTEGRATION.md](./docs/IMA_INTEGRATION.md)** for IMA setup, sample tags, and hybrid usage.
+
 ```typescript
 {
+  ima?: {
+    adTagUrl: string;
+    preRoll?: boolean;
+    postRoll?: boolean;
+    midRollCuePoints?: number[];
+  };
   preRoll?: AdBreak;
   midRoll?: AdBreak[];
   postRoll?: AdBreak;

package/dist/VideoPlayer/components/AdOverlayChrome.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+import { IPlayerConfig } from "../../types";
+interface AdOverlayChromeProps {
+    config?: IPlayerConfig;
+    showControls: boolean;
+    progressPercent: number;
+    skipable?: boolean;
+    canSkipAd?: boolean;
+    skipCountdown?: number;
+    onSkip?: () => void;
+    sponsoredUrl?: string;
+    fadeClassName?: string;
+}
+declare const AdOverlayChrome: React.FC<AdOverlayChromeProps>;
+export default AdOverlayChrome;

package/dist/VideoPlayer/components/ImaAdOverlay.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+import { AdBreak } from "../types/AdTypes";
+import { IPlayerConfig } from "../../types";
+interface ImaAdOverlayProps {
+    adBreak: AdBreak;
+    config?: IPlayerConfig;
+}
+declare const ImaAdOverlay: React.FC<ImaAdOverlayProps>;
+export default ImaAdOverlay;

package/dist/VideoPlayer/hooks/index.d.ts

@@ -6,5 +6,6 @@ export { useIntroSkip } from "./useIntroSkip";
 export { useEpisodes } from "./useEpisodes";
 export { useVideoEvents } from "./useVideoEvents";
 export { useAdManager } from "./useAdManager";
+export { useImaAds } from "./useImaAds";
 export { usePrimaryVideoLifecycle } from "./usePrimaryVideoLifecycle";
 export { useVideoError } from "./useVideoError";

package/dist/VideoPlayer/hooks/useAdManager.d.ts

@@ -1,8 +1,8 @@
-import { AdConfig, AdBreak, AdType } from "../types/AdTypes";
+import { AdConfig, AdBreak } from "../types/AdTypes";
 export declare const useAdManager: (adConfig?: AdConfig) => {
     isAdPlaying: boolean;
     currentAd: AdBreak | null;
-    adType: AdType | null;
+    adType: import("../..").AdType | null;
     skipAd: () => void;
     endAd: () => void;
 };

package/dist/VideoPlayer/hooks/useImaAds.d.ts

@@ -0,0 +1,8 @@
+import { AdConfig } from "../types/AdTypes";
+export declare const useImaAds: (adConfig?: AdConfig) => {
+    hasIma: boolean;
+    hasImaPreRoll: boolean;
+    imaPreRollNeedsGesture: boolean;
+    initializeIma: () => boolean;
+    startImaPreRoll: () => void;
+};

package/dist/VideoPlayer/hooks/useOverlayAutoHide.d.ts

@@ -0,0 +1,6 @@
+export declare const useOverlayAutoHide: () => {
+    showControls: boolean;
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    onMouseMove: () => void;
+};

package/dist/VideoPlayer/hooks/usePrimaryVideoLifecycle.d.ts

@@ -1,6 +1,7 @@
 import { VideoState } from "../../store/types/StoreTypes";
 interface UsePrimaryVideoLifecycleParams {
     hasPreRoll: boolean;
+    hasImaPreRoll?: boolean;
     trackSrc: string;
 }
 interface PrimaryVideoLifecycleResult {
@@ -13,5 +14,5 @@ interface PrimaryVideoLifecycleResult {
     shouldCoverMainVideo: boolean;
     shouldShowPlaceholder: boolean;
 }
-export declare const usePrimaryVideoLifecycle: ({ hasPreRoll, trackSrc, }: UsePrimaryVideoLifecycleParams) => PrimaryVideoLifecycleResult;
+export declare const usePrimaryVideoLifecycle: ({ hasPreRoll, hasImaPreRoll, trackSrc, }: UsePrimaryVideoLifecycleParams) => PrimaryVideoLifecycleResult;
 export {};

package/dist/VideoPlayer/ima/buildAdTagUrl.d.ts

@@ -0,0 +1,2 @@
+/** Appends a fresh correlator so each ad request is unique (required by many GAM tags). */
+export declare const buildAdTagUrl: (adTagUrl: string) => string;

package/dist/VideoPlayer/ima/createImaAdBreak.d.ts

@@ -0,0 +1,5 @@
+import { AdBreak, AdType } from "../types/AdTypes";
+/**
+ * Synthetic ad break used for IMA callbacks and UI state (no direct MP4 URL).
+ */
+export declare const createImaAdBreak: (type: AdType, id?: string) => AdBreak;

package/dist/VideoPlayer/ima/createImaRenderingSettings.d.ts

@@ -0,0 +1 @@
+export declare const createImaRenderingSettings: () => google.ima.AdsRenderingSettings;

package/dist/VideoPlayer/ima/getImaSlotDimensions.d.ts

@@ -0,0 +1,4 @@
+export declare const getImaSlotDimensions: (video: HTMLVideoElement, wrapper: HTMLDivElement | null) => {
+    width: number;
+    height: number;
+};

package/dist/VideoPlayer/ima/isVmapAdTag.d.ts

@@ -0,0 +1,3 @@
+import { ImaConfig } from "../types/AdTypes";
+/** Detect VMAP / ad-rule tags that require a single persistent IMA session. */
+export declare const isVmapAdTag: (adTagUrl: string, imaConfig?: Pick<ImaConfig, "adTagFormat">) => boolean;

package/dist/VideoPlayer/ima/loadImaSdk.d.ts

@@ -0,0 +1,10 @@
+export declare const IMA_SDK_URL = "https://imasdk.googleapis.com/js/sdkloader/ima3.js";
+export declare const isImaSdkLoaded: () => boolean;
+/**
+ * Loads the Google IMA HTML5 SDK once per URL per page.
+ */
+export declare const loadImaSdk: (sdkUrl?: string) => Promise<void>;
+/**
+ * Fire-and-forget IMA SDK preload. Safe to call before the player mounts.
+ */
+export declare const preloadImaSdk: (sdkUrl?: string) => void;

package/dist/VideoPlayer/ima/suppressImaUi.d.ts

@@ -0,0 +1,3 @@
+export declare const suppressImaUi: (roots: HTMLElement[]) => void;
+export declare const getImaUiRoots: (container: HTMLElement | null, wrapper: HTMLElement | null) => HTMLElement[];
+export declare const watchImaUi: (roots: HTMLElement[]) => (() => void);

package/dist/VideoPlayer/ima/syncImaAdUi.d.ts

@@ -0,0 +1,5 @@
+import type { VideoState } from "../../store/types/StoreTypes";
+type ImaAdUiSetters = Pick<VideoState, "setAdCurrentTime" | "setCanSkipAd" | "setSkipCountdown" | "setImaSkipEnabled">;
+/** Syncs ad progress + skip countdown from the active IMA AdsManager. */
+export declare const syncImaAdUi: (manager: google.ima.AdsManager, currentAd: google.ima.Ad | null, adDurationSeconds: number, setters: ImaAdUiSetters) => void;
+export {};

package/dist/VideoPlayer/ima/triggerImaSkip.d.ts

@@ -0,0 +1,6 @@
+export declare const findNativeSkip: (root: ParentNode) => HTMLElement | null;
+/** Clears hide styles so IMA's skip handler receives a real activation. */
+export declare const activateNativeSkip: (element: HTMLElement) => void;
+export type ImaSkipResult = "native" | "api" | "stop" | "failed";
+/** Skips the current ad when skippable. */
+export declare const triggerImaSkip: (manager: google.ima.AdsManager | null, roots: HTMLElement[]) => ImaSkipResult;

package/dist/VideoPlayer/types/AdTypes.d.ts

@@ -1,15 +1,50 @@
 export type AdType = "pre-roll" | "mid-roll" | "post-roll" | "overlay";
+/** How the ad break is rendered: direct MP4 (`custom`) or Google IMA (`ima`). */
+export type AdProvider = "custom" | "ima";
+export interface ImaConfig {
+    /** VAST/VMAP ad tag URL from Google Ad Manager or compatible ad server. */
+    adTagUrl: string;
+    /**
+     * Tag format. Auto-detected from URL when omitted (`output=vmap` or `ad_rule=1` → VMAP).
+     * VMAP uses one IMA session for pre/mid/post breaks; VAST requests ads per break.
+     */
+    adTagFormat?: "vmap" | "vast";
+    /**
+     * Request a pre-roll from the ad tag when content is ready.
+     * @default true
+     */
+    preRoll?: boolean;
+    /**
+     * Call `contentComplete()` when main content ends (enables post-roll in VMAP tags).
+     * @default true
+     */
+    postRoll?: boolean;
+    /**
+     * Content time offsets (seconds) for additional mid-roll ad requests.
+     * Use when your tag is not a full VMAP or you need explicit cue points.
+     */
+    midRollCuePoints?: number[];
+    /** Optional content metadata for ad targeting. */
+    contentTitle?: string;
+    contentDuration?: number;
+    /** Custom URL for the IMA SDK script (defaults to Google's CDN). */
+    sdkUrl?: string;
+}
 export interface AdBreak {
     id: string;
     type: AdType;
     time: number;
+    /** Direct media URL for `custom` ads; empty for synthetic IMA breaks. */
     adUrl: string;
+    provider?: AdProvider;
     skipable?: boolean;
     skipAfter?: number;
     duration?: number;
     sponsoredUrl?: string;
 }
 export interface AdConfig {
+    /** Google IMA (VAST/VMAP). Works alongside custom MP4 `preRoll` / `midRoll` / `postRoll`. */
+    ima?: ImaConfig;
     preRoll?: AdBreak;
     midRoll?: AdBreak[];
     postRoll?: AdBreak;
@@ -31,3 +66,15 @@ export interface AdConfig {
     onAdSkip?: (adBreak: AdBreak) => void;
     onAdError?: (adBreak: AdBreak, error: Error) => void;
 }
+/** Runtime API exposed by the IMA integration for player controls. */
+export interface ImaPlaybackApi {
+    pause: () => void;
+    resume: () => void;
+    setVolume: (volume: number) => void;
+    getVolume: () => number;
+    /** Returns true if AdsManager.skip() was invoked. */
+    skip: () => boolean;
+    isSkippable: () => boolean;
+    getRemainingTime: () => number;
+    getDuration: () => number;
+}

package/dist/VideoPlayer/utils/index.d.ts

@@ -10,6 +10,7 @@ export declare const timeFormat: (seconds: number) => string;
  * @returns
  */
 export declare const secondsToMilliseconds: (seconds: number) => number;
+export declare const getSeekableLiveEdge: (video: HTMLVideoElement) => number | null;
 /**
  * @description
  * @param url

package/dist/components/ui/Popover.d.ts

@@ -5,6 +5,8 @@ interface PopoverProps {
     closeOnButtonClick?: boolean;
     className?: string;
     align?: "left" | "center" | "right";
+    onOpenChange?: (open: boolean) => void;
+    triggerAriaLabel?: string;
 }
 declare const Popover: React.FC<PopoverProps>;
 export default Popover;

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { useVideoStore } from "./store/VideoState";
 export type { VideoPlayerProps, Episode, SubtitleTrack, IntroConfig, NextEpisodeConfig, WatchHistoryData, } from "./VideoPlayer/types/VideoPlayerTypes";
 export type { SubtitleStyleConfig } from "./VideoPlayer/hooks/useSubtitleStyling";
 export type { VideoQualityConfig, SeekBarConfig, PlayPauseButtonConfig, } from "./VideoPlayer/types/VideoPlayerTypes";
+export type { AdConfig, AdBreak, AdType, AdProvider, ImaConfig, ImaPlaybackApi, } from "./VideoPlayer/types/AdTypes";
 export type { VideoState, VideoRefsState, VideoPlaybackState, VideoTimingState, VideoControlsState, VideoQualityState, SubtitlesState, EpisodesState, IntroState, } from "./store/types/StoreTypes";