@benshi.ai/react-native-bsh-video

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 [e-mail] in case you have any further queries. We're always just an email away!