bitmovin-player-react-native 0.3.0 → 0.4.0

package/README.md

@@ -7,25 +7,33 @@ Official React Native bindings for Bitmovin's mobile Player SDKs.
 [![MIT License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 [![Bitmovin Community](https://img.shields.io/discourse/users?label=community&server=https%3A%2F%2Fcommunity.bitmovin.com)](https://community.bitmovin.com/?utm_source=github&utm_medium=bitmovin-player-react-native&utm_campaign=dev-community)
 
-> The library is under active development.
+> As the library is under active development, this means certain features from our native SDKs are not yet exposed through these React Native bindings.  
+> See [Feature Support](#feature-support) for an overview of the supported features.
+>
+> Not seeing the features you’re looking for?  
+> We are accepting community pull requests to this open-source project so please feel free to contribute.
+> or let us know in [our community](https://community.bitmovin.com/c/requests/14) what features we should work on next.
 
 - [Bitmovin Player React Native](#bitmovin-player-react-native)
   - [Platform Support](#platform-support)
+  - [Feature Support](#feature-support)
   - [Installation](#installation)
     - [Add package dependency](#add-package-dependency)
     - [Setup iOS Player SDK](#setup-ios-player-sdk)
     - [Setup Android Player SDK](#setup-android-player-sdk)
   - [Getting Started](#getting-started)
     - [Setting up a license key](#setting-up-a-license-key)
-      - [Configuring through code](#configuring-through-code)
-    - [Setting up a playback configurations](#setting-up-a-playback-configurations)
-      - [Configuring `Info.plist`](#configuring-infoplist)
-      - [Configuring `AndroidManifest.xml`](#configuring-androidmanifestxml)
+      - [Through code](#through-code)
+      - [Through `Info.plist`](#through-infoplist)
+      - [Through `AndroidManifest.xml`](#through-androidmanifestxml)
+    - [Setting up the playback configuration](#setting-up-the-playback-configuration)
     - [Accessing native `Player` instances](#accessing-native-player-instances)
     - [Listening to events](#listening-to-events)
     - [Enabling DRM protection](#enabling-drm-protection)
       - [Prepare hooks](#prepare-hooks)
     - [Adding external subtitle tracks](#adding-external-subtitle-tracks)
+    - [Enabling Picture in Picture mode](#enabling-picture-in-picture-mode)
+    - [Setting up ads](#setting-up-ads)
   - [Contributing](#contributing)
 
 ## Platform Support
@@ -40,6 +48,19 @@ This library requires at least React Native 0.64+ and React 17+ to work properly
 
 Please note that browsers and other browser-like environments such as webOS and Tizen are not supported.
 
+## Feature Support
+
+Features of the native mobile Player SDKs are progressively being implemented in this React Native library. The table below summarizes the current state of the main Player SDK features.
+
+| Feature                          | State                                     |
+| -------------------------------- | ----------------------------------------- |
+| Playback of DRM-protected assets | :white_check_mark: Available since v0.2.0 |
+| Subtitles & Captions             | :white_check_mark: Available since v0.2.0 |
+| Advertising                      | :gear: In progress, Q4 2022               |
+| Playlist API                     | :x: Not available                         |
+| Offline Playback                 | :x: Not available                         |
+| Analytics                        | :x: Coming Q1 2023                        |
+
 ## Installation
 
 Since Bitmovin's native SDKs are distributed through custom [Cocoapods](https://github.com/bitmovin/cocoapod-specs) and [Maven](https://artifacts.bitmovin.com/ui/native/public-releases) repositories, the installation cannot be managed by React Native's Autolink and requires some extra steps. Please refer to the installation instructions for each platform below. For more information on integrating the native SDKs, refer to the [Getting Started guides](https://bitmovin.com/docs/getting-started).
@@ -200,7 +221,7 @@ First of all, create a license key on the [Dashboard](https://bitmovin.com/dashb
 
 Then your license key can be either set from code or by configuring `Info.plist` and `AndroidManifest.xml`.
 
-#### Configuring through code
+#### Through code
 
 ```typescript
 // Simply pass the `licenseKey` property to `PlayerConfig` when instantiating a player.
@@ -219,7 +240,24 @@ const player = new Player({
 });
 ```
 
-### Setting up a playback configurations
+#### Through `Info.plist`
+
+Add the following lines to the `<dict>` section of your `ios/Info.plist`:
+
+```xml
+<key>BitmovinPlayerLicenseKey</key>
+<string>ENTER-YOUR-LICENSE-KEY</string>
+```
+
+#### Through `AndroidManifest.xml`
+
+Add the following line to the `<application>` section of your `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<meta-data android:name="BITMOVIN_PLAYER_LICENSE_KEY" android:value="ENTER-YOUR-LICENSE-KEY" />
+```
+
+### Setting up the playback configuration
 
 If needed, the default player behavior can be configured through the `playbackConfig` key when initialized.
 
@@ -239,6 +277,14 @@ const player = usePlayer({
     // Whether background playback is enabled or not. Default is false.
     // Only available for iOS.
     isBackgroundPlaybackEnabled: true,
+    // Enable the Picture in Picture mode option on the player controls.
+    //
+    // Note iOS requires the audio session category of your app to be set to `playback` otherwise
+    // PiP mode won't work.
+    //
+    // Check out `Enabling Picture in Picture mode` section of README for more information
+    // on how to properly configure your app to support PiP.
+    isPictureInPictureEnabled: true,
   },
 });
 
@@ -251,27 +297,11 @@ const player = new Player({
     isMuted: true,
     isTimeShiftEnabled: true,
     isBackgroundPlaybackEnabled: true,
+    isPictureInPictureEnabled: true,
   },
 });
 ```
 
-#### Configuring `Info.plist`
-
-Add the following lines to the `<dict>` section of your `ios/Info.plist`:
-
-```xml
-<key>BitmovinPlayerLicenseKey</key>
-<string>ENTER-YOUR-LICENSE-KEY</string>
-```
-
-#### Configuring `AndroidManifest.xml`
-
-Add the following line to the `<application>` section of your `android/app/src/main/AndroidManifest.xml`:
-
-```xml
-<meta-data android:name="BITMOVIN_PLAYER_LICENSE_KEY" android:value="ENTER-YOUR-LICENSE-KEY" />
-```
-
 ### Accessing native `Player` instances
 
 When you instantiate a player with `usePlayer` or `new Player()` from javascript, you're actually either creating a new `Player` instance in the native side (see [SDKs docs](https://bitmovin.com/docs/player/sdks) for more info) or referencing an existing one.
@@ -486,6 +516,190 @@ The supported `PlayerView` events for subtitles are:
 
 You might check out a complete subtitle example in the [`example/`](https://github.com/bitmovin/bitmovin-player-react-native/tree/development/example) app.
 
+### Enabling Picture in Picture mode
+
+In order to make use of the Picture in Picture functionalities provided by the player, it's first necessary to configure your native application to properly support PiP.
+
+The steps required for each platform are described below:
+
+#### Android
+
+**Declare Picture in Picture support on AndroidManifest.xml**
+
+Open `android/app/src/main/AndroidManifest.xml` and set `android:supportsPictureInPicture` to `true`
+on your main activity's manifest. Also, specify that your activity handles layout configuration changes
+so that your activity doesn't relaunch when layout changes occur during PiP mode transitions:
+
+```xml
+<activity android:name=".MainActivity"
+    android:supportsPictureInPicture="true"
+    android:configChanges=
+        "screenSize|smallestScreenSize|screenLayout|orientation"
+    ...
+```
+
+#### iOS
+
+**Set background modes capability**
+
+Make sure to add the `UIBackgroundModes` key to the `dict` section of your `Info.plist`:
+
+```xml
+<key>UIBackgroundModes</key>
+<array>
+  <string>audio</string>
+</array>
+```
+
+This step can also be performed from [Xcode](https://developer.apple.com/documentation/xcode/configuring-background-execution-modes).
+
+**Configure audio session on app startup**
+
+Configure your app's `AudioSession` category to `playback` during the main component's initialization:
+
+```typescript
+import { AudioSession } from 'bitmovin-player-react-native';
+
+// App's root component
+const App = () => {
+  useEffect(() => {
+    // Set your app's `AudioSession` category to `playback` on initialization.
+    // Please, note even though this step is required for iOS it won't take any effect on Android.
+    AudioSession.setCategory('playback').catch((error) => {
+      // Handle any native error that might occur during this process.
+      handleError(error);
+    });
+  });
+  // ...
+  return /* ... */;
+};
+```
+
+This step is required in order to properly enable background playback on iOS. Without it, the Picture in Picture option appears on the player UI but has no effect when used.
+
+You can read more about it on [Apple's docs](https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616509-playback).
+
+#### Showing the Picture in Picture UI option
+
+Now that your native application is properly configured to support PiP changes, the player instance
+in your JS code can be configured to show the Picture in Picture option in the player UI.
+
+Simply add `isPictureInPictureEnabled: true` on your player's `playbackConfig` option:
+
+```typescript
+const player = usePlayer({
+  playbackConfig: {
+    isPictureInPictureEnabled: true,
+  },
+});
+```
+
+#### Supported Picture in Picture events
+
+The supported Picture in Picture events on `PlayerView` are:
+
+- `onPictureInPictureEnter`
+- `onPictureInPictureExit`
+
+**iOS only**
+
+- `onPictureInPictureEntered`
+- `onPictureInPictureExited`
+
+**Android only**
+
+- `onPictureInPictureAvailabilityChanged`
+
+Check [`events.ts`](https://github.com/bitmovin/bitmovin-player-react-native/blob/development/src/components/PlayerView/events.ts) for more information about them.
+
+### Setting up ads
+
+The Bitmovin Player SDKs are capable of displaying Ads out of the box and there are two ways they can be
+configured with the player. One option is to use static configuration in the player config object,
+and the other is to schedule them dynamically using `Player.scheduleAd`.
+
+#### Static ads configuration
+
+The easiest way to configure Ads is by adding the `advertisingConfig` property to the player configuration object.
+All that needs to be provided is a URL pointing to a target Ad tag along with the type of the tag.
+
+```typescript
+const player = usePlayer({
+  licenseKey: '<PLAYER_LICENSE_KEY>',
+  advertisingConfig: {
+    // Each object in `schedule` represents an `AdItem`.
+    schedule: [
+      // An `AdItem` represents a time slot within the streamed content dedicated to ads playback.
+      {
+        // Each item specifies a list of sources with a type and URL to the ad manifest in the ads
+        // server. All but the first source act as fallback if the first one fails to load.
+        // The start and end of an ad break are signaled via `AdBreakStartedEvent` and `AdBreakFinishedEvent`.
+        sources: [
+          {
+            type: AdSourceType.IMA,
+            tag: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=',
+          },
+          // Fallback sources...
+        ],
+        // Each item also specifies the position where it should appear during playback.
+        // The possible position values are documented below.
+        // The default value is `pre`.
+        position: '20%',
+      },
+    ],
+  },
+});
+```
+
+The possible `AdItem` position values are:
+
+- `"pre"`: pre-roll ad (for VoD and Live streaming; appears before playback starts)
+- `"post"`: post-roll ad (for VoD streaming only; appears after playback finishes)
+- Fractional seconds: `"10"`, `"12.5"` (mid-roll ad, for VoD and Live streaming)
+- Percentage of the entire video duration: `"25%"`, `"50%"` (mid-roll ad, for VoD streaming only)
+- Timecode `hh:mm:ss.mmm`: `"00:10:30.000"`, `"01:00:00.000"` (mid-roll ad, for VoD streaming only)
+
+#### Dynamic ads scheduling
+
+To gain more flexibility, it is also possible to schedule an `AdItem` dynamically in code using the
+`Player` instance. To do this, you need to call the `scheduleAd` method.
+
+```typescript
+// The object passed to `scheduleAd` must be an `AdItem`.
+player.scheduleAd({
+  // Ad source with fallbacks.
+  sources: [
+    {
+      tag: '<AD-URL>',
+      type: AdSourceType.IMA,
+    },
+  ],
+});
+```
+
+An `AdScheduledEvent` event is dispatched when the ad is successfully scheduled via `scheduleAd`.
+
+Also, during playback, it's also possible to check whether an ad is being played with `player.isAd()`
+and skip the ad being currently played with `player.skipAd()` (see `AdSkippedEvent`).
+
+#### Supported ads events
+
+The supported `PlayerView` events for ads are:
+
+- `onAdBreakFinished`
+- `onAdBreakStarted`
+- `onAdClicked`
+- `onAdError`
+- `onAdFinished`
+- `onAdManifestLoad`
+- `onAdManifestLoaded`
+- `onAdQuartile`
+- `onAdScheduled`
+- `onAdSkipped`
+- `onAdStarted`
+
+You can check out a complete ads example in the [`example/`](https://github.com/bitmovin/bitmovin-player-react-native/tree/development/example) app.
+
 ## Contributing
 
 See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

package/RNBitmovinPlayer.podspec

@@ -19,5 +19,7 @@ Pod::Spec.new do |s|
   s.source_files = "ios/**/*.{h,m,mm,swift}"
 
   s.dependency "React-Core"
-  s.dependency "BitmovinPlayer", "3.28.0"
+  s.dependency "BitmovinPlayer", "3.30.0"
+  s.ios.dependency "GoogleAds-IMA-iOS-SDK", "3.17.0"
+  s.tvos.dependency "GoogleAds-IMA-tvOS-SDK", "4.6.1"
 end

package/android/build.gradle

@@ -1,6 +1,6 @@
 buildscript {
     ext {
-        kotlinVersion = '1.7.0'
+        kotlinVersion = '1.7.20'
         androidToolsVersion = '7.0.4'
     }
     repositories {
@@ -27,10 +27,10 @@ repositories {
 }
 
 android {
-    compileSdk 31
+    compileSdk 33
     defaultConfig {
-        minSdkVersion 21
-        targetSdkVersion 31
+        minSdkVersion 16
+        targetSdkVersion 33
         versionCode 1
         versionName '1.0'
     }
@@ -50,6 +50,8 @@ android {
 
 dependencies {
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlinVersion"
-    implementation 'com.bitmovin.player:player:3.24.2'
+    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.26.0'
+    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
+    implementation 'com.bitmovin.player:player:3.25.2'
     implementation 'com.facebook.react:react-native:+'
 }

package/android/src/main/java/com/bitmovin/player/reactnative/DrmModule.kt

@@ -17,7 +17,9 @@ import kotlin.concurrent.withLock
  */
 typealias PrepareCallback = (ByteArray) -> ByteArray
 
-@ReactModule(name = DrmModule.name)
+private const val MODULE_NAME = "DrmModule"
+
+@ReactModule(name = MODULE_NAME)
 class DrmModule(private val context: ReactApplicationContext) : ReactContextBaseJavaModule(context) {
     /**
      * In-memory mapping from `nativeId`s to `WidevineConfig` instances.
@@ -52,10 +54,7 @@ class DrmModule(private val context: ReactApplicationContext) : ReactContextBase
     /**
      * JS exported module name.
      */
-    companion object {
-        const val name = "DrmModule"
-    }
-    override fun getName() = DrmModule.name
+    override fun getName() = MODULE_NAME
 
     /**
      * Fetches the `WidevineConfig` instance associated with `nativeId` from internal drmConfigs.

package/android/src/main/java/com/bitmovin/player/reactnative/PlayerModule.kt

@@ -6,7 +6,9 @@ import com.facebook.react.bridge.*
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.uimanager.UIManagerModule
 
-@ReactModule(name = PlayerModule.name)
+private const val MODULE_NAME = "PlayerModule"
+
+@ReactModule(name = MODULE_NAME)
 class PlayerModule(private val context: ReactApplicationContext) : ReactContextBaseJavaModule(context) {
     /**
      * In-memory mapping from `nativeId`s to `Player` instances.
@@ -16,10 +18,7 @@ class PlayerModule(private val context: ReactApplicationContext) : ReactContextB
     /**
      * JS exported module name.
      */
-    companion object {
-        const val name = "PlayerModule"
-    }
-    override fun getName() = PlayerModule.name
+    override fun getName() = MODULE_NAME
 
     /**
      * Fetches the `Player` instance associated with `nativeId` from the internal players.
@@ -280,6 +279,43 @@ class PlayerModule(private val context: ReactApplicationContext) : ReactContextB
         }
     }
 
+    /**
+     * Schedules an `AdItem` in the `nativeId`'s associated player.
+     * @param nativeId Target player id.
+     * @param adItemJson Json representation of the `AdItem` to be scheduled.
+     */
+    @ReactMethod
+    fun scheduleAd(nativeId: NativeId, adItemJson: ReadableMap?) {
+        JsonConverter.toAdItem(adItemJson)?.let { adItem ->
+            uiManager()?.addUIBlock {
+                players[nativeId]?.scheduleAd(adItem)
+            }
+        }
+    }
+
+    /**
+     * Skips the current ad in `nativeId`'s associated player.
+     * Has no effect if the current ad is not skippable or if no ad is being played back.
+     * @param nativeId Target player id.
+     */
+    @ReactMethod
+    fun skipAd(nativeId: NativeId) {
+        uiManager()?.addUIBlock {
+            players[nativeId]?.skipAd()
+        }
+    }
+
+    /**
+     * Returns `true` while an ad is being played back or when main content playback has been paused for ad playback.
+     * @param nativeId Target player id.
+     */
+    @ReactMethod
+    fun isAd(nativeId: NativeId, promise: Promise) {
+        uiManager()?.addUIBlock {
+            promise.resolve(players[nativeId]?.isAd)
+        }
+    }
+
     /**
      * Helper function that returns the initialized `UIManager` instance.
      */