@tivio/sdk-react 2.4.0 → 2.4.4

package/README.md

@@ -2,6 +2,10 @@
 
 ## Changelog
 * Unreleased
+* v2.4.2
+  * patch: added back changelog
+* v2.4.1
+  * patch: improved doc about player wrapper
 * v2.4.0
   * patch: improved Player wrapper types
   * minor: added Tivio DOM events `tivio_key_input_handling_change`, `tivio_context_switch` and `tivio_request_goto`
@@ -58,16 +62,14 @@
 * v1.3.4
   * ...
 
-## Installation
 
-Check/install peer dependencies
-``` sh
-npm install --save mobx@6.0.4 styled-components@5.2.1 firebase@8.2.3 react@17.0.2 react-dom@17.0.2
-```
+## Installation
 
-Install SDK itself
-``` sh
-npm install --save @tivio/sdk-react
+Install @tivio/sdk-react along with its peer dependencies
+```sh
+npm i react@17 react-dom@17 @tivio/sdk-react
+# or
+yarn add react@17 react-dom@17 @tivio/sdk-react
 ```
 
 ## Initialization
@@ -77,13 +79,13 @@ Put Tivio Provider at the top level of your application:
 ``` javascript
 import { TivioProvider } from '@tivio/sdk-react'
 
-const tivioConf = {
+const config = {
     secret: 'XXXXXXXXXX',
 }
 
 function App({children}) {
     return (
-        <TivioProvider conf={tivioConf}>
+        <TivioProvider conf={config}>
            {children}
         </TivioProvider>
     )
@@ -95,7 +97,7 @@ function App({children}) {
 ``` javascript
 import { TivioProvider, setUser } from '@tivio/sdk-react'
 
-const tivioConf = {
+const config = {
     secret: 'XXXXXXXXXX',
 }
 
@@ -103,7 +105,7 @@ setUser('user-id', { some: 'payload' })
 
 function App({children}) {
     return (
-        <TivioProvider conf={tivioConf}>
+        <TivioProvider conf={config}>
            {children}
         </TivioProvider>
     )
@@ -112,7 +114,7 @@ function App({children}) {
 ## Tivio widget
 
 Tivio widget is the main Tivio component which shows the widget and provides access to its channels, sections and videos.
-Usage is very simple (be sure to set `id` to the widget ID you have configured in Tivio Studio):
+Usage is very simple (be sure to set `id` to the widget ID you have configured in [Tivio Studio](https://studio.tiv.io/)):
 
 ``` javascript
 import { TivioWidget } from '@tivio/sdk-react'
@@ -141,45 +143,108 @@ function Screen() {
     )
 }
 ```
+
 ## Player wrapper
 
-Player wrapper is the way how you can enhance your video player with Tivio features (e.g. inserting of ads).
+Player wrapper is the way how you can enhance your video player with Tivio features, such Tivio Ads. In order to start using Tivio player wrapper, wrap your player methods with PlayerWrapper, start using PlayerWrapper's methods instead of them to control your playback and start sending player events to Tivio PlayerWrapper.
+
+### Wrap your player methods with Tivio player wrapper
 
 ``` javascript
-import { useTivioData } from '@tivio/sdk-react'
+import { useTivioReadyData } from '@tivio/sdk-react'
 
 function CustomPlayer() {
-    const tivio = useTivioData()
-    const [isPlaying, setIsPlaying] = useState()
+    const tivioData = useTivioReadyData()
 
     useEffect(() => {
-        (async () => {
-            if (tivio.getPlayerWrapper) {
-                const playerWrapper = await tivio.getPlayerWrapper(
-                    { playerWrapperId: 'default' }
-                )
-
-                playerWrapper.register({
-                    play: () => {
-                        setIsPlaying(true)
-                        // start playback using your player here
-                    },
-                    pause: () => {
-                        setIsPlaying(false)
-                        // pause playback using your player here
-                    },
-                    seekTo: (ms: number) => {
-                        // seek using your player here
-                    },
-                    setSource: (videoSource: InputSource) => {
-                        // play videoSource using your player here
-                    },
-                })
-            }
-        })()
-    }, [])
-
-    return (<div>Example is {isPlaying ? null : 'not '}playing.</div>)
+        if (tivioData) {
+            // If your app uses multiple player instances, use different Tivio player wrapper for each
+            // distinguished by playerWrapperId
+            const playerWrapper = tivio.getPlayerWrapper({ playerWrapperId: 'PLAYER_1' })
+
+            // Pass your player methods to Tivio player wrapper
+            playerWrapper.register({
+                play: () => {
+                    // Un-pause your player
+                },
+                pause: () => {
+                    // Pause your player
+                },
+                seekTo: (ms: number) => {
+                    // Seek to position in milliseconds using your player
+                },
+                setSource: (videoSource: InputSource) => {
+                    // Send this video source to your player to load it
+                },
+            })
+        }
+    }, [tivioData])
+}
+```
+
+### Start using Tivio player wrapper methods to control playback
+
+``` javascript
+    // Channel source metadata, such as channel name, epg start and epg end are necessary
+    // for TV ad segment detection and application of ad strategies
+    const source = new ChannelSource(
+        'https://channel_prima_hd.m3u8',
+        {
+            // here put any additional metadata, for your use.
+            // This object will not be touched by Tivio
+        },
+        // channel name
+        // can also be prima hd, prima_hd, prima, Prima, PRIMA, etc.
+        // we will normalize it to snake case and add '_hd' if necessary
+        'Prima HD',
+        // program name
+        'Dr. House',
+        // description (optional)
+        'Episode about Dr. House being awesome',
+        // EPG start
+        new Date('2021-12-10T12:00:00'),
+        // EPG end
+        new Date('2021-12-10T13:40:00'),
+    )
+
+    // Send source to player
+    playerWrapper.onSourceChanged(source)
+
+    // Un-pause player
+    playerWrapper.play()
+
+    // Pause player
+    playerWrapper.pause()
+}
+```
+
+### Start reporting player events to Tivio
+
+``` javascript
+    // Report that source is playing
+    playerWrapper.onStateChanged('playing')
+
+    // Report that source is paused
+    playerWrapper.onStateChanged('paused')
+
+    // Report that source stopped playing
+    playerWrapper.onPlaybackEnded()
+    playerWrapper.onStateChanged('idle')
+
+    // Report video progress
+    playerWrapper.onTimeChanged(ms)
+}
+```
+
+### Start reporting playback-related errors to Tivio
+
+``` javascript
+    // Report that video failed to load (e.g. due to a wrong URI)
+    playerWrapper.onLoadError(new Error('video failed to load'))
+
+    // Report that video failed during playback (e.g. due to bad connection, corrupted chunks of stream video etc.)
+    // This type of error may be auto-recoverable
+    playerWrapper.onError(new Error('playback error'))
 }
 ```
 

package/dist/components/ContextProvider.d.ts

@@ -1,3 +1,8 @@
 import React from 'react';
-declare const ContextProvider: React.FC;
+import { RemoteBundleState } from '../services/bundleLoader';
+interface Props {
+    bundleState: RemoteBundleState;
+    children: any;
+}
+declare const ContextProvider: React.FC<Props>;
 export { ContextProvider, };

package/dist/components/context/index.d.ts

@@ -1,8 +1,5 @@
 export * from './ChannelsContext';
-export * from './OrganizationSubscriptionsContext';
-export * from './PurchasesWithVideosContext';
 export * from './ScreensContext';
 export * from './SectionsContext';
-export * from './UserContext';
 export * from './VideosContext';
 export * from './RowItemsContext';

package/dist/components/hooks/useOrganizationSubscriptions.d.ts

@@ -1,4 +1,3 @@
-declare const useOrganizationSubscriptions: () => {
+export declare const useOrganizationSubscriptions: () => {
     subscriptions: import("@tivio/common").Monetization[];
 };
-export { useOrganizationSubscriptions, };

package/dist/components/hooks/useUser.d.ts

@@ -1,5 +1,4 @@
-declare const useUser: () => {
+export declare const useUser: () => {
     user: import("@tivio/common/dist/types/externalTypes/user").User | null;
     error: string | null;
 };
-export { useUser, };