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

package/README.md

@@ -1,17 +1,20 @@
-# VP Player Component Documentation
+# React Gjirafa VP Player
 
-The `VPPlayer` component is a React-based video player built using the VP Player library from `https://host.vpplayer.tech`.
+A strict, lightweight React wrapper around the [Gjirafa VP Player SDK](https://vp.gjirafa.tech/documentation/docs/web-player/).
 
-It supports multiple ways to configure and play videos, including single files, playlists with direct files, single videos fetched via API, and playlists fetched via API. This document outlines the component's interface, configuration, and usage.
+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).
 
-## Overview
+## Features
 
-The `VPPlayer` component dynamically loads the VP Player script (`vpplayer.js`) and initializes it with a configuration object. The configuration is built based on the provided props, which determine the source and type of video data to play. It supports **Horizontal (Standard)** and **Vertical (Reels)** modes, along with comprehensive analytics tracking.
+- **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.
 
 ## Installation
 
-To install the package, run:
-
 ```bash
 npm install @devix-technologies/react-gjirafa-vp-player
 # or
@@ -22,8 +25,6 @@ pnpm add @devix-technologies/react-gjirafa-vp-player
 
 ## Quick Start
 
-Here is a basic example of how to use the `VPPlayer` component in your React application:
-
 ```tsx
 import { VPPlayer } from "@devix-technologies/react-gjirafa-vp-player";
 
@@ -31,733 +32,120 @@ const App = () => {
   return (
     <div style={{ maxWidth: "800px", margin: "0 auto" }}>
       <VPPlayer
-        playerId="my-unique-player-id"
+        playerId="unique-player-id"
         videoUrl="https://example.com/video.mp4"
         version="latest"
+        onPlayerPlay={() => console.log('Playing')}
       />
     </div>
   );
 };
-
-export default App;
-```
-
-## Source Files Structure
-
-```
-├── src/
-│   ├── components/
-│   │   └── VPPlayer/
-│   │       ├── index.ts
-│   │       └── ui/
-│   │           ├── index.ts
-│   │           ├── styled.tsx
-│   ├── config/
-│   │   ├── index.ts
-│   │   ├── vpPlayerConfig.ts
-│   ├── constants/
-│   │   ├── index.ts
-│   │   ├── vpPlayer.ts
-│   ├── contexts/
-│   │   ├── VPPlayerContext.tsx
-│   │   ├── index.ts
-│   ├── features/
-│   │   ├── VPPlayer.tsx
-│   │   ├── stories/
-│   │   │   ├── ads/
-│   │   │   │   ├── Ads.stories.tsx
-│   │   │   ├── context/
-│   │   │   │   ├── Context.stories.tsx
-│   │   │   ├── playback/
-│   │   │   │   ├── Playback.stories.tsx
-│   ├── fixtures/
-│   │   ├── index.ts
-│   │   ├── playlist.ts
-│   ├── hooks/
-│   │   ├── index.ts
-│   │   ├── useVPPlayerEvents.ts
-│   │   ├── useVPPlayerLogic.ts
-│   │   ├── useVPPlayerScript.ts
-│   │   ├── useVideoData.ts
-│   ├── interfaces/
-│   │   ├── config.ts
-│   │   ├── index.ts
-│   │   ├── instance.ts
-│   │   ├── props.ts
-│   │   ├── styles.ts
-│   ├── types/
-│   │   ├── api.types.ts
-│   │   ├── playerEvents.types.ts
-│   │   ├── index.ts
-│   ├── utils/
-│   │   ├── index.ts
-│   │   ├── vpPlayerConfigBuilder.ts
-│   │   ├── vpPlayerUtils.ts
-│   ├── App.css
-│   ├── App.tsx
-│   ├── index.css
-│   ├── main.tsx
-│   ├── vite-env.d.ts
-```
-
-## Interface
-
-The component accepts props defined by the `VPPlayerProps` interface:
-
-```typescript
-interface VPPlayerProps {
-  playerId: string; // Unique identifier for the player instance, might be random integer,
-                       but must be unique, for multiple VPPlayer instances use different values
-  videoId?: string; // Unique identifier for the video or a placeholder
-  version?: string | null; // Optional version e.g. "v2.1.1" of the VP Player script (defaults to 'latest')
-  videoUrl?: string; // Direct URL to a single video file (e.g., .mp4, .m3u8)
-  projectId?: string; // Project ID for API calls (used with videoId or playlistId)
-  playlistId?: string; // Playlist ID for fetching a playlist from API
-  config?: Partial<VPPlayerConfig>; // Optional partial configuration to override defaults
-  isReels?: boolean; // Optional flag to enable Reels/iShorties mode (defaults to false)
-  thumbnailUrl?: string; // Optional URL to a thumbnail image for Reels mode
-  hiddenClasses?: string[]; // Optional array of CSS class names to hide specific player elements
-  className?: string; // Optional CSS class name for additional styling of the player
-  onClose, // Handler function triggered when the player is closed.
-  isPlayerVisible, // Flag indicating whether the player is currently visible.
-  onPlaylistData?: (videos: PlaylistItem[]) => void; // Optional callback that fires when playlist data is loaded
-  onVideoStarted?: (videoData: CurrentVideoData) => void; // Optional callback that fires when a video starts playing
-
-  // Analytics & Event Callbacks
-  onPlayerStart?: (event: string) => void; // Fires when playback starts for the first time
-  onPlayerPlay?: (event: string) => void; // Fires on subsequent play actions
-  onPlayerPause?: (event: string) => void; // Fires when playback is paused
-  onPlayerResume?: (event: string) => void; // Fires when playback is resumed
-  onPlayerNext?: (event: string) => void; // Fires on next video click
-  onPlayerPrevious?: (event: string) => void; // Fires on previous video click
-  onPlayerEnd?: (event: string) => void; // Fires when video ends
-  onPlayerProgressEvery10Seconds?: (event: string, currentPosition: number) => void; // Fires every 10s
-  onPlayerProgressAt20Seconds?: (event: string, currentPosition: number) => void; // Fires specifically at 20s
-  onPlayerQuartile25?: (event: string, currentPosition: number) => void; // Fires at 25% progress
-  onPlayerQuartile50?: (event: string, currentPosition: number) => void; // Fires at 50% progress
-  onPlayerQuartile75?: (event: string, currentPosition: number) => void; // Fires at 75% progress
-  onPlayerEvent?: (event: string, currentPosition?: number) => void; // Universal callback for all events
-}
 ```
 
-## Props Description
-
-### **playerId: string**
-
-- Unique identifier for the player instance. Must be unique across multiple `VPPlayer` instances to avoid conflicts.
-
-### **videoId?: string**
-
-- Optional identifier for a single video to fetch from the API. Used in conjunction with `projectId` for API-based video playback.
-
-### **version?: string | null**
-
-- Optional version of the VP Player script (e.g., `"v2.1.1"`). Defaults to `"latest"` if not specified.
-
-### **videoUrl?: string**
-
-- Optional direct URL to a video file (e.g., `.mp4`, `.m3u8`) for single-file playback without API involvement.
-
-### **projectId?: string**
-
-- Optional project ID for API calls. Required when using `videoId` or `playlistId` to fetch video data from the API.
-
-### **playlistId?: string**
-
-- Optional playlist ID for fetching a playlist from the API. Used with `projectId` to retrieve a dynamic playlist.
+## Usage Patterns
 
-### **config?: Partial<VPPlayerConfig>**
+### 1. Standard Video Player (Horizontal)
+Use for standard 16:9 content.
 
-- Optional partial configuration object to override the default `VPPlayerConfig`. Allows customization of player behavior and settings.
-
-### **isReels?: boolean**
-
-- Optional flag to enable Reels/iShorties mode, optimizing the player for short vertical video playback (e.g., 9:16 aspect ratio). Defaults to `false`.
-
-### **thumbnailUrl?: string**
-
-- Optional URL to a thumbnail image displayed in Reels mode before playback starts. Enhances the visual preview for short videos.
-
-### **hiddenClasses?: string[]**
-
-- Optional array of CSS class names corresponding to player elements that should be hidden. Elements with these classes will have `display: none` applied, effectively removing them from the visible UI without affecting their underlying functionality (unless explicitly disabled). Useful for customizing the player's appearance by hiding unwanted controls.
-- **Example**: `["vp-icon-share", "vp-icon-fullscreen"]` hides the share and fullscreen buttons.
-
-### **className?: string**
-
-- Optional CSS class name for additional styling of the player. This prop allows you to apply custom styles to the entire player component or its internal elements by targeting specific CSS classes (e.g., vp-play-pause, vp-control-bar). Styles must be defined in an external CSS file, and you can use !important to override default styles if needed. This provides flexibility to customize the player's appearance, such as changing colors, repositioning buttons, or adjusting layout.
-- **Example**: `"custom-player"` can be used to apply styles defined in an external CSS file like `.custom-player { border: 2px solid red; }` or `.custom-player .vp-play-pause { display: none; }`.
-
-### **onClose?: => void;**
-
-- Optional handler function triggered when the player is closed. This callback is invoked when the user closes the player, typically via a close button or an overlay dismissal.
-
-### **isPlayerVisible?: boolean;**
-
-- Optional flag indicating whether the player is currently visible. Controls the visibility of the player component, typically used to show or hide the player in a modal, overlay, or inline context.
-
-### **onPlaylistData?: (videos: PlaylistItem[]) => void**
-
-- Optional callback function that fires when playlist data is successfully loaded from the API. This is useful for:
-  - Getting a list of all videos in the playlist (including main and backup playlists)
-  - Displaying a video list/menu in your UI
-  - Pre-loading thumbnails or metadata
-  - Building custom playlist navigation
-- **Parameters:**
-  - `videos`: Array of `PlaylistItem` objects containing video metadata (title, hlsUrl, thumbnailUrl, duration, isBackupPlaylist, mediaId)
-- **When it fires:**
-  - Once when playlist data is fetched from API (for playlists via `playlistId`)
-- **Example:**
-```typescript
+```tsx
 <VPPlayer
-  playerId="player"
-  projectId="agmipnzb"
-  playlistId="lzxikgjw"
-  onPlaylistData={(videos) => {
-    console.log('Playlist loaded:', videos.length, 'videos');
-    console.log('Main videos:', videos.filter(v => !v.isBackupPlaylist).length);
-    console.log('Backup videos:', videos.filter(v => v.isBackupPlaylist).length);
-    // Update your UI with playlist data
-  }}
+  playerId="main-player"
+  videoId="vjsnkiko" // API Video ID
+  projectId="agmipoaa" // Project ID
+  scriptUrl="https://host.vpplayer.tech/player/ptkzurly.js" // Your managed script URL
 />
 ```
 
-### **onVideoStarted?: (videoData: CurrentVideoData) => void**
+### 2. Reels / Vertical Player
+Use for TikTok-style vertical feeds. Enabling `isReels` adds the overlay UI.
 
-- Optional callback function that fires when a video starts playing. This provides real-time information about the currently playing video. Behavior differs between player types:
-  
-  **Vertical Player (Reels):**
-  - Fires on scroll (swipe up/down) to navigate between videos
-  - Fires on arrow button clicks (next/previous)
-  - Returns basic metadata from the already-loaded playlist
-  
-  **Horizontal Player (Standard):**
-  - Fires on Next/Previous button clicks
-  - Fires when video ends and next video auto-plays
-  - Fetches **complete metadata from API** (`https://host.vpplayer.tech/player/{playerId}/{videoId}.json`)
-  - Returns comprehensive data including author, tags, publishDate, premium status, etc.
-
-- **Parameters:**
-  - `videoData`: Object containing video metadata:
-    - `videoId` - Video ID
-    - `title` - Video title
-    - `description` - Video description (HTML)
-    - `file` / `hlsUrl` - Video stream URL
-    - `thumbnailUrl` - Thumbnail image URL
-    - `duration` - Video duration in seconds
-    - `videoIndex` - Index in playlist (0-based)
-    - `playlistVideoIndex` - VP Player playlist index
-    - `isBackupPlaylist` - Whether video is from backup playlist
-    - **Horizontal player additional fields:**
-      - `publishDate` - Publication date (ISO format)
-      - `projectId` - Project/entity ID
-      - `premium` - Whether video is locked/premium
-      - `author` - Video author name
-      - `tags` - Array of video tags
-    
-- **Use cases:**
-  - **Analytics tracking**: Track video views, engagement, navigation patterns
-  - **Custom UI updates**: Display current video info, progress indicators
-  - **Content recommendations**: Use tags/author to suggest related content
-  - **Monetization**: Check premium status, track ad opportunities
-  - **Social features**: Display author info, enable sharing
-
-- **Example (Vertical Player):**
-```typescript
+```tsx
 <VPPlayer
-  playerId="vertical-player"
-  projectId="agmipnzb"
-  playlistId="lzxikgjw"
-  scriptUrl="https://host.vpplayer.tech/vertical-player/rbqcdwznd.js"
+  playerId="reels-player"
   isReels={true}
-  onVideoStarted={(videoData) => {
-    console.log('Video changed:', videoData.title);
-    console.log('Video index:', videoData.videoIndex);
-    // Track analytics, update UI
-  }}
-/>
-```
-
-- **Example (Horizontal Player with full metadata):**
-```typescript
-<VPPlayer
-  playerId="horizontal-player"
+  playlistId="lzxikgjw"
   projectId="agmipnzb"
-  videoId="vjsnuhvm"
-  scriptUrl="https://host.vpplayer.tech/player/ptkzurnx.js"
-  onVideoStarted={(videoData) => {
-    console.log('Video started:', videoData.title);
-    console.log('Author:', videoData.author);
-    console.log('Tags:', videoData.tags);
-    console.log('Published:', videoData.publishDate);
-    console.log('Premium:', videoData.premium);
-    
-    // Send to analytics
-    analytics.track('video_started', {
-      video_id: videoData.videoId,
-      title: videoData.title,
-      author: videoData.author,
-      tags: videoData.tags
-    });
-  }}
-/>
-```
-
-## Configuration
-
-##### The player configuration is defined by the VPPlayerConfig interface, which is partially overridden by the config prop and dynamically built based on the input types.
-
-1. Script Loading: Loads the VP Player script (https://host.vpplayer.tech/player/${PLAYER_VERSION}/vpplayer.js) asynchronously if not already present.
-
-2. Player Setup: Once the script is loaded and the DOM element is rendered, the vpPlayer function is called with the element's ID and the final configuration.
-
-## Supported Data Input Types
-
-## Supported Data Input Types
-
-##### The VPPlayer component supports multiple types of video data inputs, determined by the props provided:
-
-1. **Single Video File**\
-   Props: videoUrl\
-   Behavior: Plays a single video directly from the provided URL.
-
-##### Usage:
-
-```bash
-<VPPlayer
-  playerId="player-1" // Must be a unique string (e.g., "player-1", "123", etc.)
-  version="latest"
-  videoUrl="http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
+  scriptUrl="https://host.vpplayer.tech/vertical-player/rbqcdwzlg.js"
+  thumbnailUrl="https://example.com/poster.jpg"
 />
 ```
 
-2. **Playlist with Files**\
-   Props: config with video.playlist\
-   Behavior: Plays a playlist of videos defined statically in the config prop.
-
-##### Usage:
-
-```bash
-<VPPlayer
-  playerId="player-2"
-  version="latest"
-  config={{
-    projectId: 'vp-player-projectId', // optional placeholder
-    video: {
-      file: playlist.videos[0].file, // Initial video file, first in the queue
-      playlist: playlist, // Pass the full playlist array object
-    },
-  }}
-/>
-```
-
-3. **Single Video via API (VideoId)**\
-   Props: projectId, videoId\
-   Behavior: Fetches the playbackUrl from the API endpoint https://vp-api.gjirafa.tech/api/v2/projects/{projectId}/videos?search={videoId} and plays the video.
-
-##### Usage:
-
-```bash
-<VPPlayer
-  playerId="player-3"
-  version="latest"
-  videoId="vjsnuxxx"
-  projectId="agmipxxx"
-/>
-```
-
-4. **Playlist via API (PlaylistId)**\
-   Props: projectId, playlistId\
-   Behavior: Fetches a playlist from the API endpoint https://vp-api.gjirafa.tech/api/projects/{projectId}/playlists/{playlistId}/videos and builds a playlist object dynamically.
-
-##### Usage:
-
-```bash
-<VPPlayer
-  playerId="player-4"
-  version="latest"
-  projectId="agmipxxx"
-  playlistId="lzxikxxx"
-/>
-```
-
-5. **Example with `hiddenClasses` and `className`**\
-
-##### Usage:
+### 3. Custom Playlist (Direct Files)
+Pass a custom playlist structure. The wrapper automatically transforms this for the Vertical Player SDK if needed.
 
-```bash
+```tsx
 <VPPlayer
-  playerId="player-5"
-  isReels={true}
-  thumbnailUrl="https://images.pexels.com/videos/4678261/pexels-photo-4678261.jpeg?auto=compress&cs=tinysrgb&w=600"
-  hiddenClasses={["vp-icon-share", "vp-icon-fullscreen"]} // Hides share and fullscreen buttons
-  className="custom-player" // Defined class for custom styling
+  playerId="playlist-player"
   config={{
     video: {
       playlist: {
         state: true,
-        playlistVideoIndex: 0,
         videos: [
-          { videoId: "1", file: "https://videos.pexels.com/video-files/4678261/4678261-hd_1080_1920_25fps.mp4" },
-          { videoId: "2", file: "https://videos.pexels.com/video-files/4678261/4678261-hd_1080_1920_25fps.mp4" },
-        ],
-      },
-    },
+          { title: "Video 1", file: "https://.../1.mp4" },
+          { title: "Video 2", file: "https://.../2.mp4" }
+        ]
+      }
+    }
   }}
 />
-
-# e.g.
-/* Define custom styles in your CSS file */
-.custom-player {
-  /* Your own styles here */
-}
-```
-
-## Video Tracking & Analytics
-
-The VPPlayer component provides two powerful callbacks for tracking video playback and playlist data:
-
-### `onPlaylistData` - Playlist Data Callback
-
-Fires once when playlist is loaded. Useful for building custom UI or pre-loading data.
-
-```typescript
-import { VPPlayer } from "@dvxx/vp-player";
-import { useState } from "react";
-
-const MyPlaylistComponent = () => {
-  const [videos, setVideos] = useState([]);
-
-  return (
-    <>
-      {/* Display video list */}
-      <ul>
-        {videos.map((video, idx) => (
-          <li key={idx}>
-            {video.title} {video.isBackupPlaylist && "(Backup)"}
-          </li>
-        ))}
-      </ul>
-
-      {/* Player with callback */}
-      <VPPlayer
-        playerId="my-playlist-player"
-        projectId="agmipnzb"
-        playlistId="lzxikgjw"
-        onPlaylistData={(playlistVideos) => {
-          setVideos(playlistVideos);
-          console.log("Loaded videos:", playlistVideos.length);
-        }}
-      />
-    </>
-  );
-};
 ```
 
-### `onVideoStarted` - Video Change Tracking
-
-Fires every time a video starts (scroll, click, auto-play). Perfect for analytics and real-time UI updates.
-
-**Vertical Player Example:**
-
-```typescript
-<VPPlayer
-  playerId="reels-player"
-  projectId="agmipnzb"
-  playlistId="lzxikgjw"
-  scriptUrl="https://host.vpplayer.tech/vertical-player/rbqcdwznd.js"
-  isReels={true}
-  onVideoStarted={(videoData) => {
-    // Fires on scroll or arrow navigation
-    console.log("Now playing:", videoData.title);
-    console.log("Video index:", videoData.videoIndex);
-    
-    // Send to analytics
-    trackVideoView({
-      videoId: videoData.videoId,
-      index: videoData.videoIndex,
-      isBackup: videoData.isBackupPlaylist
-    });
-  }}
-/>
-```
-
-**Horizontal Player Example (with full metadata):**
-
-```typescript
-<VPPlayer
-  playerId="standard-player"
-  projectId="agmipnzb"
-  videoId="vjsnuhvm"
-  scriptUrl="https://host.vpplayer.tech/player/ptkzurnx.js"
-  onVideoStarted={(videoData) => {
-    // Fires on next/previous or auto-play
-    // Full metadata fetched from API
-    console.log({
-      title: videoData.title,
-      author: videoData.author,
-      tags: videoData.tags,
-      publishDate: videoData.publishDate,
-      premium: videoData.premium,
-      description: videoData.description
-    });
-    
-    // Rich analytics tracking
-    analytics.track("video_view", {
-      video_id: videoData.videoId,
-      video_title: videoData.title,
-      author: videoData.author,
-      tags: videoData.tags,
-      is_premium: videoData.premium,
-      project_id: videoData.projectId
-    });
-  }}
-/>
-```
-
-**Combined Example (both callbacks):**
-
-```typescript
-import { VPPlayer } from "@dvxx/vp-player";
-import { useState } from "react";
-
-const AdvancedPlayerComponent = () => {
-  const [playlistVideos, setPlaylistVideos] = useState([]);
-  const [currentVideo, setCurrentVideo] = useState(null);
-
-  return (
-    <div>
-      {/* Current video info */}
-      {currentVideo && (
-        <div className="video-info">
-          <h3>{currentVideo.title}</h3>
-          <p>Video {currentVideo.videoIndex + 1} of {playlistVideos.length}</p>
-          {currentVideo.author && <p>By: {currentVideo.author}</p>}
-          {currentVideo.tags && <p>Tags: {currentVideo.tags.join(", ")}</p>}
-        </div>
-      )}
-
-      {/* Player */}
-      <VPPlayer
-        playerId="advanced-player"
-        projectId="agmipnzb"
-        playlistId="lzxikgjw"
-        scriptUrl="https://host.vpplayer.tech/player/ptkzurnx.js"
-        onPlaylistData={(videos) => {
-          setPlaylistVideos(videos);
-          console.log(`Playlist loaded: ${videos.length} videos`);
-        }}
-        onVideoStarted={(videoData) => {
-          setCurrentVideo(videoData);
-          console.log(`Playing video ${videoData.videoIndex + 1}`);
-        }}
-      />
-
-      {/* Video playlist */}
-      <div className="playlist">
-        {playlistVideos.map((video, idx) => (
-          <div
-            key={idx}
-            className={currentVideo?.videoIndex === idx ? "active" : ""}
-          >
-            {video.title}
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-};
-```
-
-### Playback Event Tracking (Analytics)
-
-Besides tracking playlist and video changes, `VPPlayer` offers granular callbacks for tracking player state and progress. This is ideal for sending data to analytics services (e.g., Google Analytics, Segment).
-
-You can use **specific callbacks** for each event type or a single **universal callback**.
-
-#### 1. Available Events
-The following events are tracked:
-- **State Events:** `player_start`, `player_play`, `player_pause`, `player_resume`, `player_end`, `player_next`, `player_previous`
-- **Progress Events:** `player_progress_every_10_seconds`, `player_progress_at_20_seconds`
-- **Quartile Events:** `player_quartile_25`, `player_quartile_50`, `player_quartile_75`
-
-*Note: Progress and Quartile events allow you to access the `currentPosition` (in seconds).*
-
-#### 2. Using Specific Callbacks
-Use this approach if you want to handle only specific events.
-
-```typescript
-<VPPlayer
-  // ... other props
-  onPlayerStart={(event) => console.log("Started:", event)}
-  onPlayerPause={(event) => console.log("Paused:", event)}
-  onPlayerQuartile50={(event, time) => console.log("50% watched at:", time)}
-  onPlayerEnd={(event) => console.log("Finished:", event)}
-/>
-```
-
-#### 3. Using Universal Callback (`onPlayerEvent`)
-Use this approach to route all events through a single function, which simplifies integration with analytics providers.
-
-```typescript
-const handleAnalytics = (eventName: string, currentPosition?: number) => {
-  // Example: Send to analytics layer
-  analytics.track(eventName, {
-    video_id: "12345",
-    timestamp: currentPosition || 0,
-    device: "desktop"
-  });
-
-  console.log(`[Analytics] ${eventName}`, currentPosition ? `Time: ${currentPosition}` : "");
-};
-
-<VPPlayer
-  playerId="analytics-player"
-  // ... other props
-  onPlayerEvent={handleAnalytics}
-/>
-```
-
-## Release Notes
-
-### v1.0.27
-- **Fixes:**
-    - Fixed `getCurrentVideoData()` to support **2 data sources**: config-based playlist, and single video
-    - Fixed `onVideoStarted` callback to correctly return video data for config-based playlists
-- **Features:**
-    - Improved video tracking for playlists passed directly via `config` prop
-
-### v1.0.26
-- **Fixes:**
-    - Fixed **config-based playlist indexing** for vertical players - `onVideoStarted` now correctly reports video index on scroll.
-    - Fixed `getCurrentVideoData()` to properly handle playlists passed via `config.video.playlist.videos`.
-    - Improved `vpPlayerConfigBuilder` to use correct initial video based on `playlistVideoIndex`.
-- **Refactor:**
-    - Removed `fetchedPlaylist` dependency from `useVPPlayerLogic` - all playlist data now flows through config.
-    - Cleaned up unused constants (`DEFAULT_PLAYLIST_ID` removed from exports).
-
-### v1.0.25 (unpublished)
-
-### v1.0.24
-- **Fixes:**
-    - Fixed event tracking for vertical players with `isReels={false}`.
-    - Unified event listener setup logic - detection now based on `scriptUrl` instead of `isReels` prop.
-    - Fixed 400 Bad Request errors for horizontal player tracking by ensuring `projectId` is always included in config.
-    - Re-added `ready` and `playlistItem` event listeners for horizontal player navigation.
-- **Features:**
-    - Full metadata fetching now works for both vertical and horizontal players.
-- **Refactor:**
-    - Changed `DEFAULT_PROJECT_ID` to generic value for better reusability.
-    - Replaced `edge.vpplayer.tech` with `host.vpplayer.tech` for better performance.
-
-### v1.0.23
-- **Features:**
-    - Enhanced **vertical player analytics** with improved event tracking.
-    - Added support for passing video arrays directly via `config.video.playlist.videos`.
-- **Fixes:**
-    - Fixed duplicate event triggering in vertical player.
-    - Improved `player_start` and `player_play` event logic for `player_next`/`player_previous` actions.
-
-### v1.0.22
-- **New Features:**
-    - Added comprehensive **Analytics Event Callbacks** (`onPlayerStart`, `onPlayerPlay`, `onPlayerPause`, `onPlayerEnd`, etc.).
-    - Added **Universal `onPlayerEvent` callback** for simplified event tracking.
-    - Added support for **Vertical Player analytics** including `player_next`/`player_previous` on scroll/swipe.
-    - Added **Progress & Quartile events** (10s, 20s, 25%, 50%, 75%) with `currentPosition` data.
-- **Fixes:**
-    - Fixed `videoId` configuration issue in VP Player tracking causing 400 errors.
-    - Refined event logic to prevent duplicate events (e.g., `player_pause` during scroll/click).
-
-### v1.0.21
-- **Fixes:**
-    - Fixed vertical fullscreen video layout to rely on `aspect-ratio`.
-    - Cleaned up unused variables in Storybook examples.
-
-### v1.0.20
-- **Features:**
-    - Added full metadata API fetch for **Vertical Player** (`onVideoStarted` now returns more comprehensive data).
-
-### v1.0.19
-- **Features:**
-    - Added full metadata support for **Horizontal Player**.
-    - Introduced `onVideoStarted` callback for tracking video changes and retrieving metadata (title, author, tags, premium status, etc.).
-- **Documentation:**
-    - Updated documentation to reflect new metadata capabilities.
-
-### v1.0.18
-- **Features:**
-    - Added `onPlaylistData` callback prop to access the full playlist structure (videos, backup status, etc.).
-
-### v1.0.17
-- **Styles:**
-    - Adjusted vertical player wrapper sizing for better layout consistency.
-
-### v1.0.16
-- **Styles:**
-    - Adjusted player container border radius overrides.
-
-### v1.0.15
-- **Styles:**
-    - Removed default rounded corners and borders from VP Player to allow easier custom styling.
-
-### v1.0.14
-- **Features:**
-    - Added support for **backup playlist videos** handling.
-
-### v1.0.13
-- **Fixes:**
-    - Fixed video ID indexing issue in sliced playlists for vertical player.
-
-### v1.0.12
-- **Refactor:**
-    - Reverted to original playlist configuration logic for better stability.
-
-### v1.0.11
-- **Fixes:**
-    - Fixed logic regarding the removal of the first video from the playlist.
-
-### v1.0.10
-- **Features:**
-    - Added TypeScript interfaces for tracks and `showCaptions`.
-- **Fixes:**
-    - Fixed video indexing and thumbnail display issues in vertical player.
-
-### v1.0.9
-- **Fixes:**
-    - Ensure title and thumbnail are correctly applied to the first video in the playlist configuration.
-
-### v1.0.8
-- **Features:**
-    - Improved player configuration builder.
-- **Fixes:**
-    - Fixed playlist video index bug.
-    - Added functionality to start playlist from a specific index.
-
-### v1.0.7
-- **Fixes:**
-    - Handled timeout issues in vertical player.
-    - Resolved all linting and TypeScript errors.
-
-### v1.0.6
-- **Fixes:**
-    - Fixed TypeScript build errors.
-
-### v1.0.5
-- **Fixes:**
-    - Fixed vertical player issue on page refresh.
-    - Removed unnecessary type assertions.
-
-### v1.0.4
-- **Fixes:**
-    - Improved handling of vertical player video changes.
-
-### v1.0.0 - v1.0.3
-- **Initial Release:**
-    - Core `VPPlayer` component with support for:
-        - Single video file playback.
-        - Playlist playback (file-based and API-based).
-        - Single video API fetching.
-        - Reels/Vertical mode.
-    - Added `useVPPlayerScript` and `useVideoData` hooks with retry and caching logic.
-    - Unified error handling and configuration building.
-    - Added Storybook examples and comprehensive documentation.
+## Architecture & Best Practices
+
+This wrapper allows you to follow the "Green Field" approach—treating the player as a black box that just works.
+
+### 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`).
+
+### 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`
+
+### 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.
+
+## Custom Custom Functionality
+
+### "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).
+
+### "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.
+
+## Props Reference
+
+| 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.