@jwplayer/jwplayer-react-native 1.2.0 → 1.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![Version](/badges/version.svg)](https://github.com/jwplayer/jwplayer-react-native) [![NPM version](https://img.shields.io/npm/v/%40jwplayer%2Fjwplayer-react-native)](https://www.npmjs.com/package/@jwplayer/jwplayer-react-native) [![License](/badges/license.svg)](/LICENSE)
 
-⚠️ This **README** is for `jwplayer-react-native` version `1.0.0` and higher, for previous versions from the original author, [Chaim Paneth](https://github.com/chaimPaneth) via [Orthodox Union](https://www.ou.org/), see [react-native-jw-media-player](https://github.com/chaimPaneth/react-native-jw-media-player). Beginning with version `0.2.0`, this library uses [JWP's `JWPlayerKit ` (iOS)]((https://developer.jwplayer.com/jwplayer/docs/ios-get-started)) and [SDK 4 (Android)]((https://developer.jwplayer.com/jwplayer/docs/android-get-started)).
+⚠️ This **README** is for `jwplayer-react-native` version `1.0.0` and higher, for previous versions from the original author, [Chaim Paneth](https://github.com/chaimPaneth) via [Orthodox Union](https://www.ou.org/), see [react-native-jw-media-player](https://github.com/chaimPaneth/react-native-jw-media-player). Beginning with version `0.2.0`, this library uses [JWX's `JWPlayerKit ` (iOS)]((https://developer.jwplayer.com/jwplayer/docs/ios-get-started)) and [SDK 4 (Android)]((https://developer.jwplayer.com/jwplayer/docs/android-get-started)).
 
 <br />
 
@@ -10,7 +10,7 @@
 
 <br />
 
-The `jwplayer-react-native` library is a bridge that enables using the native JWP Android and iOS SDKs in React Native applications.
+The `jwplayer-react-native` library is a bridge that enables using the native JWX Android and iOS SDKs in React Native applications.
 
 <img width="200" alt="sample" src="./images/1.png"> <img width="200" alt="sample" src="./images/2.png"> <img width="200" alt="sample" src="./images/3.png">
 
@@ -19,8 +19,8 @@ The `jwplayer-react-native` library is a bridge that enables using the native JW
 ## Prerequisites
 
 Before installing and using the library, you need the following items:
-- JWP [Account](https://jwplayer.com/pricing/)
-- JWP License Key ([Android](https://docs.jwplayer.com/players/docs/android-overview#requirements) | [iOS](https://docs.jwplayer.com/players/docs/ios-overview#requirements))
+- JWX [Account](https://jwplayer.com/pricing/)
+- JWX License Key ([Android](https://docs.jwplayer.com/players/docs/android-overview#requirements) | [iOS](https://docs.jwplayer.com/players/docs/ios-overview#requirements))
 - [React Native App](https://reactnative.dev/docs/getting-started)
 - Package Manager ([npm](https://nodejs.org/en/download) | [yarn](https://yarnpkg.com/getting-started/install) )
 
@@ -38,7 +38,7 @@ Follow these steps to add the library to your Android project:
 
    yarn: `yarn add @jwplayer/jwplayer-react-native`
 
-2. In **android/build.gradle**, add the JWP Maven repository inside the `allprojects` block.
+2. In **android/build.gradle**, add the JWX Maven repository inside the `allprojects` block.
 
    ```groovy
    allprojects {
@@ -49,7 +49,7 @@ Follow these steps to add the library to your Android project:
            }
    ```
 
-For more details and guidance regarding configuration and requirements, see the [JWP Android SDK documentation](https://docs.jwplayer.com/players/docs/android-overview#requirements).
+For more details and guidance regarding configuration and requirements, see the [JWX Android SDK documentation](https://docs.jwplayer.com/players/docs/android-overview#requirements).
 
 <br />
 
@@ -72,13 +72,13 @@ Follow these steps to add the library to your iOS project:
    pod install
    ```
 
-For more details and guidance regarding configuration and requirements, see the [JWP iOS SDK documentation](https://docs.jwplayer.com/players/docs/ios-overview#requirements).
+For more details and guidance regarding configuration and requirements, see the [JWX iOS SDK documentation](https://docs.jwplayer.com/players/docs/ios-overview#requirements).
 
 <br /><br />
 
 ## Usage
 
-The following example shows how you can enhance your React Native application by seamlessly integrating the multimedia playback functionalities of the JWP mobile SDKs.
+The following example shows how you can enhance your React Native application by seamlessly integrating the multimedia playback functionalities of the JWX mobile SDKs.
 
 Follow these steps to configure the media playback experience in your app:
 
@@ -190,7 +190,7 @@ Follow these steps to configure the media playback experience in your app:
   ```
 
 
-2. Define `config.license` with your Android or iOS JWP license key.
+2. Define `config.license` with your Android or iOS JWX license key.
 3. Define `config.playlist` with the media to play in the player.
 4. (Optional) Define the other values of the `config` prop.
 
@@ -222,7 +222,7 @@ Follow these steps to run the example project:
    pod install
    ```
 4. In Xcode,open **RNJWPlayer.xcworkspace**.
-5. In **App.js**, within the `config` prop, add your JWP SDK license key.
+5. In **App.js**, within the `config` prop, add your JWX SDK license key.
 6. Build and run the app for your preferred platform.
    ```
    yarn android
@@ -240,6 +240,68 @@ Follow these steps to run the example project:
 
 <br /><br />
 
+## Configuration
+
+The library now features a **unified configuration system** that provides consistent, type-safe configuration across both iOS and Android platforms.
+
+### 📚 Documentation
+
+- **[Configuration Reference](./docs/CONFIG-REFERENCE.md)** - Complete guide to all configuration options with examples
+- **[Platform Differences](./docs/PLATFORM-DIFFERENCES.md)** - Detailed comparison of iOS vs Android features
+- **[Migration Guide](./docs/MIGRATION-GUIDE.md)** - Guide for upgrading to the unified type system
+- **[Props Documentation](./docs/props.md)** - Component props reference
+
+### Quick Example
+
+```typescript
+import JWPlayer, { JWPlayerConfig } from '@jwplayer/jwplayer-react-native';
+
+const config: JWPlayerConfig = {
+  license: 'YOUR_LICENSE_KEY',
+  file: 'https://example.com/video.m3u8',
+  autostart: true,
+  advertising: {
+    client: 'dai',
+    imaDaiSettings: {
+      videoId: 'tears-of-steel',
+      cmsId: '2528370'
+    }
+  }
+};
+
+export default () => (
+  <JWPlayer config={config} style={{ flex: 1 }} />
+);
+```
+
+### Configuration Modes
+
+The library supports two configuration modes:
+
+1. **Modern Configuration (Recommended)**
+   - Uses the unified type system (`JWPlayerConfig`)
+   - Provides full type safety and IDE support
+   - Matches JW Player Delivery API format
+   - Clearly documents platform-specific features
+   - Example: See [TypeScript Example](./Example/app/jsx/screens/TypeScriptExample.tsx)
+
+2. **Legacy Configuration**
+   - Set `forceLegacyConfig={true}` in props
+   - Uses older builder patterns from previous versions
+   - Limited type safety and platform support
+   - Not recommended for new implementations
+   - Documentation: See [Legacy Readme](./docs/legacy_readme.md)
+
+### Key Features
+
+- ✅ **Type Safety**: Full TypeScript support with autocomplete
+- ✅ **Cross-Platform**: Single configuration works on both iOS and Android
+- ✅ **Platform Annotations**: Clear documentation of platform-specific features
+- ✅ **Backward Compatible**: Existing configurations continue to work
+- ✅ **Well Documented**: Comprehensive guides for all features
+
+<br /><br />
+
 ## Advanced Topics
 
 [Advertising](#advertising) | [Background Audio](#background-audio) | [Casting](#casting) | [DRM](#drm) | [Picture in Picture (PiP)](#picture-in-picture-pip) | [Styling](#styling)
@@ -252,9 +314,40 @@ Follow these steps to run the example project:
 
 #### Android Advertising
 
-Follow this step to set up advertising with IMA or DAI:
+Follow these steps to set up advertising with IMA or DAI:
+
+1. In the **android/build.gradle** `ext{}` block, add `RNJWPlayerUseGoogleIMA = true`. 
+   
+   ```groovy
+   buildscript {
+       ext {
+           RNJWPlayerUseGoogleIMA = true
+       }
+   }
+   ```
+   
+   This setting will add the following dependencies: `com.google.ads.interactivemedia.v3:interactivemedia:3.36.0` and `com.google.android.gms:play-services-ads-identifier:18.0.1`.
+
+2. **⚠️ REQUIRED: Enable desugaring in your app** (required for IMA SDK 3.37.0+):
+
+   In your **android/app/build.gradle**, add the following configuration:
+
+   ```groovy
+   android {
+       compileOptions {
+           sourceCompatibility JavaVersion.VERSION_1_8
+           targetCompatibility JavaVersion.VERSION_1_8
+           coreLibraryDesugaringEnabled true
+       }
+   }
+
+   dependencies {
+       // ... your other dependencies
+       coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'
+   }
+   ```
 
-1. In the **app/build.gradle** `ext{}`, add `RNJWPlayerUseGoogleIMA = true`. This setting will add the following dependencies: `com.google.ads.interactivemedia.v3:interactivemedia:3.31.0` and `com.google.android.gms:play-services-ads-identifier:18.0.1`.
+> **Important**: The IMA SDK 3.37.0+ requires desugaring due to its transitive dependencies. While the `jwplayer-react-native` library configures desugaring internally, **Android requires that your consuming app also explicitly enable desugaring**. If you skip step 2, you will get build errors like "Dependency requires core library desugaring to be enabled". This is an Android Gradle requirement where both the library and the consuming app must opt-in to desugaring.
 
 <br />
 
@@ -314,7 +407,7 @@ Suppose you are **not** using the background audio service on Android. In that c
 
 [Android](#android-casting) | [iOS](#ios-casting) | [DRM Casting](#drm-casting)
 
-JWP enables casting by default with a casting button.
+JWX enables casting by default with a casting button.
 
 <br />
 
@@ -380,7 +473,7 @@ Casting your DRM protected content requires some additional configuration and mo
 
 See our Android and iOS documentation about creating ([iOS](https://docs.jwplayer.com/players/docs/ios-create-a-custom-receiver) / [Android](https://docs.jwplayer.com/players/docs/android-create-a-custom-receiver)) and sending data ([iOS](https://docs.jwplayer.com/players/docs/ios-enable-casting-to-chromecast-devices#send-custom-data-to-a-custom-receiver) / [Android](https://docs.jwplayer.com/players/docs/android-enable-casting-to-chromecast-devices#send-custom-data-to-a-custom-receiver)) for more information.
 
-To send custom data to your receiver, use the `userInfo` prop and avoid using the reserved `sources` key, as the JWP SDK will append the DRM source information here for you to parse in your DRM enabled receiver. 
+To send custom data to your receiver, use the `userInfo` prop and avoid using the reserved `sources` key, as the JWX SDK will append the DRM source information here for you to parse in your DRM enabled receiver. 
 
 <br /><br />
 
@@ -398,11 +491,11 @@ Only Widevine is supported.
 
 Follow these steps to enable DRM:
 1. Set up your Android app for [DRM playback](https://developer.jwplayer.com/jwplayer/docs/android-play-drm-protected-content).
-2. Define `config.playlist` with the [JWP signed URL](https://docs.jwplayer.com/platform/docs/protection-studio-drm-generate-a-signed-content-url-for-drm-playback) of the media to play in the player.
+2. Define `config.playlist` with the [JWX signed URL](https://docs.jwplayer.com/platform/docs/protection-studio-drm-generate-a-signed-content-url-for-drm-playback) of the media to play in the player.
 
 *❗️DO NOT sign and store your API secerets from your application.❗️*
 
-If you use a different provider for DRM or this does not work for your use case, conforming to a similiar format as a JWP signed URL response is optimal, such as adding the `drm` field to the `sources` for a playlist item).
+If you use a different provider for DRM or this does not work for your use case, conforming to a similiar format as a JWX signed URL response is optimal, such as adding the `drm` field to the `sources` for a playlist item).
 
 <br />
 
@@ -414,11 +507,11 @@ The below is currently not fully supported by the iOS SDK, so please refer to `E
 
 > Follow these steps to enable DRM:
 > 1. Set up your iOS app for [DRM playback](https://developer.jwplayer.com/jwplayer/docs/ios-play-drm-protected-content).
-> 2. Define `config.playlist` with the [JWP signed URL](https://docs.jwplayer.com/platform/docs/protection-studio-drm-generate-a-signed-content-url-for-drm-playback) of the media to play in the player.
+> 2. Define `config.playlist` with the [JWX signed URL](https://docs.jwplayer.com/platform/docs/protection-studio-drm-generate-a-signed-content-url-for-drm-playback) of the media to play in the player.
 >
 > *❗️DO NOT sign and store your API secerets from your application.❗️*
 > 
-If you use a different provider for DRM or this does not work for your use case, conforming to a similiar format as a JWP signed URL response is optimal, such as adding the `drm` field to the `sources` for a playlist item).
+If you use a different provider for DRM or this does not work for your use case, conforming to a similiar format as a JWX signed URL response is optimal, such as adding the `drm` field to the `sources` for a playlist item).
 
 <br /><br />
 
@@ -446,7 +539,7 @@ If you use a different provider for DRM or this does not work for your use case,
 
 #### iOS PiP
 
-1. Read and understand the requirements for PiP in the [iOS SDK](https://docs.jwplayer.com/players/docs/ios-invoke-picture-in-picture-playback). PiP mode is enabled by JWP for the `PlayerViewController`.
+1. Read and understand the requirements for PiP in the [iOS SDK](https://docs.jwplayer.com/players/docs/ios-invoke-picture-in-picture-playback). PiP mode is enabled by JWX for the `PlayerViewController`.
 2. (viewOnly:true only) Set the `pipEnabled` prop to `true`.
 3. (viewOnly:true only) Call `togglePIP()` to enable or disable PiP.
 4. Ensure [category](/docs//legacy_readme.md#audiosessioncategory) and/or [categoryOptions](/docs//legacy_readme.md#audiosessioncategoryoptions) prop(s) are set to define and configure your media. This is required to setup the audio session. If `category` is not defined but `pipEnabled` is set true, we default to the standard `playback` category to avoid crashing.  
@@ -458,9 +551,9 @@ If you use a different provider for DRM or this does not work for your use case,
 [Android](#android-styling) | [iOS](#ios-styling)
 
 #### Android Styling
-The `styling` prop will not work when using the modern prop convention that matches the JWP Delivery API. Even when using the `forceLegacyConfig` prop, Android may not respect your choices.
+The `styling` prop will not work with Android when using the modern configuration system. Android styling should be handled through XML resource overrides (see below).
 
-Android styling is best handled through overring JWP IDs in your apps resources files. See the documentation [here](https://docs.jwplayer.com/players/docs/android-styling-guide). 
+Android styling is best handled through overring JWX IDs in your apps resources files. See the documentation [here](https://docs.jwplayer.com/players/docs/android-styling-guide). 
 
 A sample of overring a color via XML can be seen in this [colors file](Example/android/app/src/main/res/values/colors.xml). The color specified here is the default, but if you wish to change it, the color will be updated on the player.
 

package/RNJWPlayer.podspec

@@ -12,7 +12,7 @@ Pod::Spec.new do |s|
   s.platform     = :ios, "15.0"
   s.source       = { :git => "https://github.com/jwplayer/jwplayer-react-native.git", :tag => "v#{s.version}" }
   s.source_files  = "ios/RNJWPlayer/*.{h,m,swift}"
-  s.dependency   'JWPlayerKit', '4.23.2'
+  s.dependency   'JWPlayerKit', '4.25.0'
   s.dependency   'React-Core'
   s.static_framework = true
   s.info_plist = {

package/android/build.gradle

@@ -39,6 +39,15 @@ android {
         }
     }
 
+    // Enable desugaring conditionally when IMA is used (required for IMA SDK 3.37.0+)
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+        if (useIMA) {
+            coreLibraryDesugaringEnabled true
+        }
+    }
+
     buildTypes {
         debug {
             // Set the build config fields for the debug build type
@@ -73,7 +82,7 @@ allprojects {
     }
 }
 
-def jwPlayerVersion = "4.21.1"
+def jwPlayerVersion = "4.24.0"
 def exoplayerVersion = "2.18.7" // Deprecated. Use Media3 when targeting JW SDK > 4.16.0
 def media3ExoVersion = "1.4.1"
 
@@ -91,6 +100,10 @@ dependencies {
     if (useIMA) {
         implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.36.0'
         implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
+        // Core library desugaring (required for IMA SDK 3.37.0+)
+        // Using version 2.1.5 as recommended by IMA SDK documentation:
+        // https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/get-started
+        coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'
     }
 
     // Cast dependencies

package/android/src/main/java/com/jwplayer/rnjwplayer/RNJWPlayerModule.java

@@ -434,12 +434,27 @@ public class RNJWPlayerModule extends ReactContextBaseJavaModule {
 
     @ReactMethod
     /**
-     * Stub method for recreatePlayerWithConfig - this method is iOS only
-     * On Android, create a new player instance with the new configuration instead
+     * Reconfigures or recreates the player with a new configuration.
+     * 
+     * This method intelligently determines whether to:
+     * 1. Reconfigure the existing player (preferred, ~90% of cases)
+     * 2. Recreate the player (only when necessary, e.g., license changes)
+     * 
+     * Note: Despite the name "recreate", this method usually does NOT recreate the player.
+     * It follows the JWPlayer SDK's design intent of reusing player instances via setup() calls.
+     * 
+     * This provides API parity with iOS while being more efficient on Android.
      */
     public void recreatePlayerWithConfig(final int reactTag, final ReadableMap config) {
-        // No-op on Android - this method is iOS only
-        Log.w("RNJWPlayer", "recreatePlayerWithConfig is not supported on Android. Create a new player instance with the new configuration instead.");
+        new Handler(Looper.getMainLooper()).post(() -> {
+            RNJWPlayerView playerView = getPlayerView(reactTag);
+            if (playerView != null) {
+                // Delegate to setConfig() which intelligently handles reconfiguration vs recreation
+                playerView.setConfig(config);
+            } else {
+                Log.e("RNJWPlayer", "recreatePlayerWithConfig: Player view not found for tag " + reactTag);
+            }
+        });
     }
 
     private int stateToInt(PlayerState playerState) {