docs: update documentation

Author: KrzysztofMoch

docs/pages/other/plugin.md

@@ -25,28 +25,34 @@ First you need to create a new react native package:
 npx create-react-native-library@latest react-native-video-custom-analytics
 ```
 
-Both android and iOS implementation expose an interface `RNVPlugin`.
-Your `react-native-video-custom-analytics` shall implement this interface and register itself as a plugin for react native video.
+Both Android and iOS implementations expose two interfaces:
+- `RNVPlugin`: Base interface for all RNV plugins that doesn't have dependencies nor logic specific to any player
+- Player-specific interfaces: `RNVExoplayerPlugin` (Android) and `RNVAVPlayerPlugin` (iOS) for plugins that need direct access to the specific player implementations
+
+Your `react-native-video-custom-analytics` shall implement one of these interfaces and register itself as a plugin for react native video.
 
 ## Android
-There is no special requierement for gradle file.
-You need two mandatory action to be able to receive player handle
+
+There is no special requirement for gradle file.
+You need two mandatory actions to be able to receive player handle.
 
 ### 1/ Create the plugin
 
-First you should instanciate a class which extends `RNVPlugin`.
+You have two options for implementing a plugin on Android:
 
-The proposed integration implement `RNVPlugin` directly inside the Module file (`VideoPluginSampleModule`).
+#### Option 1: Basic Plugin (RNVPlugin)
 
-The `RNVPlugin` interface defines following functions, see description here under.
+For plugins that don't need Exoplayer-specific functionality, implement the `RNVPlugin` interface:
 
 ```kotlin
+interface RNVPlugin {
     /**
      * Function called when a new player is created
      * @param id: a random string identifying the player
      * @param player: the instantiated player reference
      */
     fun onInstanceCreated(id: String, player: Any)
+
     /**
      * Function called when a player should be destroyed
      * when this callback is called, the plugin shall free all
@@ -55,79 +61,136 @@ The `RNVPlugin` interface defines following functions, see description here unde
      * @param player: the player to release
      */
     fun onInstanceRemoved(id: String, player: Any)
-    
+}
+```
+
+#### Option 2: Exoplayer-specific Plugin (RNVExoplayerPlugin)
+
+For plugins that need direct access to Exoplayer functionality, implement the `RNVExoplayerPlugin` interface:
+
+```kotlin
+interface RNVExoplayerPlugin : RNVPlugin {
     /**
      * Optional function that allows plugin to provide custom DRM manager
      * Only one plugin can provide DRM manager at a time
      * @return DRMManagerSpec implementation if plugin wants to handle DRM, null otherwise
      */
-    fun getDRMManager(): DRMManagerSpec? {
-        return null
-    }
+    fun getDRMManager(): DRMManagerSpec? = null
+
+    /**
+     * Function called when a new player is created
+     * @param id: a random string identifying the player
+     * @param player: the instantiated player reference
+     * @note: This is helper that ensure that player is non null ExoPlayer
+     */
+    fun onInstanceCreated(id: String, player: ExoPlayer)
+
+    /**
+     * Function called when a player should be destroyed
+     * when this callback is called, the plugin shall free all
+     * resources and release all reference to Player object
+     * @param id: a random string identifying the player
+     * @param player: the player to release
+     * @note: This is helper that ensure that player is non null ExoPlayer
+     */
+    fun onInstanceRemoved(id: String, player: ExoPlayer)
+}
 ```
 
-### 2/ register the plugin
+The `RNVExoplayerPlugin` interface already implements the base `RNVPlugin` methods by providing type-safe wrappers that ensure you receive an ExoPlayer instance.
 
-To register this allocated class in the main react native video package you should call following function:
+### 2/ Register the plugin
+
+To register your plugin with the main react native video package, call the following function:
 
 ```kotlin
 ReactNativeVideoManager.getInstance().registerPlugin(plugin)
 ```
-The proposed integration register the instanciated class in `createNativeModules` entry point.
+
+The proposed integration registers the instantiated class in the `createNativeModules` entry point.
 
 Your native module can now track Player updates directly from Player reference and report to backend.
 
 ## iOS
 
 ### 1/ podspec integration
 
-Your new module shall be able to access to react-native-video package, then we must declare it as a dependency of the new module you are creating.
+Your new module should be able to access the react-native-video package, so you must declare it as a dependency of the new module you are creating.
 
 ```podfile
   s.dependency "react-native-video"
 ```
 
 ### 2/ Create the plugin
 
-First you should instanciate a class which extends `RNVPlugin`.
+You have two options for implementing a plugin on iOS:
 
-The proposed integration implement `RNVPlugin` directly inside the entry point of the module file (`VideoPluginSample`).
+#### Option 1: Basic Plugin (RNVPlugin)
 
-The `RNVPlugin` interface defines following functions, see description here under.
+For plugins that don't need AVPlayer-specific functionality, extend the `RNVPlugin` class:
 
 ```swift
+open class RNVPlugin: NSObject {
     /**
      * Function called when a new player is created
      * @param id: a random string identifying the player
      * @param player: the instantiated player reference
      */
-    func onInstanceCreated(id: String, player: Any)
+    open func onInstanceCreated(id: String, player: Any) { /* no-op */ }
+    
     /**
      * Function called when a player should be destroyed
      * when this callback is called, the plugin shall free all
      * resources and release all reference to Player object
      * @param id: a random string identifying the player
      * @param player: the player to release
      */
-    func onInstanceRemoved(id: String, player: Any)
-    
+    open func onInstanceRemoved(id: String, player: Any) { /* no-op */ }
+}
+```
+
+#### Option 2: AVPlayer-specific Plugin (RNVAVPlayerPlugin)
+
+For plugins that need direct access to AVPlayer functionality, extend the `RNVAVPlayerPlugin` class:
+
+```swift
+open class RNVAVPlayerPlugin: RNVPlugin {
     /**
      * Optional function that allows plugin to provide custom DRM manager
      * Only one plugin can provide DRM manager at a time
      * @return: DRMManagerSpec type if plugin wants to handle DRM, nil otherwise
      */
-    func getDRMManager() -> DRMManagerSpec.Type?
+    open func getDRMManager() -> DRMManagerSpec? { nil }
+    
+    /**
+     * Function called when a new AVPlayer instance is created
+     * @param id: a random string identifying the player
+     * @param player: the instantiated AVPlayer
+     * @note: This is helper that ensure that player is non null AVPlayer
+     */
+    open func onInstanceCreated(id: String, player: AVPlayer) { /* no-op */ }
+    
+    /**
+     * Function called when a AVPlayer instance is being removed
+     * @param id: a random string identifying the player
+     * @param player: the AVPlayer to release
+     * @note: This is helper that ensure that player is non null AVPlayer
+     */
+    open func onInstanceRemoved(id: String, player: AVPlayer) { /* no-op */ }
+}
 ```
 
+The `RNVAVPlayerPlugin` class already extends from the base `RNVPlugin` class and provides type-safe wrappers that ensure you receive an AVPlayer instance.
+
 ### 3/ Register the plugin
 
-To register this allocated class in the main react native video package you should register it by calling this function:
+To register your plugin with the main react native video package, call this function:
 
 ```swift
 ReactNativeVideoManager.shared.registerPlugin(plugin: plugin)
 ```
 
-The proposed integration register the instanciated class in file `VideoPluginSample` in the init function:
+The proposed integration registers the instantiated class in file `VideoPluginSample` in the init function:
 
 ```swift
 import react_native_video
@@ -168,14 +231,20 @@ class CustomDRMManager : DRMManagerSpec {
 Implement `getDRMManager()` in your plugin to provide the custom DRM manager:
 
 ```kotlin
-class CustomVideoPlugin : RNVPlugin {
+class CustomVideoPlugin : RNVExoplayerPlugin {
     private val drmManager = CustomDRMManager()
 
     override fun getDRMManager(): DRMManagerSpec? {
         return drmManager
     }
 
-    // ... other RNVPlugin methods ...
+    override fun onInstanceCreated(id: String, player: ExoPlayer) {
+        // Handle player creation
+    }
+    
+    override fun onInstanceRemoved(id: String, player: ExoPlayer) {
+        // Handle player removal
+    }
 }
 ```
 
@@ -224,12 +293,18 @@ class CustomDRMManager: NSObject, DRMManagerSpec {
 Implement `getDRMManager()` in your plugin to provide the custom DRM manager:
 
 ```swift
-class CustomVideoPlugin: RNVPlugin {
-    func getDRMManager() -> DRMManagerSpec.Type? {
+class CustomVideoPlugin: RNVAVPlayerPlugin {
+    override func getDRMManager() -> DRMManagerSpec? {
         return CustomDRMManager.self
     }
 
-    // ... other RNVPlugin methods ...
+    override func onInstanceCreated(id: String, player: AVPlayer) {
+        // Handle player creation
+    }
+    
+    override func onInstanceRemoved(id: String, player: AVPlayer) {
+        // Handle player removal
+    }
 }
 ```