@tivio/sdk-react 3.6.2 → 3.6.3

package/README.md

@@ -1,7 +1,14 @@
 # @tivio/sdk-react
 
+@tivio/sdk-react provides everything which is necessary (components, data hooks etc.) to build a custom React application
+above Tivio Studio. You can comfortably manage all you videos, settings such as application's screens and rows and also monetization
+settings in the administration of Tivio Studio while having the freedom to build your own application.
+
 ## Changelog
 
+* v3.6.3
+  * patch: improve README.md
+
 * v3.6.2
   * patch: Fix types
 
@@ -185,46 +192,51 @@ await setUser('userId', { token: 'xxx'})
 await setUser(null)
 ```
 
-## Tivio widget
+## Player
 
-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/)):
+You can choose whether you will use complete player component provided by Tivio or you will wrap your existing player
+with the Tivio Player Wrapper.
 
-``` javascript
-import { TivioWidget } from '@tivio/sdk-react'
+### Tivio Player component
 
-function Screen() {
-    return (
-        <TivioWidget id="theWidgetId" />
-    )
-}
-```
+```javascript
+import { useTivioData } from '@tivio/sdk-react'
 
-### Usage with smart TV navigation (focus control)
+const PlayerExample = () => {
+    const bundle = useTivioData()
 
-``` javascript
-import { TivioWidget, TivioWidgetRef } from '@tivio/sdk-react'
-
-function Screen() {
-    const ref = useRef<TivioWidgetRef>(null)
+    if (!bundle?.components?.WebPlayer) {
+        return <p>Loading...</p>
+    }
 
     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>
+        <>
+            <div
+                style={{
+                    height: 720,
+                    width: 1280,
+                }}
+            >
+                <bundle.components.WebPlayer
+                    id="player1"
+                    className="web-player"
+                    source="/videos/xxxxxxxxxxxxxxxxxxxx" // dynamically change this based on video you want to play
+                />
+            </div>
+        </>
     )
 }
 ```
 
-## Player wrapper
+### 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.
+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
+#### Wrap your player methods with Tivio player wrapper
 
-``` javascript
+```javascript
 import { useTivioReadyData } from '@tivio/sdk-react'
 
 function CustomPlayer() {
@@ -256,9 +268,9 @@ function CustomPlayer() {
 }
 ```
 
-### Start using Tivio player wrapper methods to control playback
+#### Start using Tivio player wrapper methods to control playback
 
-``` javascript
+```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(
@@ -292,9 +304,9 @@ function CustomPlayer() {
 }
 ```
 
-### Start reporting player events to Tivio
+#### Start reporting player events to Tivio
 
-``` javascript
+```javascript
     // Report that source is playing
     playerWrapper.onStateChanged('playing')
 
@@ -310,9 +322,9 @@ function CustomPlayer() {
 }
 ```
 
-### Start reporting playback-related errors to Tivio
+#### Start reporting playback-related errors to Tivio
 
-``` javascript
+```javascript
     // Report that video failed to load (e.g. due to a wrong URI)
     playerWrapper.onLoadError(new Error('video failed to load'))
 
@@ -322,87 +334,46 @@ function CustomPlayer() {
 }
 ```
 
-## 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.
+### useUser hook
+Gets information about current user.
 
-### 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;
+```ts
+useUser: () => {
+    user: User | null
+    error: string | null
+    isInitialized: boolean
 }
 ```
 
-### useChannel hook
-
-Gets Channel object and subscribes to its changes.
+### useRowsInScreen hook
+Gets array of Rows objects of specific screen and subscribes to its changes.
 
-``` javascript
+```ts
 /**
- * Use channel
- * @param channelId - channel id
+ * Use rows in screen
+ * @param screenId - screen id (from studio.tiv.io)
+ * @param options - subscription options
  */
-useChannel: (channelId: string) => {
-    error: string | null;
-    data: Channel | null;
+useRowsInScreen: (screenId: string, options?: PaginationOptions) => {
+    pagination: PaginationInterface<Row> | null
+    error: Error | null
 }
 ```
 
-### useSection hook
-
-Gets Section object and subscribes to its changes.
+### useItemsInRow hook
+Gets array of row items objects of specific row and subscribes to its changes.
 
-``` javascript
+```ts
 /**
- * Use section
- * @param sectionId - section id
+ * Use row items
+ * @param rowId - row ID
+ * @param options - subscription options
  */
-useSection: (sectionId: string) => {
-    error: string | null;
-    data: Section | null;
+useItemsInRow: (rowId: string, options?: SubscribeToItemsInRowOptions) => {
+    pagination: PaginationInterface<ItemsInRow> | null
+    error: Error | null
 }
 ```
 
@@ -410,7 +381,7 @@ useSection: (sectionId: string) => {
 
 Gets Video object and subscribes to its changes.
 
-``` javascript
+```ts
 /**
  * Use video
  * @param videoId - video id
@@ -421,139 +392,18 @@ useVideo: (videoId: string) => {
 }
 ```
 
-### 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.
+### useTaggedVideos hook
+Gets videos with given tag IDs.
 
 ```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
+ * Use tagged videos
+ * @param tagIds - tag ids
+ * @param options - subscription options
+ * @public
  */
-useTaggedItems: (tagIds: string[], {limit?: number, noLimit?: boolean, fecthTags?: boolean}) => {
+useTaggedVideos: (tagIds: string[], options?: SubscribeToItemsInRowOptions) => {
+    pagination: PaginationInterface<Video> | null
     error: Error | null
-    data: PaginationData<Video> | null
 }
 ```