@devix-technologies/react-gjirafa-vp-player 1.0.31-beta.18 → 1.0.31-beta.20

package/README.md

@@ -53,20 +53,16 @@ import { VPPlayer } from "@devix-technologies/react-gjirafa-vp-player";
 <VPPlayer
   scriptId="ptkzurnx"
   videoId="vjsobqhe"
-  onPlay={() => analytics.track('play')}
-  onQuartile25={() => analytics.track('25% watched')}
-  onProgress20s={() => analytics.track('20s milestone')}
+  onPlay={() => analytics.track("play")}
+  onQuartile25={() => analytics.track("25% watched")}
+  onProgress20s={() => analytics.track("20s milestone")}
 />
 ```
 
 ### Vertical Player
 
 ```tsx
-<VPPlayer
-  scriptId="rbqcdwzlg"
-  videoId="vjsobqhe"
-  isVertical={true}
-/>
+<VPPlayer scriptId="rbqcdwzlg" videoId="vjsobqhe" isVertical={true} />
 ```
 
 ### Reels Mode (TikTok-style)
@@ -109,8 +105,8 @@ For vertical player with your own videos array (not using GTech admin playlists)
     ],
     startIndex: 0,
   }}
-  onNext={() => console.log('Next video')}
-  onVideoStarted={(data) => console.log('Playing:', data.title)}
+  onNext={() => console.log("Next video")}
+  onVideoStarted={(data) => console.log("Playing:", data.title)}
 />
 ```
 
@@ -132,59 +128,111 @@ The player fills its container (100% width/height). Control sizing with a wrappe
 </div>
 ```
 
+## Video Locking
+
+Video locking lets you lock a portion of each video (e.g. require watching N seconds or N% before skipping). The SDK supports this via a `shouldLockVideo` callback and `removeVideoLock()`. The recommended approach is to set the callback inside `onVideoSwitch` so locking applies after each video switch.
+
+### Ref methods
+
+- **`shouldLockVideo(callback)`** – Set the callback that returns lock config. Pass a function that returns `{ isEnabled, type, value }`, or `null` to clear. Matches SDK naming.
+- **`removeVideoLock()`** – Clear any active lock.
+
+### Lock config shape
+
+```ts
+{ isEnabled: boolean; type: "seconds" | "percentage"; value: number }
+```
+
+### Recommended pattern: lock on video switch
+
+Use `onVideoSwitch` to set or clear `shouldLockVideo` after each switch. In the callback you can decide whether to lock (e.g. from app state) and for how long.
+
+```tsx
+const playerRef = useRef<VPPlayerRef>(null);
+
+<VPPlayer
+  ref={playerRef}
+  scriptId="ptkzurnx"
+  videoId="vjsobqhe"
+  config={{ /* ... */ }}
+  onVideoSwitch={() => {
+    const shouldLock = true; // your logic, e.g. from state
+    if (shouldLock) {
+      playerRef.current?.shouldLockVideo(() => ({
+        isEnabled: true,
+        type: "seconds",
+        value: 20,
+      }));
+    } else {
+      playerRef.current?.removeVideoLock();
+      playerRef.current?.shouldLockVideo(() => ({
+        isEnabled: false,
+        type: "seconds",
+        value: 0,
+      }));
+    }
+  }}
+/>
+```
+
+To only lock for a period after each switch, enable locking in `onVideoSwitch` with the desired `value` (e.g. 20 seconds). To disable locking for the next video, call `removeVideoLock()` and set `shouldLockVideo` to return `isEnabled: false`.
+
 ## Props Reference
 
 ### Identification (one required)
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `scriptId` | `string` | GTech script ID (e.g., "ptkzurnx") |
-| `videoId` | `string` | GTech video ID (e.g., "vjsobqhe") |
-| `scriptUrl` | `string` | Full managed script URL |
+| Prop        | Type     | Description                        |
+| ----------- | -------- | ---------------------------------- |
+| `scriptId`  | `string` | GTech script ID (e.g., "ptkzurnx") |
+| `videoId`   | `string` | GTech video ID (e.g., "vjsobqhe")  |
+| `scriptUrl` | `string` | Full managed script URL            |
 
 ### Optional
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `projectId` | `string` | GTech project ID (required for manual playlist) |
-| `playlist` | `ManualPlaylistConfig` | Custom videos array for manual playlist mode |
-| `playerId` | `string` | Custom container ID (auto-generated if not provided) |
-| `isVertical` | `boolean` | Force vertical player mode |
-| `isReels` | `boolean` | Enable Reels overlay mode |
-| `thumbnailUrl` | `string` | Thumbnail for Reels mode |
-| `className` | `string` | CSS class for container |
-| `hiddenClasses` | `string[]` | SDK element classes to hide |
+| Prop            | Type                   | Description                                          |
+| --------------- | ---------------------- | ---------------------------------------------------- |
+| `projectId`     | `string`               | GTech project ID (required for manual playlist)      |
+| `playlist`      | `ManualPlaylistConfig` | Custom videos array for manual playlist mode         |
+| `playerId`      | `string`               | Custom container ID (auto-generated if not provided) |
+| `isVertical`    | `boolean`              | Force vertical player mode                           |
+| `isReels`       | `boolean`              | Enable Reels overlay mode                            |
+| `thumbnailUrl`  | `string`               | Thumbnail for Reels mode                             |
+| `className`     | `string`               | CSS class for container                              |
+| `hiddenClasses` | `string[]`             | SDK element classes to hide                          |
 
 ### Event Callbacks
 
-| Prop | Horizontal | Vertical | Description |
-|------|:----------:|:--------:|-------------|
-| `onReady` | ✓ | ✓ | Player initialized |
-| `onPlay` | ✓ | ✓ | Playback started (initial play) |
-| `onPause` | ✓ | ✓ | Playback paused (user-initiated) |
-| `onResume` | ✗ | ✓ | Playback resumed after pause (vertical only) |
-| `onComplete` | ✓ | ✗ | Video completed (horizontal only) |
-| `onError` | ✓ | ✓ | Error occurred |
-| `onVideoStarted` | ✓ | ✓ | Video metadata available (returns `CurrentVideoData`) |
-| `onTimeUpdate` | ✓ | ✓ | Continuous time updates (returns seconds) |
-| `onQuartile25` | ✓ | ✓ | 25% watched |
-| `onQuartile50` | ✓ | ✓ | 50% watched |
-| `onQuartile75` | ✓ | ✓ | 75% watched |
-| `onNext` | ✓ | ✓ | Next video in playlist |
-| `onPrevious` | ✗ | ✓ | Previous video (vertical only) |
-| `onProgress10s` | ✓ | ✓ | Every ~10 seconds (returns seconds) |
-| `onProgress20s` | ✓ | ✓ | 20 second milestone (returns seconds) |
-| `onClose` | - | - | Reels overlay closed |
+| Prop             | Horizontal | Vertical | Description                                           |
+| ---------------- | :--------: | :------: | ----------------------------------------------------- |
+| `onReady`        |     ✓      |    ✓     | Player initialized                                    |
+| `onPlay`         |     ✓      |    ✓     | Playback started (initial play)                       |
+| `onPause`        |     ✓      |    ✓     | Playback paused (user-initiated)                      |
+| `onResume`       |     ✗      |    ✓     | Playback resumed after pause (vertical only)          |
+| `onComplete`     |     ✓      |    ✗     | Video completed (horizontal only)                     |
+| `onError`        |     ✓      |    ✓     | Error occurred                                        |
+| `onVideoStarted` |     ✓      |    ✓     | Video metadata available (returns `CurrentVideoData`) |
+| `onTimeUpdate`   |     ✓      |    ✓     | Continuous time updates (returns seconds)             |
+| `onQuartile25`   |     ✓      |    ✓     | 25% watched                                           |
+| `onQuartile50`   |     ✓      |    ✓     | 50% watched                                           |
+| `onQuartile75`   |     ✓      |    ✓     | 75% watched                                           |
+| `onNext`         |     ✓      |    ✓     | Next video in playlist                                |
+| `onPrevious`     |     ✗      |    ✓     | Previous video (vertical only)                        |
+| `onProgress10s`  |     ✓      |    ✓     | Every ~10 seconds (returns seconds)                   |
+| `onProgress20s`  |     ✓      |    ✓     | 20 second milestone (returns seconds)                 |
+| `onVideoSwitch`  |     ✓      |    ✓     | SDK `vp-video-switch` (use for video locking)         |
+| `onClose`        |     -      |    -     | Reels overlay closed                                  |
 
 #### Event Implementation Notes
 
 **Horizontal Player** uses standard VP Player SDK events via `.on()` listener:
+
 - `ready`, `play`, `pause`, `complete`, `video-started`, `video-state`, `time`, `playlistItem`, `error`
 - Quartiles: `analytics-25%-completed`, `analytics-50%-completed`, `analytics-75%-completed`
 
 **Vertical Player** uses a combination of `.on()` listener and the global `vp-event` handler:
 
 Standard events via `.on()`:
+
 - `vp-first-frame`, `vp-video-started`, `vp-video-state`, `vp-time`, `vp-video-switch`, `error`
 - Quartiles: `analytics-25%-completed`, `analytics-50%-completed`, `analytics-75%-completed`
 
@@ -192,15 +240,16 @@ Standard events via `.on()`:
 
 The following events are intercepted from the global `vp-event` emission because the VP Vertical Player SDK doesn't expose them via the standard `.on()` listener:
 
-| Event | SDK Event | Special Logic |
-|-------|-----------|---------------|
-| `onPlay` | `vp-state-playing` | Fires on initial play (when not resuming from pause) |
-| `onPause` | `vp-state-paused` | Only fires on **user-initiated** pause (not on video loop/end) |
-| `onResume` | `vp-state-playing` | Fires when resuming after **user-initiated** pause |
+| Event      | SDK Event          | Special Logic                                                  |
+| ---------- | ------------------ | -------------------------------------------------------------- |
+| `onPlay`   | `vp-state-playing` | Fires on initial play (when not resuming from pause)           |
+| `onPause`  | `vp-state-paused`  | Only fires on **user-initiated** pause (not on video loop/end) |
+| `onResume` | `vp-state-playing` | Fires when resuming after **user-initiated** pause             |
 
 **User Interaction Tracking:**
 
 To distinguish between user actions and automatic playback events (like video loops), we track the `vp-user-interaction` event:
+
 - When `vp-user-interaction` fires before `vp-state-paused` → user clicked pause → `onPause` fires
 - When `vp-user-interaction` fires before `vp-state-playing` (after pause) → user clicked play → `onResume` fires
 - When `vp-state-paused` fires without prior user interaction → video ended/looped → no `onPause` (silent)
@@ -209,6 +258,7 @@ To distinguish between user actions and automatic playback events (like video lo
 This ensures analytics events like `player_pause` and `player_resume` only fire for actual user actions, not automatic video looping.
 
 **Key Differences:**
+
 - `onComplete` - Only available on horizontal player (vertical auto-advances to next video)
 - `onResume` - Only available on vertical player (horizontal has no pause/resume distinction)
 - `onPrevious` - Only available on vertical player (horizontal has no direction detection)
@@ -222,14 +272,14 @@ import {
   getFullyManagedPlayerScriptUrl,
   getVerticalPlayerScriptUrl,
   appendDivIdToUrl,
-} from '@devix-technologies/react-gjirafa-vp-player';
+} from "@devix-technologies/react-gjirafa-vp-player";
 
 // Build managed script URL
-const url = getFullyManagedPlayerScriptUrl('ptkzurnx', 'vjsobqhe');
+const url = getFullyManagedPlayerScriptUrl("ptkzurnx", "vjsobqhe");
 // => "https://host.vpplayer.tech/player/ptkzurnx/vjsobqhe.js"
 
 // Build vertical player URL
-const verticalUrl = getVerticalPlayerScriptUrl('rbqcdwzlg');
+const verticalUrl = getVerticalPlayerScriptUrl("rbqcdwzlg");
 // => "https://host.vpplayer.tech/vertical-player/rbqcdwzlg.js"
 ```
 
@@ -238,13 +288,16 @@ const verticalUrl = getVerticalPlayerScriptUrl('rbqcdwzlg');
 For programmatic control, use the hook directly:
 
 ```tsx
-import { useVPPlayerLogic, PlayerContainer } from '@devix-technologies/react-gjirafa-vp-player';
+import {
+  useVPPlayerLogic,
+  PlayerContainer,
+} from "@devix-technologies/react-gjirafa-vp-player";
 
 function CustomPlayer() {
   const { playerRef, playerInstanceRef, isScriptLoaded, generatedPlayerId } =
     useVPPlayerLogic({
-      scriptId: 'ptkzurnx',
-      videoId: 'vjsobqhe',
+      scriptId: "ptkzurnx",
+      videoId: "vjsobqhe",
     });
 
   return (
@@ -257,7 +310,9 @@ function CustomPlayer() {
         $hiddenClasses={[]}
       />
       <button onClick={() => playerInstanceRef.current?.play?.()}>Play</button>
-      <button onClick={() => playerInstanceRef.current?.pause?.()}>Pause</button>
+      <button onClick={() => playerInstanceRef.current?.pause?.()}>
+        Pause
+      </button>
     </div>
   );
 }

package/dist/index.d.ts

@@ -267,6 +267,8 @@ export declare interface EventCallbackRefs {
     onPrevious?: (currentTime: number) => void;
     onProgress10s?: (seconds: number) => void;
     onProgress20s?: (seconds: number) => void;
+    onPlaylistItem?: (data: CurrentVideoData_2) => void;
+    onVideoSwitch?: (data: VideoSwitchData) => void;
 }
 
 /**
@@ -726,7 +728,7 @@ export declare interface TimesliderSkin {
  * 1. **Auto-init mode** (default): Load managed script that auto-initializes with GTech admin config
  * 2. **Config override mode**: Fetch config, merge user overrides, and call setup()
  */
-export declare const useVPPlayerLogic: ({ scriptId, videoId, scriptUrl, projectId, config, playerId, isVertical, isReels, onReady, onPlay, onPause, onResume, onComplete, onError, onVideoStarted, onTimeUpdate, onQuartile25, onQuartile50, onQuartile75, onNext, onPrevious, onProgress10s, onProgress20s, }: VPPlayerProps_2) => {
+export declare const useVPPlayerLogic: ({ scriptId, videoId, scriptUrl, projectId, config, playerId, isVertical, isReels, onReady, onPlay, onPause, onResume, onComplete, onError, onVideoStarted, onTimeUpdate, onQuartile25, onQuartile50, onQuartile75, onNext, onPrevious, onProgress10s, onProgress20s, onPlaylistItem, onVideoSwitch, }: VPPlayerProps_2) => {
     playerRef: RefObject<HTMLDivElement | null>;
     playerInstanceRef: RefObject<VPPlayerInstance_2 | null>;
     isScriptLoaded: boolean;
@@ -818,6 +820,17 @@ export declare interface VideoFlag {
     name: string;
 }
 
+export declare interface VideoLockingConfig {
+    isEnabled: boolean;
+    type: "seconds" | "percentage";
+    value: number;
+}
+
+export declare interface VideoSwitchData {
+    direction?: "next" | "prev";
+    currentTime?: number;
+}
+
 /**
  * Volume skin configuration
  */
@@ -936,7 +949,7 @@ export declare interface VPPlayerConfig {
  * @interface VPPlayerInstance
  */
 export declare interface VPPlayerInstance {
-    setup: (config: unknown) => void;
+    setup: (config: unknown) => Promise<void> | void;
     destroy?: () => void;
     play?: () => void;
     pause?: () => void;
@@ -974,6 +987,9 @@ export declare interface VPPlayerInstance {
     setCurrentQuality?: (index: number) => void;
     setLevelToAuto?: () => void;
     setCuePoint?: (cue: number, callback: () => void) => void;
+    setVideoLocking?: (config: VideoLockingConfig) => void;
+    removeVideoLock?: () => void;
+    shouldLockVideo?: () => VideoLockingConfig;
     on?: (event: string, callback: (data?: unknown) => void) => void;
     off?: (event: string, callback?: (data?: unknown) => void) => void;
     videoIndex?: number;
@@ -1151,6 +1167,17 @@ export declare interface VPPlayerProps {
      * @param seconds - Current playback position (should be ~20)
      */
     onProgress20s?: (seconds: number) => void;
+    /**
+     * Called when the active playlist item changes (horizontal player only)
+     * Fires reliably for all playlist transitions, including auto-advance
+     * @param data - Video metadata for the new playlist item
+     */
+    onPlaylistItem?: (data: CurrentVideoData_2) => void;
+    /**
+     * Called when the SDK emits vp-video-switch (e.g. user switched to next/prev video).
+     * Use with ref.shouldLockVideo() for video locking; see README Video Locking section.
+     */
+    onVideoSwitch?: (data: VideoSwitchData) => void;
 }
 
 /**
@@ -1189,6 +1216,15 @@ export declare interface VPPlayerRef {
     isPlaying: () => boolean;
     isPaused: () => boolean;
     isFullscreen: () => boolean;
+    /**
+     * Set the shouldLockVideo callback on the player (SDK naming).
+     * Pass a function that returns lock config, or null to clear.
+     */
+    shouldLockVideo: (callback: (() => VideoLockingConfig) | null) => void;
+    /**
+     * Remove/unlock the video.
+     */
+    removeVideoLock: () => void;
 }
 
 /**