react-native-media3-player 2.1.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # 📽️ Media3Player
 
-> A lightweight, high-performance React Native video player powered by Android Media3 (ExoPlayer). Fully customizable with support for autoplay, mute, event handling, and automatic stream type detection (DASH, HLS, MP4). This is an **Android** only package.
+> A lightweight, high-performance React Native video player powered by Android Media3 (ExoPlayer). Fully customizable with support for autoplay, mute, event handling, automatic stream type detection (DASH, HLS, MP4), and client-side ad insertion (CSAI) via Google IMA. This is an **Android** only package.
 
 ---
 
@@ -11,6 +11,7 @@
 - [Props](#props)
 - [Stream Type Detection](#stream-type-detection)
 - [DRM Support (Widevine)](#drm-support-widevine)
+- [IMA Ads Support (CSAI)](#ima-ads-support-csai)
 - [Events](#events)
 - [TypeScript Support](#typescript-support)
 - [Examples](#examples)
@@ -109,13 +110,43 @@ export default function App() {
 }
 ```
 
+**With IMA Ads (Client-Side Ad Insertion):**
+
+```jsx
+import React from 'react';
+import {View} from 'react-native';
+import Media3Player from 'react-native-media3-player';
+
+export default function App() {
+  return (
+    <View style={{flex: 1}}>
+      <Media3Player
+        style={{width: '100%', height: 250}}
+        source={{
+          uri: 'https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
+          ads: {
+            adTagUrl:
+              'https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/vmap_ad_samples&sz=640x480&cust_params=sample_ar%3Dpreonly&ciu_szs=300x250%2C728x90&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&env=vp&correlator=',
+          },
+        }}
+        autoplay={true}
+        play={true}
+        onReady={() => console.log('Player is ready')}
+        onEnd={() => console.log('Video ended')}
+        onError={error => console.log('Player error:', error.message)}
+      />
+    </View>
+  );
+}
+```
+
 ---
 
 ## Props
 
 | Prop       | Type                         | Default                          | Description                                                              |
 | ---------- | ---------------------------- | -------------------------------- | ------------------------------------------------------------------------ |
-| `source`   | `Source`                     | required                         | Video source object. Must include a valid `uri`. Supports optional `drm` config. |
+| `source`   | `Source`                     | required                         | Video source object. Must include a valid `uri`. Supports optional `drm` and `ads` config. |
 | `autoplay` | `boolean`                    | `false`                          | Automatically start playback when the video is ready.                    |
 | `play`     | `boolean`                    | `false`                          | Controls whether the player is playing. Overrides autoplay.              |
 | `mute`     | `boolean`                    | `false`                          | Mutes or unmutes the video.                                              |
@@ -128,6 +159,7 @@ export default function App() {
 | `uri`    | `string`                     | Yes      | The URI of the media to play (MP4, DASH, HLS, etc.).                                                         |
 | `type`   | `'dash' \| 'hls' \| 'mp4'`  | No       | Explicitly set the stream type. Defaults to `'mp4'`. If omitted, the player auto-detects the type from the URI. |
 | `drm`    | `DRMConfig`                  | No       | DRM configuration for protected content.                                                                     |
+| `ads`    | `AdsConfig`                  | No       | IMA ads configuration for client-side ad insertion.                                                           |
 
 ### `DRMConfig` Object
 
@@ -136,6 +168,12 @@ export default function App() {
 | `licenseUrl` | `string`                          | Yes      | The Widevine license server URL.                      |
 | `headers`    | `Array<{ key: string, value: string }>` | No       | Custom headers to include in the DRM license request. |
 
+### `AdsConfig` Object
+
+| Property   | Type     | Required | Description                                                       |
+| ---------- | -------- | -------- | ----------------------------------------------------------------- |
+| `adTagUrl` | `string` | Yes      | The VAST/VMAP ad tag URL for client-side ad insertion via IMA SDK. |
+
 ---
 
 ## Stream Type Detection
@@ -233,6 +271,58 @@ Some license servers require authentication tokens or custom headers. Pass them
 
 ---
 
+## IMA Ads Support (CSAI)
+
+This library supports **Client-Side Ad Insertion (CSAI)** using the [Google IMA SDK](https://developers.google.com/interactive-media-ads) integrated via Media3's IMA extension. To enable ads, pass an `ads` object inside the `source` prop with a VAST or VMAP ad tag URL.
+
+### Basic Ad Playback
+
+```jsx
+<Media3Player
+  source={{
+    uri: 'https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
+    ads: {
+      adTagUrl:
+        'https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/vmap_ad_samples&sz=640x480&cust_params=sample_ar%3Dpreonly&ciu_szs=300x250%2C728x90&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&env=vp&correlator=',
+    },
+  }}
+  autoplay
+  play
+/>
+```
+
+### Ads with DRM Content
+
+You can combine ads with DRM-protected streams:
+
+```jsx
+<Media3Player
+  source={{
+    uri: 'https://storage.googleapis.com/shaka-demo-assets/angel-one-widevine/dash.mpd',
+    type: 'dash',
+    drm: {
+      licenseUrl: 'https://cwip-shaka-proxy.appspot.com/no_auth',
+    },
+    ads: {
+      adTagUrl: 'https://your-ad-server.com/vmap-tag',
+    },
+  }}
+  autoplay
+  play
+  onError={e => console.error('Error:', e.message)}
+/>
+```
+
+### Notes
+
+- Ads are supported on **Android only**.
+- The `adTagUrl` should point to a valid VAST or VMAP XML endpoint.
+- Both pre-roll and mid-roll ad configurations are supported via VMAP.
+- The IMA ads loader is automatically initialized and released as needed when the ad tag URL changes.
+- Ads play inline within the same `PlayerView` used for content playback.
+
+---
+
 ## Events
 
 | Event     | Callback Signature                     | Description                                                                            |
@@ -285,6 +375,23 @@ const drmProps: Media3PlayerProps = {
 };
 ```
 
+**With IMA Ads:**
+
+```ts
+const adsProps: Media3PlayerProps = {
+  source: {
+    uri: 'https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
+    ads: {
+      adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?...',
+    },
+  },
+  autoplay: true,
+  play: true,
+  style: {width: '100%', height: 250},
+  onError: err => console.log('Ad Error:', err.message),
+};
+```
+
 ---
 
 ## Examples
@@ -371,6 +478,41 @@ const drmProps: Media3PlayerProps = {
 />
 ```
 
+**With IMA Ads (VMAP):**
+
+```jsx
+<Media3Player
+  source={{
+    uri: 'https://example.com/video.mp4',
+    ads: {
+      adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?...',
+    },
+  }}
+  autoplay
+  play
+/>
+```
+
+**Ads with DRM Stream:**
+
+```jsx
+<Media3Player
+  source={{
+    uri: 'https://example.com/protected/manifest.mpd',
+    type: 'dash',
+    drm: {
+      licenseUrl: 'https://license.example.com/widevine',
+    },
+    ads: {
+      adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?...',
+    },
+  }}
+  autoplay
+  play
+  onError={err => console.error('Error:', err.message)}
+/>
+```
+
 ---
 
 ## Contributing

package/android/build.gradle

@@ -65,4 +65,10 @@ dependencies {
 
     // Android core utilities and extensions (KTX)
     implementation "androidx.core:core-ktx:1.13.1"
+
+    // IMA Ads support for Media3
+    implementation "androidx.media3:media3-exoplayer-ima:$media3Version"
+
+    // Google IMA SDK
+    implementation "com.google.ads.interactivemedia.v3:interactivemedia:3.33.0"
 }

package/android/src/main/java/com/rnmedia3playerdemo/Media3PlayerView.kt

@@ -22,6 +22,9 @@ import androidx.media3.exoplayer.source.ProgressiveMediaSource
 import androidx.media3.exoplayer.dash.DashMediaSource
 import androidx.media3.exoplayer.hls.HlsMediaSource
 import androidx.media3.exoplayer.smoothstreaming.SsMediaSource
+import androidx.media3.exoplayer.ima.ImaAdsLoader
+import androidx.media3.exoplayer.source.ads.AdsMediaSource
+import androidx.media3.exoplayer.source.DefaultMediaSourceFactory
 
 /**
  * Custom view that wraps ExoPlayer and PlayerView, integrating with React Native.
@@ -39,6 +42,10 @@ class Media3PlayerView(context: Context) : FrameLayout(context) {
     private var play: Boolean = false
     // Mute state controlled by the JS prop
     private var mute: Boolean = false
+    // IMA Ads loader
+    private var adsLoader: ImaAdsLoader? = null
+    // Currently loaded ad tag URL
+    private var currentAdTagUrl: String? = null
 
     /**
      * Constructor: initialize the PlayerView and attach it to the layout.
@@ -52,6 +59,21 @@ class Media3PlayerView(context: Context) : FrameLayout(context) {
         addView(playerView)
     }
 
+    /**
+     * Initializes the IMA Ads loader and sets it to the player.
+     * @param adTagUrl The URL of the ad tag to load.
+     */
+    private fun initializeAdsLoader(adTagUrl: String) {
+        if (adsLoader == null || currentAdTagUrl != adTagUrl) {
+            adsLoader?.release()
+
+            adsLoader = ImaAdsLoader.Builder(context).build()
+            currentAdTagUrl = adTagUrl
+
+            adsLoader?.setPlayer(exoPlayer)
+        }
+    }
+
     /**
      * Initializes ExoPlayer and attaches a listener for player events.
      * Ensures only one instance exists.
@@ -61,6 +83,9 @@ class Media3PlayerView(context: Context) : FrameLayout(context) {
             exoPlayer = ExoPlayer.Builder(context).build()
             playerView.player = exoPlayer
 
+            // Set the IMA Ads loader to the player
+            adsLoader?.setPlayer(exoPlayer)
+
             // Listen for playback state changes and errors
             exoPlayer?.addListener(object : Player.Listener {
                 override fun onPlaybackStateChanged(state: Int) {
@@ -219,7 +244,8 @@ class Media3PlayerView(context: Context) : FrameLayout(context) {
         uriString: String?,
         type: String?,
         licenseUrl: String?,
-        headers: Map<String, String>?
+        headers: Map<String, String>?,
+        adTagUrl: String?
     ) {
         // Return early if no valid URI is provided
         if (uriString.isNullOrEmpty()) return
@@ -227,6 +253,15 @@ class Media3PlayerView(context: Context) : FrameLayout(context) {
         // Store the URI string for reference
         sourceUri = uriString
 
+        
+        // Release and reset the adsLoader if the ad tag URL has changed -
+        // to prevent playing old ads or memory leaks.
+        if (currentAdTagUrl != adTagUrl) {
+            adsLoader?.setPlayer(null)
+            adsLoader?.release()
+            adsLoader = null
+        }
+
         // Ensure the ExoPlayer instance is initialized before use
         initializePlayer()
 
@@ -255,10 +290,33 @@ class Media3PlayerView(context: Context) : FrameLayout(context) {
                 MediaItem.fromUri(uri)
             }
 
-        // Build the appropriate MediaSource (handles progressive, DASH/HLS/SmoothStreaming)
-        // and assign it to ExoPlayer. Prepare ExoPlayer for playback.
-        val mediaSource = buildMediaSource(uri, mediaItem, type)
-        exoPlayer?.setMediaSource(mediaSource)
+        // If an ad tag URL is provided, configure the player for ad playback using IMA:
+        // - Initialize the AdsLoader (only if not already done for the current ad tag)
+        // - Build a MediaItem that includes the ads configuration
+        // - Create a DefaultMediaSourceFactory with ads and ad view providers
+        // - Set the media source with ads on the player
+        if (!adTagUrl.isNullOrEmpty()) {
+            initializeAdsLoader(adTagUrl)
+
+            val mediaItemWithAds = mediaItem.buildUpon()
+                .setAdsConfiguration(
+                    MediaItem.AdsConfiguration.Builder(Uri.parse(adTagUrl)).build()
+                )
+                .build()
+
+            val mediaSourceFactory = DefaultMediaSourceFactory(DefaultHttpDataSource.Factory())
+                .setAdsLoaderProvider { adsLoader }
+                .setAdViewProvider(playerView)
+
+            exoPlayer?.setMediaSource(
+                mediaSourceFactory.createMediaSource(mediaItemWithAds)
+            )
+        } else {
+            // If no ad tag URL, simply build and set the normal content media source
+            val mediaSource = buildMediaSource(uri, mediaItem, type)
+            exoPlayer?.setMediaSource(mediaSource)
+        }
+        // Prepare the player for playback (loads media and notifies listeners)
         exoPlayer?.prepare()
     }
 
@@ -300,10 +358,25 @@ class Media3PlayerView(context: Context) : FrameLayout(context) {
      * This should be called when the view is destroyed.
      */
     fun releasePlayer() {
+        // Release the IMA Ads loader
+        adsLoader?.setPlayer(null)
+        adsLoader?.release()
+        adsLoader = null
+
+        // Release the ExoPlayer
         exoPlayer?.release()
         exoPlayer = null
     }
 
+    /**
+     * Called when the view is detached from the window.
+     * Releases the player and cleans up resources.
+     */
+    override fun onDetachedFromWindow() {
+        super.onDetachedFromWindow()
+        releasePlayer()
+    }
+
     /**
      * Helper function to send events and optional data payloads to React Native JS side.
      * @param eventName Name of the event (e.g., "topReady", "topError")

package/android/src/main/java/com/rnmedia3playerdemo/Media3PlayerViewManager.kt

@@ -57,6 +57,10 @@ class Media3PlayerViewManager :
         var headers: Map<String, String>? = null
         val drmMap = source?.getMap("drm")
 
+        // Extract the IMA Ads configuration from the source map.
+        val adsMap = source?.getMap("ads")
+        val adTagUrl = adsMap?.getString("adTagUrl")
+
         if (drmMap != null) {
             licenseUrl = drmMap.getString("licenseUrl")
             val headersArray = drmMap.getArray("headers")
@@ -74,7 +78,7 @@ class Media3PlayerViewManager :
             }
         }
         if (!uri.isNullOrEmpty()) {
-            view.setSource(uri, type, licenseUrl, headers)
+            view.setSource(uri, type, licenseUrl, headers, adTagUrl)
         }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-media3-player",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "React Native Media3 Player component for Android (ExoPlayer 3 integration).",
   "main": "index.js",
   "react-native": "index.js",

package/src/Media3PlayerNativeComponent.ts

@@ -1,7 +1,10 @@
 // Import the base ViewProps type from React Native to extend the native component's props
 import type {ViewProps} from 'react-native';
 // Import the DirectEventHandler type used for native-to-JS event callback typings
-import type {DirectEventHandler, WithDefault} from 'react-native/Libraries/Types/CodegenTypes';
+import type {
+  DirectEventHandler,
+  WithDefault,
+} from 'react-native/Libraries/Types/CodegenTypes';
 // Import codegenNativeComponent to register the native UI component for use in React Native
 import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
 
@@ -14,13 +17,20 @@ type DRMConfig = Readonly<{
   licenseUrl: string;
   headers?: ReadonlyArray<HeaderEntry>;
 }>;
+
+type AdsConfig = Readonly<{
+  adTagUrl: string;
+}>;
+
 // Source defines the media source for the player component.
 // - uri: The URI of the media to be played (required).
 // - drm: (Optional) DRM configuration for protected content.
+// - ads: (Optional) IMA Ads configuration for ad playback.
 type Source = Readonly<{
   uri: string;
   type?: WithDefault<'dash' | 'hls' | 'mp4', 'mp4'>;
   drm?: DRMConfig;
+  ads?: AdsConfig;
 }>;
 // Event type emitted when the player is ready
 type OnReadyEvent = Readonly<{}>;