Benshi React Native Video Player Setup

Media Player to auto track media events (play, pause, seek and finish) for benshi AI platform. Using this package, you don't need to worry about triggering the events or passing the right information, package will take care of that itself also it will trigger the catalog API for you when provided the content.

You can use this video player for both android and iOS but the events will only be triggered when it is an android device. For iOS this will skip the events until the iOS support is included.

This package contains a simple set of GUI controls that work with the @benshi.ai/react-native-bsh-core <media> events. This includes a back button, volume bar, play/pause toggle, seekbar, title, error handling and timer toggle that can switch between time remaining and current time when tapped.

By default the <VideoPlayer> accepts a navigator property from React's built-in <Navigator> which pops the current scene off the stack when tapped. Alternatively you can provide your own onBack prop to the component to override this functionality. You should also provide your own onEnd prop to the component so it knows what to do when a video ends playback.

You can also customize the <VideoPlayer> class as per your design guidelines. For basic operation the <VideoPlayer> component requires a video source and a navigator property. The default back button functionality in the component relies on using the built-in <Navigator> functionality in React Native and pops the current scene off the stack. This can be overridden if desired, see the Usage for more details.

Table of Contents

• Installation
  • Android
  • iOS
• Usage
  • Props
  • Events
  • Controls
• Guidelines

Installation

Using npm:

npm install --save react-native-bsh-video

or using yarn:

yarn add react-native-bsh-video

Then follow the instructions for your platform to link react-native-bsh-video into your project:

Android installation

Linking is not required in React Native 0.60 and above. If your project is using React Native < 0.60, run react-native link react-native-bsh-video to link the react-native-bsh-video library.

Or if you have trouble, make the following additions to the given files manually:

android/settings.gradle

Add player source in build configuration

include ':react-native-bsh-video'
project(':react-native-bsh-video').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-bsh-video/android')

android/app/build.gradle

From version >= 5.0.0, you have to apply these changes:

dependencies {
   ...
    implementation project(':react-native-bsh-video')
+   implementation "androidx.appcompat:appcompat:1.0.0"
-   implementation "com.android.support:appcompat-v7:${rootProject.ext.supportLibVersion}"

}

android/gradle.properties

Migrating to AndroidX (needs version >= 5.0.0):

android.useAndroidX=true
android.enableJetifier=true

iOS installation

Standard Method

React Native 0.60 and above

Run npx pod-install. Linking is not required in React Native 0.60 and above.

React Native 0.59 and below

Run react-native link react-native-bsh-video to link the react-native-bsh-video library.

Enable Static Linking for dependencies in your ios project Podfile

Add use_frameworks! :linkage => :static just under platform :ios in your ios project Podfile.

Using CocoaPods (required to enable caching)

Setup your Podfile like it is described in the react-native documentation.

Depending on your requirements you have to choose between the two possible subpodspecs:

Video only:

  pod 'Folly', :podspec => '../node_modules/react-native/third-party-podspecs/Folly.podspec'
+  `pod 'react-native-bsh-video', :path => '../node_modules/react-native-bsh-video/react-native-video.podspec'`
end

  pod 'Folly', :podspec => '../node_modules/react-native/third-party-podspecs/Folly.podspec'
+  `pod 'react-native-bsh-video/VideoCaching', :path => '../node_modules/react-native-bsh-video/react-native-video.podspec'`
end

To use the library properly, you need to also include @benshi.ai/react-native-bsh-core in your project as it has a peer dependency on that to log the events. You don't need to setup any listeners in order to track the events for the sdk as this will auto trigger those events along with the catalog event. To use in your js you can refer below, you need to provide the following details at once and the rest will be taken care by the package.

// At the top where our imports are...
import VideoPlayer from 'react-native-bsh-video';

// in the component's render() function
<VideoPlayer
    style={{ height: 220 }}
    source={{uri: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4'}}
    videoId={"RN-MEDIA-ID"}
    videoContentBlock={ContentBlock.Core}
    videoTitle={"Test Video Title"}
    displayTitle={false}
    videoDescription={"Test Video Description"}
    videoResolution={"720p"}
    videoLanguage={LanguageCode.English}
    navigator={this.props.navigator}
/>

To play a local file, use require syntax like so:

<VideoPlayer source={require('path/to/file')} />

Usage

The <VideoPlayer> component can take a number of inputs to customize it as needed. They are outlined below:

Video Events

You need to pass the following props for the video player to log the events and also to handle the catalog events.

| Prop | Type | Required | Description | | ----------------- | --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | videoId | string | required | To set the video Id that in your backend | | videoTitle | string | optional | To set the title/name of the video in question, to show on the player and also used for catalog | | videoDescription | string | optional | To pass the description for the video, used for catalog | | videoResolution | string | optional | To pass the resolution of the video, must be in a string format, values should be standard resolution string, 480p, 720p, etc. used for catalog | | videoLanguage | string | optional | To pass the language of the video, must be from the enum provided by the core SDk, LanguageCode, used for catalog | | videoContentBlock | string | optional | to pass the content block for the video, can be core, e-commerce, e0learning, etc. default is core. |

Props

You can pass any of the props that the <Video /> component at react-native-video takes. Simply add them onto the <VideoPlayer /> and it will pass them through to the <Video /> component.

In addition, the <VideoPlayer /> also takes these props:

| Prop | Type | Default | Description | | ---------------------------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | toggleResizeModeOnFullscreen | Boolean | true | If true, clicking the fullscreen button will toggle the <Video /> component between cover/contain, set to false if you want to customize fullscreen behaviour | | controlAnimationTiming | Integer | 500 | The amount of time (in milliseconds) to animate the controls in and out. | | doubleTapTime | Integer | 130 | Tapping twice within this amount of time in milliseconds is considered a double tap. Single taps will not be actioned until this time has expired. | | controlTimeout | Integer | 15000 | Hide controls after X amount of time in milliseconds | | scrubbing | Integer | 0 | If > 0, enable live scrubbing when moving the seek bar. The provided value is the minimum time step of the scrubbing in milliseconds. | | showOnStart | Boolean | true | Show or hide the controls on first render | | videoStyle | StyleSheet | null | React Native StyleSheet object that is appended to the <Video> component | | navigator | Navigator | null | When using the default React Native navigator and do not override the onBack function, you'll need to pass the navigator to the VideoPlayer for it to function | | seekColor | String(#HEX) | '#FFF' | Fill/handle colour of the seekbar | | style | StyleSheet | null | React Native StyleSheet object that is appended to the video's parent View | | tapAnywhereToPause | Boolean | false | If true, single tapping anywhere on the video (other than a control) toggles between playing and paused. | | showTimeRemaining | Boolean | true | If true, show the time remaining, else show the current time in the Player View. | showHours | Boolean | false | If true, convert time to hours in the Player View.

Events

These are various events that you can hook into and fire functions on in the component:

| Callback | Description | | ----------------- | ------------------------------------------------------------------------------- | | onEnterFullscreen | Fired when the video enters fullscreen after the fullscreen button is pressed | | onExitFullscreen | Fired when the video exits fullscreen after the fullscreen button is pressed | | onHideControls | Fired when the controls disappear | | onShowControls | Fired when the controls appear | | onError | Fired when an error is encountered when loading the video | | onPause | Fired when the video is paused after the play/pause button is pressed | | onPlay | Fired when the video begins playing after the play/pause button is pressed | | onBack | Function fired when back button is pressed, override if using custom navigation | | onEnd | Fired when the video is complete |

Controls

These are the various controls that you can turn on/off as needed. All of these props default to false, override them to disable any controls

| Control | Description | | ----------------- | -------------------------- | | displayTitle | Show title of the video | | disableFullscreen | Hide the fullscreen button | | disablePlayPause | Hide the play/pause toggle | | disableSeekbar | Hide the seekbar | | disableVolume | Hide the Volume control | | disableTimer | Hide the timer | | disableBack | Hide the back button |

Guidelines

• By default, iOS will only load encrypted (https) urls. If you want to load content from an encrypted (http) source, you will need to modify your Info.plist file. For more detailed info check this article

• When using a router like the react-navigation TabNavigator, switching between tab routes would previously cause ExoPlayer to detach causing the video player to pause. We now don't detach the view, allowing the video to continue playing in a background tab. This matches the behavior for iOS.

• All platforms will auto-play if the paused prop was not set, the media would not automatically start playing. The only way it would work was if you set paused={false}. This has been changed to automatically play if paused is not set so that the behavior is consistent across platforms.

• All platforms now keep their paused state when returning from the background.

• If your video work on Debug mode, but on Release you see only black screen, please, check the link to your video. If you use 'http' protocol there, you will need to add next string to your AndroidManifest.xml file.

<application
 ...
 android:usesCleartextTraffic="true"
>

Please feel free to drop in a few lines at [email protected] in case you have any further queries. We're always just an email away!