@devix-technologies/react-gjirafa-vp-player 1.0.18 → 1.0.19

package/README.md

@@ -85,6 +85,8 @@ interface VPPlayerProps {
   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
 }
 ```
 
@@ -148,6 +150,116 @@ interface VPPlayerProps {
 
 - 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
+<VPPlayer
+  playerId="player"
+  projectId="agmipnzb"
+  playlistId="lzxikgjw"
+  apiKey="YOUR_API_KEY"
+  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
+  }}
+/>
+```
+
+### **onVideoStarted?: (videoData: CurrentVideoData) => void**
+
+- 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
+<VPPlayer
+  playerId="vertical-player"
+  projectId="agmipnzb"
+  playlistId="lzxikgjw"
+  scriptUrl="https://host.vpplayer.tech/vertical-player/rbqcdwznd.js"
+  isReels={true}
+  apiKey="YOUR_API_KEY"
+  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"
+  projectId="agmipnzb"
+  videoId="vjsnuhvm"
+  scriptUrl="https://host.vpplayer.tech/player/ptkzurnx.js"
+  apiKey="YOUR_API_KEY"
+  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.
@@ -298,6 +410,165 @@ const MyComponent = () => (
 }
 ```
 
+## 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"
+        apiKey="YOUR_API_KEY"
+        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}
+  apiKey="YOUR_API_KEY"
+  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"
+  apiKey="YOUR_API_KEY"
+  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"
+        apiKey="YOUR_API_KEY"
+        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>
+  );
+};
+```
 <!-- Release notes WIP -->
 <!-- v. 1.0.0 -->
 <!-- Single video file, Playlist with files, Single Api video, Playlist Api-->