@devix-technologies/react-gjirafa-vp-player 1.0.31-beta.0 → 1.0.31-beta.11

package/README.md

@@ -1,25 +1,20 @@
 # React Gjirafa VP Player
 
-A strict, lightweight React wrapper around the [Gjirafa VP Player SDK](https://vp.gjirafa.tech/documentation/docs/web-player/).
+A lightweight React wrapper for the [Gjirafa VP Player SDK](https://vp.gjirafa.tech/documentation/docs/web-player/).
 
-This package provides a clean interface for integrating the Gjirafa Player into React applications, adhering strictly to the official "Managed Script" implementation guide while adding necessary custom features for specific business needs (Reels mode, Analytics).
+## v2.0.0 - Simplified Architecture
 
-## Features
+Version 2.0.0 is a major simplification. The wrapper is now a **thin bridge** to the GTech JS player:
 
-- **Strict SDK Wrapping:** Uses the official `window.vpPlayer` / `window.vpVerticalPlayer` API.
-- **Managed Script Loading:** Handles async script loading with caching and error handling.
-- **Reels Mode:** Built-in "Overlay" UI for vertical short-form videos.
-- **Native Events:** Bridges official SDK events (play, pause, quartiles) to React callbacks.
-- **Custom Analytics:** Includes a custom "20 seconds watched" event (calculated from playback time).
-- **Playlist Support:** Handles both Web Player and Vertical Player playlist configuration differences automatically.
+- **No configuration interference** - GTech admin panel is the source of truth
+- **Auto-initialization** - Managed scripts auto-init with embedded config
+- **Event forwarding** - React callbacks for SDK events
 
 ## Installation
 
 ```bash
 npm install @devix-technologies/react-gjirafa-vp-player
 # or
-yarn add @devix-technologies/react-gjirafa-vp-player
-# or
 pnpm add @devix-technologies/react-gjirafa-vp-player
 ```
 
@@ -28,124 +23,247 @@ pnpm add @devix-technologies/react-gjirafa-vp-player
 ```tsx
 import { VPPlayer } from "@devix-technologies/react-gjirafa-vp-player";
 
-const App = () => {
-  return (
-    <div style={{ maxWidth: "800px", margin: "0 auto" }}>
-      <VPPlayer
-        playerId="unique-player-id"
-        videoUrl="https://example.com/video.mp4"
-        version="latest"
-        onPlayerPlay={() => console.log('Playing')}
-      />
-    </div>
-  );
-};
+// Using scriptId + videoId (recommended)
+<VPPlayer
+  scriptId="ptkzurnx"
+  videoId="vjsobqhe"
+  onPlay={() => console.log('Playing!')}
+/>
+
+// OR using full script URL
+<VPPlayer
+  scriptUrl="https://host.vpplayer.tech/player/ptkzurnx/vjsobqhe.js"
+  onPlay={() => console.log('Playing!')}
+/>
 ```
 
-## Usage Patterns
+## How It Works
+
+1. Wrapper generates a unique `divId` for the container
+2. Script URL: `https://host.vpplayer.tech/player/{scriptId}/{videoId}.js?divId={ourDivId}`
+3. Script loads and **auto-initializes** with GTech admin config
+4. Wrapper does **NOT** call `.setup()` - script already did it
+5. Wrapper attaches event listeners for React callbacks
+
+## Usage Examples
+
+### Web Player
+
+```tsx
+<VPPlayer
+  scriptId="ptkzurnx"
+  videoId="vjsobqhe"
+  onPlay={() => analytics.track('play')}
+  onQuartile25={() => analytics.track('25% watched')}
+  onProgress20s={() => analytics.track('20s milestone')}
+/>
+```
 
-### 1. Standard Video Player (Horizontal)
-Use for standard 16:9 content.
+### Vertical Player
 
 ```tsx
 <VPPlayer
-  playerId="main-player"
-  videoId="vjsnkiko" // API Video ID
-  projectId="agmipoaa" // Project ID
-  scriptUrl="https://host.vpplayer.tech/player/ptkzurly.js" // Your managed script URL
+  scriptId="rbqcdwzlg"
+  videoId="vjsobqhe"
+  isVertical={true}
 />
 ```
 
-### 2. Reels / Vertical Player
-Use for TikTok-style vertical feeds. Enabling `isReels` adds the overlay UI.
+### Reels Mode (TikTok-style)
 
 ```tsx
 <VPPlayer
-  playerId="reels-player"
+  scriptId="rbqcdwzlg"
+  videoId="vjsobqhe"
   isReels={true}
-  playlistId="lzxikgjw"
-  projectId="agmipnzb"
-  scriptUrl="https://host.vpplayer.tech/vertical-player/rbqcdwzlg.js"
-  thumbnailUrl="https://example.com/poster.jpg"
+  thumbnailUrl="https://example.com/thumb.jpg"
+  onClose={() => setShowPlayer(false)}
 />
 ```
 
-### 3. Custom Playlist (Direct Files)
-Pass a custom playlist structure. The wrapper automatically transforms this for the Vertical Player SDK if needed.
+### Manual Playlist (Custom Videos Array)
+
+For vertical player with your own videos array (not using GTech admin playlists):
 
 ```tsx
 <VPPlayer
-  playerId="playlist-player"
-  config={{
-    video: {
-      playlist: {
-        state: true,
-        videos: [
-          { title: "Video 1", file: "https://.../1.mp4" },
-          { title: "Video 2", file: "https://.../2.mp4" }
-        ]
-      }
-    }
+  scriptId="rbqcdwzlg"
+  projectId="agmipnzb"
+  isVertical={true}
+  playlist={{
+    videos: [
+      {
+        videoId: "1",
+        title: "Big Buck Bunny",
+        file: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
+        thumbnailUrl: "https://example.com/thumb1.jpg",
+        duration: 498,
+      },
+      {
+        videoId: "2",
+        title: "Elephants Dream",
+        file: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4",
+        thumbnailUrl: "https://example.com/thumb2.jpg",
+        duration: 738,
+      },
+    ],
+    startIndex: 0,
   }}
+  onNext={() => console.log('Next video')}
+  onVideoStarted={(data) => console.log('Playing:', data.title)}
 />
 ```
 
-## Architecture & Best Practices
+**Note:** Manual playlist mode calls `player.setup()` internally with the built config. This is required because the VP Vertical Player SDK needs `video.file` to be set even in playlist mode.
 
-This wrapper allows you to follow the "Green Field" approach—treating the player as a black box that just works.
+### Custom Container Sizing
 
-### 1. Controlled by Props, Powered by SDK
-We do **not** expose the internal player instance via `ref`. All interaction should happen via:
-- **Props:** To configure the player (`videoUrl`, `config`).
-- **Callbacks:** To react to state changes (`onPlayerPlay`, `onVideoStarted`).
+The player fills its container (100% width/height). Control sizing with a wrapper:
 
-### 2. Event Handling
-We map native SDK events directly to React props.
-- **Do not** set up your own event listeners using `window.vpPlayer().on(...)`.
-- **Use the provided callbacks:**
-  - `onPlayerStart`, `onPlayerPlay`, `onPlayerPause`, `onPlayerEnd`
-  - `onPlayerProgressEvery10Seconds` (10s interval)
-  - `onPlayerProgressAt20Seconds` (Custom 20s milestone)
-  - `onPlayerQuartile25/50/75`
+```tsx
+// Responsive 16:9
+<div style={{ width: '100%', maxWidth: '800px', aspectRatio: '16/9' }}>
+  <VPPlayer scriptId="ptkzurnx" videoId="vjsobqhe" />
+</div>
 
-### 3. Vertical Player Configuration
-The Vertical Player SDK has a different configuration schema than the Web Player.
-- **Web Player:** Accepts standard playlist object.
-- **Vertical Player:** Requires `video.file` to be set even for playlists.
-- **Solution:** This package's `vpPlayerConfigBuilder` handles this transformation automatically. You can pass the same config structure to both, and the builder will adapt it.
+// Fixed size
+<div style={{ width: '400px', height: '225px' }}>
+  <VPPlayer scriptId="ptkzurnx" videoId="vjsobqhe" />
+</div>
+```
 
-## Custom Custom Functionality
+## Props Reference
 
-### "Reels" Overlay
-When `isReels={true}`:
-1. The player renders a thumbnail first.
-2. Clicking the thumbnail opens the full-screen overlay.
-3. The player instance is initialized only when needed (or preloaded if configured).
+### Identification (one required)
 
-### "20 Seconds Watched" Event
-The Gjirafa SDK does not have a native "watched for 20 seconds" event.
-- **Implementation:** We listen to the native `time` event.
-- **Logic:** When `currentTime >= 20`, we fire `onPlayerProgressAt20Seconds` once per video session.
+| 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 |
 
-## Props Reference
+### Optional
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `playerId` | `string` | **Required.** Unique DOM ID for the player container. |
-| `scriptUrl` | `string` | **Recommended.** The full URL to your Gjirafa managed script. |
-| `videoId` | `string` | ID of the video to fetch from Gjirafa API. |
-| `videoUrl` | `string` | Direct URL to a video file (mp4/m3u8). |
-| `projectId` | `string` | Required if using `videoId` or `playlistId`. |
-| `playlistId` | `string` | ID of the playlist to fetch from Gjirafa API. |
-| `isReels` | `boolean` | Enables Vertical/Reels UI mode with overlay. |
-| `config` | `object` | Deep overrides for the player configuration object. |
-| `onPlayerEvent` | `func` | Universal callback for all analytics events. |
-
-## Migration Guide
-
-If refactoring an existing integration to use this package:
-
-1. **Remove Old Script Tags:** Ensure `vpplayer.js` is not loaded globally in your `index.html`. This package handles loading.
-2. **Remove Custom State:** Delete any local state tracking `isPlaying`, `currentTime`, etc. Rely on the player's internal state and callbacks.
-3. **Simplify Config:** Stop manually constructing complex config objects. Pass `videoId`, `playlistId`, or `videoUrl` directly as props.
-4. **Use Callbacks:** Replace custom `setInterval` analytics trackers with `onPlayerProgressEvery10Seconds` and `onPlayerQuartile...` props.
+| `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 |
+| `onPause` | ✓ | ✓ | Playback paused |
+| `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 |
+
+#### Event Implementation Notes
+
+**Horizontal Player** uses standard VP Player SDK events:
+- `ready`, `play`, `pause`, `complete`, `video-started`, `video-state`, `time`, `playlistItem`, `error`
+- Quartiles: `analytics-25%-completed`, `analytics-50%-completed`, `analytics-75%-completed`
+
+**Vertical Player** uses VP Vertical Player SDK events (different naming):
+- `vp-ready`, `playing`, `pause`, `vp-video-started`, `vp-video-state`, `vp-time`, `vp-video-switch`, `error`
+- Quartiles: `analytics-25%-completed`, `analytics-50%-completed`, `analytics-75%-completed`
+- Direction detection: Uses `player._switchDirection` property (via `queueMicrotask`) to differentiate `onNext` vs `onPrevious`
+
+**Key Differences:**
+- `onComplete` - Only available on horizontal player (vertical auto-advances)
+- `onPrevious` - Only available on vertical player (horizontal has no direction detection)
+- `onNext` on horizontal fires for ANY playlist change (next button, auto-advance after complete)
+
+## URL Helpers
+
+```tsx
+import {
+  getFullyManagedPlayerScriptUrl,
+  getVerticalPlayerScriptUrl,
+  appendDivIdToUrl,
+} from '@devix-technologies/react-gjirafa-vp-player';
+
+// Build managed script URL
+const url = getFullyManagedPlayerScriptUrl('ptkzurnx', 'vjsobqhe');
+// => "https://host.vpplayer.tech/player/ptkzurnx/vjsobqhe.js"
+
+// Build vertical player URL
+const verticalUrl = getVerticalPlayerScriptUrl('rbqcdwzlg');
+// => "https://host.vpplayer.tech/vertical-player/rbqcdwzlg.js"
+```
+
+## Advanced: Direct Hook Usage
+
+For programmatic control, use the hook directly:
+
+```tsx
+import { useVPPlayerLogic, PlayerContainer } from '@devix-technologies/react-gjirafa-vp-player';
+
+function CustomPlayer() {
+  const { playerRef, playerInstanceRef, isScriptLoaded, generatedPlayerId } =
+    useVPPlayerLogic({
+      scriptId: 'ptkzurnx',
+      videoId: 'vjsobqhe',
+    });
+
+  return (
+    <div>
+      <PlayerContainer
+        id={generatedPlayerId}
+        ref={playerRef}
+        width="100%"
+        height="auto"
+        $hiddenClasses={[]}
+      />
+      <button onClick={() => playerInstanceRef.current?.play?.()}>Play</button>
+      <button onClick={() => playerInstanceRef.current?.pause?.()}>Pause</button>
+    </div>
+  );
+}
+```
+
+## Migration from v1.x
+
+See [MIGRATION.md](./MIGRATION.md) for detailed upgrade instructions.
+
+### Quick Summary
+
+```tsx
+// BEFORE (v1.x)
+<VPPlayer
+  videoId="vjsobqhe"
+  projectId="abc123"
+  scriptUrl="https://host.vpplayer.tech/player/ptkzurnx.js"
+  pureMode={true}
+  config={{ video: { autoplay: true } }}
+  onPlayerPlay={() => console.log('play')}
+/>
+
+// AFTER (v2.0.0)
+<VPPlayer
+  scriptId="ptkzurnx"
+  videoId="vjsobqhe"
+  onPlay={() => console.log('play')}
+/>
+```
+
+## License
+
+MIT