@devix-technologies/react-gjirafa-vp-player 1.0.22 → 1.0.23

package/README.md

@@ -6,7 +6,41 @@ It supports multiple ways to configure and play videos, including single files,
 
 ## Overview
 
-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.
+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.
+
+## Installation
+
+To install the package, run:
+
+```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
+```
+
+## 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";
+
+const App = () => {
+  return (
+    <div style={{ maxWidth: "800px", margin: "0 auto" }}>
+      <VPPlayer
+        playerId="my-unique-player-id"
+        videoUrl="https://example.com/video.mp4"
+        version="latest"
+      />
+    </div>
+  );
+};
+
+export default App;
+```
 
 ## Source Files Structure
 
@@ -41,6 +75,7 @@ The `VPPlayer` component dynamically loads the VP Player script (`vpplayer.js`)
 │   │   ├── playlist.ts
 │   ├── hooks/
 │   │   ├── index.ts
+│   │   ├── useVPPlayerEvents.ts
 │   │   ├── useVPPlayerLogic.ts
 │   │   ├── useVPPlayerScript.ts
 │   │   ├── useVideoData.ts
@@ -52,6 +87,7 @@ The `VPPlayer` component dynamically loads the VP Player script (`vpplayer.js`)
 │   │   ├── styles.ts
 │   ├── types/
 │   │   ├── api.types.ts
+│   │   ├── playerEvents.types.ts
 │   │   ├── index.ts
 │   ├── utils/
 │   │   ├── index.ts
@@ -87,6 +123,21 @@ interface VPPlayerProps {
   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
 }
 ```
 
@@ -209,7 +260,7 @@ interface VPPlayerProps {
       - `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
@@ -569,7 +620,158 @@ const AdvancedPlayerComponent = () => {
   );
 };
 ```
-<!-- Release notes WIP -->
-<!-- v. 1.0.0 -->
-<!-- Single video file, Playlist with files, Single Api video, Playlist Api-->
-<!--  -->
+
+### 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.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.