@tivio/sdk-react 3.1.4-alpha2 → 3.2.0

package/README.md

@@ -2,20 +2,17 @@
 
 ## Changelog
 
-* UNRELEASED
+* v3.2.0
   * minor: Added `capabilitiesOptions` for finer configuration of device capabilities
+  * minor: tag names are returned in correct language (the one from tivio config); language value should be one from enum "Language"
 * v3.1.3
   * patch: Hotfix made sure disabled Tivio does not break React Native
-  * internal: Fixed conf.bundleUrlOverride error handling
 * v3.1.2
   * patch: Allow `conf` prop of `TivioProvider` to be `null` or `undefined` in order to turn off Tivio
-  * internal: Added `runFeatureSupportCheck` to `TivioProvider`
 * v3.1.1
   * patch: fixed `setUser()` crash when bundle fails to load
 * v3.1.0
-  * internal: refactored `useAd`, `useAdSegment`
   * patch: `useAdSegment()` now returns null if no monetization is configured, ad segments are not managed in that situation
-  * internal: fixed refactored `setUser()`
   * minor: enriched `AdSegment` type from `useAdSegment()`
   * minor: Added `setUser()` function for login and logout
 * v3.0.0

package/README.md.bak

@@ -0,0 +1,517 @@
+# @tivio/sdk-react
+
+## Changelog
+
+* v3.2.0
+  * minor: Added `capabilitiesOptions` for finer configuration of device capabilities
+  * minor: tag names are returned in correct language (the one from tivio config); language value should be one from enum "Language"
+* v3.1.3
+  * patch: Hotfix made sure disabled Tivio does not break React Native
+  * internal: Fixed conf.bundleUrlOverride error handling
+* v3.1.2
+  * patch: Allow `conf` prop of `TivioProvider` to be `null` or `undefined` in order to turn off Tivio
+  * internal: Added `runFeatureSupportCheck` to `TivioProvider`
+* v3.1.1
+  * patch: fixed `setUser()` crash when bundle fails to load
+* v3.1.0
+  * internal: refactored `useAd`, `useAdSegment`
+  * patch: `useAdSegment()` now returns null if no monetization is configured, ad segments are not managed in that situation
+  * internal: fixed refactored `setUser()`
+  * minor: enriched `AdSegment` type from `useAdSegment()`
+  * minor: Added `setUser()` function for login and logout
+* v3.0.0
+  * minor: Added hook `useWatchWithoutAdsOffer` to trigger purchase dialog to "watch without ads", if available
+  * patch: fix peerDependency declaration for react, react-dom
+  * major: TivioProvider requires deviceCapabilities
+  * major: TivioProvider requires currency
+  * minor: add voucher support (see usePurchaseSubscription and useTransactionPayment hooks)
+  * minor: device limit support
+  * minor: drm (Widevine, PlayReady) support
+  * minor: watermarking support
+  * minor: add useSearch hook
+  * patch: price on video is 0 when purchased
+* 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`
+  * patch: added support for remote code on browsers that do not implement [indexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+  * patch: added support for browsers that do not implement [indexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+* v2.3.4
+  * patch: fix of usePurchaseSubscription not reactive
+* v2.3.3
+  * patch: fix of useUser not updating
+* v2.3.2
+  * patch: next app doesn't fail anymore due to "self is not defined"
+* v2.3.1
+  * patch: fix of @tivio/common dependency
+* v2.3.0
+  * minor: add useTaggedVideos that allows to fetch videos with given tags
+  * minor: add option to fetch tags (on hook useItemsInRow), useVideo always fetching videos tags
+* v2.2.1
+  * patch: disable Sentry when no config is supplied to `TivioProvider`
+* v2.2.0
+  * patch: reduced bundle size
+  * minor: disable Sentry when no config is supplied to `TivioProvider` or when Tivio is disabled `{ enable: false }`, or when Sentry is disabled via config `{ enableSentry: false }`
+* v2.1.5
+  * patch fix of `useVideosInSection` hook (fetching video's monetizations)
+* v2.1.4
+  * patch: fix re-rendering of `useAd` during non-skippable ads (requires core-react-dom@2.1.9)
+* v2.1.3
+  * patch: fix changelog
+* v2.1.2
+  * patch: Fixed exported types
+* v2.1.1
+  * patch: TivioWidget now correctly reports `false` via `onEnabled` callback when in invalid internal state
+* v2.1.0
+  * patch: fix of useItemsInRow hook
+  * patch: fix of useScreen hook
+  * add: useRowsInScreen hook
+* v2.0.3
+  * patch: fix of useItemsInRow hook
+* v2.0.2
+  * patch: screen and row IDs fixed
+      * `TivioBundle.subscriptions.subscribeToItemsInRow` now accepts user-defined ID via studio.tiv.io
+      * `TivioBundle.subscriptions.subscribeToScreen` now accepts user-defined ID via studio.tiv.io
+      * `Screen` and `Row` types returned by `useScreen()` return their user-defined IDs (`.id`) correctly
+* v2.0.1
+  * no changes
+* v2.0.0
+  * major: video.channelId can now be `string | null` used to be `string`
+  * minor: added data API and hooks for screens (screens, rows of screen and row items)
+    * hooks: `useScreen()`,  `useItemsInRow()`
+    * api: `TivioBundle.subscriptions.subscribeToScreen`,  `TivioBundle.subscriptions.subscribeToItemsInRow`
+* v1.3.6
+  * ?
+* v1.3.5
+  * minor: added WebPlayer props (canReplay, showMarkers, customShortcuts, enableKeyboardShortcuts, source.poster)
+* v1.3.4
+  * ...
+
+
+## Installation
+
+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
+
+Put Tivio Provider at the top level of your application:
+
+``` javascript
+import { TivioProvider } from '@tivio/sdk-react'
+
+const config = {
+    secret: 'XXXXXXXXXX',
+}
+
+function App({children}) {
+    return (
+        <TivioProvider conf={config}>
+           {children}
+        </TivioProvider>
+    )
+}
+```
+
+## Authentication
+
+A logged-in user can access more features, such as making purchases. In order to authenticate a user with Tivio, use the `setUser()` method.
+
+Verification of the user against 3rd party auth servers is implemented per customer.
+
+```typescript
+import { setUser } from '@tivio/sdk-react'
+
+// Log in
+
+// Payload is specific per customer
+// A common use-case is sending an auth token inside the payload, which Tivio can use to verify the user
+await setUser('userId', { token: 'xxx'})
+
+// Log out
+await setUser('userId', null)
+```
+
+## 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](https://studio.tiv.io/)):
+
+``` javascript
+import { TivioWidget } from '@tivio/sdk-react'
+
+function Screen() {
+    return (
+        <TivioWidget id="theWidgetId" />
+    )
+}
+```
+
+### Usage with smart TV navigation (focus control)
+
+``` javascript
+import { TivioWidget, TivioWidgetRef } from '@tivio/sdk-react'
+
+function Screen() {
+    const ref = useRef<TivioWidgetRef>(null)
+
+    return (
+        <TivioWidget id="theWidgetId" ref={ref} onBlur={() => {/* widget lost focus */}}/>
+        <div>
+            <button onClick={() => ref.current?.focus({ x: 100 })}>Focus</button>
+            <button onClick={() => ref.current?.unfocus()}>Unfocus</button>
+        </div>
+    )
+}
+```
+
+## Player wrapper
+
+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 { useTivioReadyData } from '@tivio/sdk-react'
+
+function CustomPlayer() {
+    const tivioData = useTivioReadyData()
+
+    useEffect(() => {
+        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'))
+}
+```
+
+## Tivio DOM events
+
+`TivioWidget` triggers these events on `window.document`.
+
+1. To instruct the parent app to navigate to and focus a specific TivioWidget (e.g. after going back from a Tivio screen)
+
+```typescript
+document.addEventListener("tivio_request_goto", e => {
+    e.detail.widgetId; // string - Tivio widget ID to go navigate to in UI
+});
+```
+2. To notify the parent app about context switch, i.e. where is the user located or what is he focusing
+
+```typescript
+document.addEventListener("tivio_context_switch", e => {
+    e.detail.context; // 'tivio' | 'parent' - where is the user located? - in Tivio or in parent app
+
+    // For context Tivio there are additional fields
+    e.detail.context; // 'tivio'
+    e.detail.contextLocation; // 'route' | 'overlay' | 'widget' - where in Tivio is the user located?
+    // - on a Tivio route, in parent app but looking at a full screen Tivio overlay,
+    // or in parent app and focus is on a Tivio widget
+
+    // For context Tivio contextLocation 'widget' there is an additional field of widget ID
+    e.detail.widgetId; // string - which Tivio widget is focused right now
+});
+```
+3. To notify the parent app about whether it should be handling key input from RC (TV remote) or not. When inputHandler is 'tivio', the parent app should stop reacting to key input, when inputHandler is 'parent' the parent app should start reacting again.
+
+```typescript
+document.addEventListener("tivio_key_input_handling_change", e => {
+    e.detail.inputHandler; // 'tivio' | 'parent' - who should be handling RC input? - Tivio or parent app
+});
+```
+
+## Data hooks
+
+If you don't want to use TivioWidget, you can implement your own UI using React data hooks.
+
+### useWidget hook
+
+Gets Widget object and subscribes to its changes.
+
+``` javascript
+/**
+ * Use widget
+ * @param widgetId - widget id
+ */
+useWidget: (widgetId: string) => {
+    error: string | null;
+    data: Widget | null;
+}
+```
+
+### useChannel hook
+
+Gets Channel object and subscribes to its changes.
+
+``` javascript
+/**
+ * Use channel
+ * @param channelId - channel id
+ */
+useChannel: (channelId: string) => {
+    error: string | null;
+    data: Channel | null;
+}
+```
+
+### useSection hook
+
+Gets Section object and subscribes to its changes.
+
+``` javascript
+/**
+ * Use section
+ * @param sectionId - section id
+ */
+useSection: (sectionId: string) => {
+    error: string | null;
+    data: Section | null;
+}
+```
+
+### useVideo hook
+
+Gets Video object and subscribes to its changes.
+
+``` javascript
+/**
+ * Use video
+ * @param videoId - video id
+ */
+useVideo: (videoId: string) => {
+    error: string | null;
+    data: Video | null;
+}
+```
+
+### useChannelsInWidget hook
+
+Gets array of Channel objects and subscribes to their changes. It is possible to use `hasNextPage` and `fetchMore`
+for pagination (returned in `data` object).
+
+``` javascript
+/**
+ * Use channels in widget
+ * @param widgetId - widget id
+ * @param [limit] - channels count, defaults to 10
+ */
+useChannelsInWidget: (widgetId: string, limit?: number) => {
+    error: string | null;
+    data: PaginationData<Channel> | null;
+}
+```
+
+### useSectionsInChannel hook
+
+Gets array of Section objects and subscribes to their changes. It is possible to use `hasNextPage` and `fetchMore`
+for pagination (returned in `data` object).
+
+``` javascript
+/**
+ * Use section in channel
+ * @param channelId - channel id
+ * @param [limit] - sections count, defaults to 10
+ */
+useSectionsInChannel: (channelId: string, limit?: number) => {
+    error: string | null;
+    data: PaginationData<Section> | null;
+}
+```
+
+### useVideosInSection hook
+
+Gets array of Video objects and subscribes to their changes. It is possible to use `hasNextPage` and `fetchMore`
+for pagination (returned in `data` object).
+
+``` javascript
+/**
+ * Use videos in section
+ * @param sectionId - section id
+ * @param [limit] - videos count, defaults to 10
+ */
+useVideosInSection: (sectionId: string, limit?: number) => {
+    error: string | null;
+    data: PaginationData<Video> | null;
+}
+```
+
+### useScreen hook
+Gets Screen object and subscribes to its changes.
+
+```ts
+/**
+ * Hook to fetch an app screen
+ * @param screenId - screen ID configured via studio.tiv.io
+ */
+useScreen: (screenId: string) => {
+    error: Error | null
+    data: Screen | null
+}
+
+// Example:
+// Screens with their screenIds are configured via studio.tiv.io
+const screenId = '890sdfvxoi'
+const { error, data } = useScreen(screenId)
+
+if (data) {
+    const screenName = data.name
+    const screenRows = data.rows
+    // ...
+}
+```
+
+### useItemsInRow hook
+
+Gets array of Video or Tag objects for a specified row. It is possible to use
+`hasNextPage` and `fetchMore` for pagination (returned in `data` object).
+
+*(Note: Does not subscribe to changes in video objects, in order to refresh data it is necessary to reload the app.)*
+
+```ts
+/**
+ * Hook to fetch row items for rows received from `useScreen()`
+ * @param id - row ID configured via studio.tiv.io
+ * @param options.limit - items limit
+ * @param options.noLimit - disable/enable pagination (will fetch all items)
+ * @param options.fecthTags - disable/enable tags fetching
+ */
+useItemsInRow: (id: string, options: {limit?: number, noLimit?: boolean, fecthTags?: boolean}) => {
+    error: Error | null
+    data: PaginationData<Video | Tag> | null
+    isLoading: boolean
+}
+
+// Example:
+// Rows and their row ID can be loaded using useScreen() hook
+const Row = ({ id }: { id: string}) => {
+    const rowData = useItemsInRow(id, 10)
+
+    return <div>
+        <div>Row id: {id}</div>
+        Count: ({rowData.data?.items.length})
+        <div>
+            {rowData.isLoading && <div>Loading...</div>}
+            {rowData.data?.items.map(item => (
+                <div>
+                    <div>{item.name}</div>
+                    <img src={item.cover} alt={item.name} />
+                </div>
+            ))}
+        </div>
+        <button onClick={() => rowData.data?.fetchMore()}>more</button>
+    </div>
+}
+```
+
+### useTaggedItems hook
+
+Allows to fetch videos with given tags.
+
+```ts
+/**
+ * Hook to fetch row items for rows received from `useScreen()`
+ * @param id - row ID configured via studio.tiv.io
+ * @param options.limit - items limit
+ * @param options.noLimit - disable/enable pagination (will fetch all items)
+ * @param options.fecthTags - disable/enable tags fetching
+ */
+useTaggedItems: (tagIds: string[], {limit?: number, noLimit?: boolean, fecthTags?: boolean}) => {
+    error: Error | null
+    data: PaginationData<Video> | null
+}
+
+
+# Deprecations
+- Video.url will be removed in version 3.0.0, use Video.uri attribute instead
+- Video.cover will be removed in version 3.0.0, use Video.assets attribute instead