@zezosoft/zezo-ott-react-native-video-player 1.0.1 → 1.0.3

package/README.md

@@ -1,20 +1,71 @@
 # 🎬 ZezoOTT Video Player
 
-The **ZezoOTT Video Player** is a powerful React Native component crafted for OTT platforms.  
-It delivers a **seamless full-screen video playback experience**, powered by a centralized **VideoPlayer Store** for state management.
+A powerful, production-ready React Native video player component designed specifically for OTT (Over-The-Top) platforms. Built with TypeScript and featuring a centralized state management system, it delivers a seamless full-screen video playback experience with comprehensive support for playlists, seasons, ads, analytics, and custom controls.
+
+---
+
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Requirements](#-requirements)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [API Reference](#-api-reference)
+  - [VideoPlayer Props](#-videoplayer-props)
+  - [VideoAd Interface](#-videoad-interface)
+- [Usage Examples](#-usage-examples)
+  - [Basic Example](#-basic-example)
+  - [Auto-Next Episodes](#-auto-next-episodes)
+  - [Custom Theming](#-custom-theming)
+  - [Playlist & Seasons](#-playlist--seasons)
+  - [Ads Player](#-ads-player)
+- [Video Player Store](#-video-player-store)
+- [Best Practices](#-best-practices)
+- [Troubleshooting](#-troubleshooting)
+- [Demo App](#-demo-app)
+- [License](#-license)
 
 ---
 
 ## ✨ Features
 
-- 📺 **Episode navigation & Seasons support**
-- 📊 **Watch progress tracking & analytics**
-- 🎨 **Custom theming**
-- 🔄 **Auto-next playback**
-- 🎬 **Playlist & seasons integration**
-- 🗄️ **Centralized store for playback state, tracks & UI**
-- 📱 **Optimized for React Native OTT apps**
-- 🛠 **Minimal configuration, production-ready**
+- 📺 **Episode Navigation & Seasons** - Seamless navigation between episodes and seasons
+- 📊 **Watch Progress Tracking** - Built-in analytics for watch time and progress
+- 🎨 **Custom Theming** - Fully customizable UI colors and metrics
+- 🔄 **Auto-Next Playback** - Automatically plays next episode/video
+- 🎬 **Playlist Integration** - Support for playlists and multi-season content
+- 📝 **Subtitles (SRT/VTT)** - Built-in subtitle support with track selection
+- 🗄️ **Centralized Store** - Zustand-powered state management for playback, tracks & UI
+- 📱 **React Native Optimized** - Built specifically for React Native OTT apps
+- 📢 **Ads Player** - Pre-roll, mid-roll, and post-roll ads with comprehensive tracking
+- 🎯 **Production Ready** - Minimal configuration, battle-tested in production
+- 🔒 **TypeScript** - Full TypeScript support with comprehensive type definitions
+
+---
+
+## 📦 Requirements
+
+### Peer Dependencies
+
+This package requires the following peer dependencies to be installed in your project:
+
+```bash
+yarn add react react-native react-native-video react-native-safe-area-context \
+  react-native-gesture-handler react-native-reanimated react-native-fast-image \
+  react-native-linear-gradient react-native-svg react-native-system-navigation-bar
+```
+
+or
+
+```bash
+npm install react react-native react-native-video react-native-safe-area-context \
+  react-native-gesture-handler react-native-reanimated react-native-fast-image \
+  react-native-linear-gradient react-native-svg react-native-system-navigation-bar
+```
+
+### Fullscreen & Orientation
+
+`react-native-orientation-locker` is included as a dependency. For fullscreen and orientation lock to work, ensure native setup is complete. See [Troubleshooting](#-troubleshooting) for details.
 
 ---
 
@@ -32,19 +83,91 @@ npm install @zezosoft/zezo-ott-react-native-video-player
 
 ---
 
-## ⚙️ VideoPlayer Props
+## 🚀 Quick Start
 
-| Prop                | Type                                                                                | Description                                                                  |
-| ------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| **onClose**         | `() => void`                                                                        | Triggered when the player is closed.                                         |
-| **isFocused**       | `boolean`                                                                           | Controls playback focus. Automatically pauses when the screen is not active. |
-| **seekTime**        | `number \| null`                                                                    | Starts playback from a given time (in seconds).                              |
-| **mode**            | `'fullscreen' \| 'normal'`                                                          | Sets the display mode of the player.                                         |
-| **onSeek**          | `(time: number) => void`                                                            | Fired when the user manually seeks to a new playback position.               |
-| **autoNext**        | `boolean`                                                                           | Automatically plays the next episode/video after completion.                 |
-| **event**           | `{ onPressEpisode?: ({ episode }: { episode: MediaEpisode }) => Promise<boolean> }` | Event hooks (e.g. custom handling for episode selection).                    |
-| **theme**           | `Partial<VideoPlayerTheme>`                                                         | Customize the look & feel of the player (colors, metrics, etc.).             |
-| **onWatchProgress** | `(progress: ExtendedWatchProgress) => void`                                         | Reports playback analytics such as watch time, current time, and completion. |
+```tsx
+import React from 'react';
+import { VideoPlayer } from '@zezosoft/zezo-ott-react-native-video-player';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+export default function VideoPlayerScreen() {
+  const insets = useSafeAreaInsets();
+
+  return (
+    <VideoPlayer
+      insets={insets}
+      isFocused={true}
+      mode="fullscreen"
+      autoNext={true}
+      onClose={() => console.log('Player closed')}
+      onWatchProgress={(progress) => {
+        console.log('Watch Progress:', progress);
+      }}
+    />
+  );
+}
+```
+
+> **Note:** Make sure you've set up the video player store with your content before rendering the player. See [Playlist & Seasons](#-playlist--seasons) section for details.
+
+---
+
+## 📚 API Reference
+
+### ⚙️ VideoPlayer Props
+
+| Prop                | Type                                                                                        | Required | Default        | Description                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------- | -------- | -------------- | -------------------------------------------------------------------------------------- |
+| **insets**          | `EdgeInsets`                                                                                | ✅ Yes   | -              | Safe area insets from `react-native-safe-area-context` (use `useSafeAreaInsets()`).    |
+| **onClose**         | `() => void`                                                                                | ❌ No    | -              | Callback triggered when the player is closed.                                          |
+| **isFocused**       | `boolean`                                                                                   | ❌ No    | `true`         | Controls playback focus. Automatically pauses when the screen is not active.           |
+| **seekTime**        | `number \| null`                                                                            | ❌ No    | `null`         | Starts playback from a given time (in seconds).                                        |
+| **mode**            | `'fullscreen' \| 'normal'`                                                                  | ❌ No    | `'fullscreen'` | Sets the display mode of the player.                                                   |
+| **autoNext**        | `boolean`                                                                                   | ❌ No    | `true`         | Automatically plays the next episode/video after completion.                           |
+| **event**           | `{ onPressEpisode?: ({ episode }: { episode: MediaEpisode }) => Promise<boolean> }`         | ❌ No    | -              | Event hooks for custom handling (e.g. episode selection, subscription checks).         |
+| **theme**           | `Partial<VideoPlayerTheme>`                                                                 | ❌ No    | -              | Customize the look & feel of the player (colors, metrics, etc.).                       |
+| **onWatchProgress** | `(progress: ExtendedWatchProgress) => void`                                                 | ❌ No    | -              | Reports playback analytics such as watch time, current time, and completion.           |
+| **ads**             | `VideoAd[]`                                                                                 | ❌ No    | `[]`           | Array of video ads to display (pre-roll, mid-roll, post-roll).                         |
+| **onAdEnd**         | `(ad: VideoAd) => void`                                                                     | ❌ No    | -              | Callback fired when an ad finishes playing.                                            |
+| **onAdError**       | `(error: Error, ad: VideoAd) => void`                                                       | ❌ No    | -              | Callback fired when an ad encounters an error.                                         |
+| **onAdTracking**    | `({ ad, trackingUrl, event }: { ad: VideoAd; trackingUrl: string; event: string }) => void` | ❌ No    | -              | Callback for ad tracking events (impression, start, quartiles, complete, skip, click). |
+
+### 📢 VideoAd Interface
+
+The `VideoAd` interface defines the structure for video advertisements:
+
+```typescript
+interface VideoAd {
+  id: string; // Unique identifier for the ad
+  title: string; // Ad title
+  description: string; // Ad description
+  position: 'pre' | 'mid' | 'post'; // Ad position: pre-roll, mid-roll, or post-roll
+  source: string; // Video source URL (MP4 or HLS)
+  duration: number; // Ad duration in seconds
+  time?: number; // For mid-roll ads: time in seconds when ad should play
+  skippable: boolean; // Whether the ad can be skipped
+  skipAfter: number; // Seconds after which skip button appears (if skippable)
+  clickThroughUrl?: string; // Optional URL to open when ad is clicked
+  tracking?: AdTracking; // Optional tracking URLs for ad events
+}
+
+interface AdTracking {
+  impression?: string; // Fired when ad is displayed
+  start?: string; // Fired when ad playback starts
+  firstQuartile?: string; // Fired at 25% of ad duration
+  midpoint?: string; // Fired at 50% of ad duration
+  thirdQuartile?: string; // Fired at 75% of ad duration
+  complete?: string; // Fired when ad completes
+  skip?: string; // Fired when ad is skipped
+  click?: string; // Fired when ad is clicked
+}
+```
+
+**Ad Position Types:**
+
+- `'pre'` - Pre-roll ad: Plays before the main video content
+- `'mid'` - Mid-roll ad: Plays during the video at the specified `time`
+- `'post'` - Post-roll ad: Plays after the main video content completes
 
 ---
 
@@ -55,10 +178,14 @@ npm install @zezosoft/zezo-ott-react-native-video-player
 ```tsx
 import React from 'react';
 import { VideoPlayer } from '@zezosoft/zezo-ott-react-native-video-player';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
 export default function App() {
+  const insets = useSafeAreaInsets();
+
   return (
     <VideoPlayer
+      insets={insets}
       isFocused={true}
       onClose={() => console.log('Player closed')}
       autoNext={true}
@@ -73,32 +200,56 @@ export default function App() {
 ### 🔄 Auto-Next Episodes
 
 ```tsx
-<VideoPlayer
-  autoNext={true}
-  event={{
-    onPressEpisode: async ({ episode }) => {
-      console.log('Next episode:', episode.title);
-      return true; // return false to block playback
-    },
-  }}
-/>
+import React from 'react';
+import { VideoPlayer } from '@zezosoft/zezo-ott-react-native-video-player';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+export default function VideoPlayerScreen() {
+  const insets = useSafeAreaInsets();
+
+  return (
+    <VideoPlayer
+      insets={insets}
+      autoNext={true}
+      event={{
+        onPressEpisode: async ({ episode }) => {
+          console.log('Next episode:', episode.title);
+          // Add your custom logic here (e.g., subscription check)
+          // return false to block playback
+          return true;
+        },
+      }}
+    />
+  );
+}
 ```
 
-### 🎨 Theming Example
+### 🎨 Custom Theming
 
 ```tsx
-<VideoPlayer
-  theme={{
-    colors: {
-      primary: '#E50914',
-      background: '#000000',
-      onBackground: '#FFFFFF',
-    },
-    metrics: {
-      controlButtonSize: 42,
-    },
-  }}
-/>
+import React from 'react';
+import { VideoPlayer } from '@zezosoft/zezo-ott-react-native-video-player';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+export default function ThemedPlayer() {
+  const insets = useSafeAreaInsets();
+
+  return (
+    <VideoPlayer
+      insets={insets}
+      theme={{
+        colors: {
+          primary: '#E50914',
+          background: '#000000',
+          onBackground: '#FFFFFF',
+        },
+        metrics: {
+          controlButtonSize: 42,
+        },
+      }}
+    />
+  );
+}
 ```
 
 ### 📺 Playlist & Seasons Setup
@@ -120,10 +271,14 @@ export default function ContentDetailsScreen({ contentData }) {
   const navigation = useNavigation();
 
   const handlePlay = () => {
+    // Always reset store before loading new content
     resetStore();
+
+    // Set seasons data
     setContentSeasons(contentData.seasons);
     setActiveSeason(contentData.seasons[0]);
 
+    // Create playlist from episodes
     const playlist = contentData.seasons[0].episodes.map((ep) => ({
       id: ep.id,
       title: ep.name,
@@ -132,10 +287,12 @@ export default function ContentDetailsScreen({ contentData }) {
       type: contentData.type,
     }));
 
+    // Set playlist and active track
     setPlayList(playlist);
     setCurrentTrackIndex(0);
     setActiveTrack(playlist[0]);
 
+    // Navigate to player screen
     navigation.navigate('VideoPlayerScreen');
   };
 
@@ -146,36 +303,123 @@ export default function ContentDetailsScreen({ contentData }) {
 ```tsx
 // VideoPlayerScreen.tsx
 import { VideoPlayer } from '@zezosoft/zezo-ott-react-native-video-player';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
 export default function VideoPlayerScreen() {
-  return <VideoPlayer isFocused={true} autoNext={true} />;
+  const insets = useSafeAreaInsets();
+
+  return <VideoPlayer insets={insets} isFocused={true} autoNext={true} />;
 }
 ```
 
----
+### 📢 Ads Player
 
-# 🗄️ Video Player Store
+```tsx
+import React from 'react';
+import {
+  VideoPlayer,
+  type VideoAd,
+} from '@zezosoft/zezo-ott-react-native-video-player';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+export default function VideoPlayerWithAds() {
+  const insets = useSafeAreaInsets();
+
+  const ads: VideoAd[] = [
+    {
+      id: 'ad1',
+      title: 'Pre-roll Ad',
+      description: 'Advertisement',
+      position: 'pre',
+      source: 'https://example.com/ad.mp4',
+      duration: 30,
+      skippable: true,
+      skipAfter: 5,
+      clickThroughUrl: 'https://example.com',
+      tracking: {
+        impression: 'https://example.com/track/impression',
+        start: 'https://example.com/track/start',
+        firstQuartile: 'https://example.com/track/firstQuartile',
+        midpoint: 'https://example.com/track/midpoint',
+        thirdQuartile: 'https://example.com/track/thirdQuartile',
+        complete: 'https://example.com/track/complete',
+        skip: 'https://example.com/track/skip',
+        click: 'https://example.com/track/click',
+      },
+    },
+    {
+      id: 'ad2',
+      title: 'Mid-roll Ad',
+      description: 'Advertisement',
+      position: 'mid',
+      source: 'https://example.com/mid-ad.mp4',
+      duration: 15,
+      time: 300, // Show at 5 minutes (300 seconds)
+      skippable: false,
+      skipAfter: 0,
+      tracking: {
+        impression: 'https://example.com/track/mid/impression',
+        complete: 'https://example.com/track/mid/complete',
+      },
+    },
+    {
+      id: 'ad3',
+      title: 'Post-roll Ad',
+      description: 'Advertisement',
+      position: 'post',
+      source: 'https://example.com/post-ad.mp4',
+      duration: 20,
+      skippable: true,
+      skipAfter: 10,
+      tracking: {
+        impression: 'https://example.com/track/post/impression',
+        complete: 'https://example.com/track/post/complete',
+      },
+    },
+  ];
 
-The **VideoPlayerStore** is a centralized state store that powers the ZezoOTT Video Player.  
-It manages **playback state, tracks, UI controls, analytics, and content navigation**.
+  return (
+    <VideoPlayer
+      insets={insets}
+      isFocused={true}
+      ads={ads}
+      onAdEnd={(ad) => {
+        console.log('Ad finished:', ad.title);
+      }}
+      onAdError={(error, ad) => {
+        console.error('Ad error:', error, ad.title);
+      }}
+      onAdTracking={({ ad, trackingUrl, event }) => {
+        console.log('Ad tracking:', event, trackingUrl);
+        // Make tracking request to your ad server
+        fetch(trackingUrl).catch(console.error);
+      }}
+      onClose={() => console.log('Player closed')}
+    />
+  );
+}
+```
 
 ---
 
-## 🚀 Store Features
+## 🗄️ Video Player Store
 
-- Manage **playback state**: current time, duration, buffering, playback rate
-- Handle **tracks**: audio, subtitles, video quality
-- Control **UI state**: controls visibility, settings modal, skip/next episode
-- Track **content structure**: playlists, seasons, active season/episode
-- Support **analytics**: watch time, view count, error handling
+The **VideoPlayerStore** is a centralized Zustand store that powers the ZezoOTT Video Player. It manages playback state, tracks, UI controls, analytics, and content navigation.
 
----
+### 🚀 Store Features
 
-## ⚡ Store Usage Example
+- **Playback State**: current time, duration, buffering, playback rate
+- **Tracks Management**: audio tracks, subtitles, video quality
+- **UI State**: controls visibility, settings modal, skip/next episode indicators
+- **Content Structure**: playlists, seasons, active season/episode
+- **Analytics**: watch time tracking, view count, error handling
+
+### ⚡ Store Usage Example
 
 ```tsx
 import { useVideoPlayerStore } from '@zezosoft/zezo-ott-react-native-video-player';
 import React from 'react';
+import { View, Pressable, Text, FlatList } from 'react-native';
 
 export default function VideoPlayerExample() {
   const {
@@ -234,61 +478,74 @@ export default function VideoPlayerExample() {
   };
 
   return (
-    <div>
-      <button onClick={setupPlayer}>Load Series</button>
-      <h3>Active Season: {activeSeason?.name}</h3>
-      <ul>
-        {playList.map((track) => (
-          <li key={track.id}>
+    <View>
+      <Pressable onPress={setupPlayer}>
+        <Text>Load Series</Text>
+      </Pressable>
+      <Text>Active Season: {activeSeason?.name}</Text>
+      <FlatList
+        data={playList}
+        keyExtractor={(track) => track.id}
+        renderItem={({ item: track }) => (
+          <Text>
             {track.title} {activeTrack?.id === track.id ? '(Playing)' : ''}
-          </li>
-        ))}
-      </ul>
-    </div>
+          </Text>
+        )}
+      />
+    </View>
   );
 }
 ```
 
 ---
 
-## 📝 Notes & Best Practices
+## 📝 Best Practices
 
-- 🔄 **Always call `resetStore()`** before loading new content.
-- 🎚️ **Playback rate** requires both `rate` and `label` in sync.
-- 🕹️ **Controls auto-hide** is managed by `controlsTimer`.
-- 🌐 **Track selections** depend on available `OnLoadData` — always null-check.
-- 📊 **Analytics props** integrate with your analytics pipeline.
-- ⚠️ **Error handling**: Use `setError` for surfacing playback issues.
-- 🎬 **Seasons & episodes**: Update both `contentSeasons` and `activeSeason` before setting playlist.
+- 🔄 **Always call `resetStore()`** before loading new content to prevent state conflicts
+- 🎚️ **Playback rate** requires both `rate` and `label` to be in sync
+- 🕹️ **Controls auto-hide** is managed by `controlsTimer` in the store
+- 🌐 **Track selections** depend on available `OnLoadData` — always null-check before using
+- 📊 **Analytics props** integrate seamlessly with your analytics pipeline
+- ⚠️ **Error handling**: Use `setError` from the store for surfacing playback issues
+- 🎬 **Seasons & episodes**: Update both `contentSeasons` and `activeSeason` before setting playlist
+- 📢 **Ads**: Ensure ad sources are valid and tracking URLs are properly configured
+- 🔒 **Type safety**: Leverage TypeScript types for better development experience
 
 ---
 
-## 📌 Fullscreen Notes
+## 🔧 Troubleshooting
 
-If fullscreen doesn’t work, ensure you install **react-native-orientation-locker**:
+### Fullscreen Not Working
 
-```bash
-yarn add react-native-orientation-locker
-# or
-npm install react-native-orientation-locker
-```
+**react-native-orientation-locker** is included in this package. If fullscreen or orientation lock doesn't work:
 
-## React Native Orientation Locker
+1. Rebuild the native app after installing the library.
+2. On Android, ensure your `AndroidManifest.xml` allows the orientations you need.
+3. If you use a custom native setup, link the library per its documentation.
 
-### 🔹 Known Issues
+#### Known Issues
 
 If you encounter any problems with react-native-orientation-locker, check the official issues page:
 [View Known Issues](https://github.com/wonday/react-native-orientation-locker/issues)
 
-### 🔹 Setup & Installation
+#### Setup & Installation
 
 Follow the official guide to properly set up react-native-orientation-locker:
 [View Setup Guide](https://github.com/wonday/react-native-orientation-locker)
 
+### Common Issues
+
+1. **Player not showing**: Ensure you've set up the store with `activeTrack` before rendering
+2. **Ads not playing**: Verify ad sources are accessible and `position` is correctly set
+3. **Controls not visible**: Check `isFocused` prop and ensure screen is active
+4. **TypeScript errors**: Make sure all peer dependencies are installed
+
 ---
 
 ## 🔗 Demo App
 
+Check out our demo app to see the player in action:
+
 👉 [Zezo OTT Demo App](https://github.com/Zezo-Soft/zezo-ott-demo-app)
 
 ---