@tivio/sdk-react 5.0.0 → 5.0.2

package/{changelog.md → README.md.bak}

@@ -1,4 +1,16 @@
-# Changelog @tivio/sdk-react
+# @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
+
+* 5.0.2
+    * patch: export hook useChannelSource
+
+* 5.0.1
+    * patch: move changelog
 
 * 5.0.0
     * major: upgrade to React 18, change react and react-dom peer dependencies to 17.x || 18.x
@@ -9,20 +21,20 @@
     * minor: add uri property to tv channel type
     * minor: add useChannelSource to hooks
 
-* v4.5.0
+* 4.5.0
     * minor: extend PurchaseEndpointPayload type with purchase previousStatus and newStatus fields
 
-* v4.4.1
+* 4.4.1
     * patch: added waitForTags param in useSearch hook for videos
 
-* v4.4.0
+* 4.4.0
     * minor: PrimaryButton component props type set to any for now
     * patch: isPurchasableAsVoucher added to PurchasableMonetization
     * patch: voucherPurchase flag added to purchase overlays
     * patch: item added to MonetizationsSelectOverlayData
     * minor: added hungarian language to `LangCode` enum
 
-* v4.3.0:
+* 4.3.0:
     * minor: add GetPurchaseInfoResponse and PurchaseEndpointPayload to exported types
     * minor: support for disabling purchase of specified subscriptions (new param in useOrganizationSubscriptions hook)
     * minor: more specific PurchasableMonetization type usage instead of Monetization
@@ -30,22 +42,22 @@
     * minor: monetization now has originalPrice and promotion properties available
     * patch: remove not used OrganizationSubscriptionsContext, **this change requires bundle 3.20.0 or newer**
 
-* v4.2.0:
+* 4.2.0:
     * minor: fix useSearch loading type
     * patch: added italian language to `LangCode` enum
 
-* v4.1.0
+* 4.1.0
     * patch: added italian language to `LangCode` enum
     * minor: fixed spanish language code in `LangCode` enum (`sp` -> `es`)
     * minor: other misc type changes
 
-* v4.0.1
+* 4.0.1
     * patch: added setBundleVersion setter to bundle type
     * patch: added setStorageManager setter to bundle type
     * patch: `Purchase.isPurchased` is deprecated
     * patch: fill `useSearch` field `hasNextPage` with proper value
 
-* v4.0.0
+* 4.0.0
     * minor: Types cleanup
     * MAJOR: Remove deprecated and unused stuff
         * auth
@@ -56,7 +68,7 @@
             * initializeUser
             * createFreePurchase
         * components
-            * VideoAdBanner
+            * videoAdBanner
         * getters
             * getExportedConfig
             * getChannelById
@@ -83,76 +95,76 @@
 ---
 _Versions <= v3.7.0 requires core-react-dom bundle < v3.0.0 (because sdk-react used some sdk API deleted in core-react-dom@4.0.0)_
 
-* v3.7.0
+* 3.7.0
     * minor: purchase contains created and updated
 
-* v3.6.3
+* 3.6.3
     * patch: improve README.md
 
-* v3.6.2
+* 3.6.2
     * patch: Fix types
 
-* v3.6.1
+* 3.6.1
     * patch: Fix README
 
-* v3.6.0
+* 3.6.0
     * minor: Update types
 
-* v3.5.2
+* 3.5.2
     * patch: All types are available again.
 
-* v3.5.1
+* 3.5.1
     * patch: remove incorrect dependency (@tivio/types)
 
-* v3.5.0
+* 3.5.0
     * minor: Types change - Video.price and Video.detailedPrice can be null
     * minor: Types change - Video.cover is marked as deprecated
 
-* v3.4.0
+* 3.4.0
     * minor: more precise type for errors in usePurchaseRecovery and usePurchaseRecovery
     * patch: jsdocs for usePurchaseRecovery and usePurchaseRecovery
     * minor: inviteCodeReset in useApplyInviteCode
     * minor: Reset forgotten password
     * minor: Consolidating monetization logic
-* v3.3.2
+* 3.3.2
     * patch: Adding new optional parameters (where, orderBy) to useTaggedVideos hook
-* v3.3.1
+* 3.3.1
     * patch: Fixed types of `setUser`
-* v3.3.0
+* 3.3.0
     * minor: Add getPlayerCapabilities to getters.
     * patch: Added option to log out via `setUser(null)`, requires @tivio/core-react-dom@2.17.9
-* v3.2.5
+* 3.2.5
     * patch: added recovery flag to QerkoPaymentInfo type
     * patch: bundle.types changes - internal.components.WebVideoScreen
     * patch: types changes - add new onBack prop to WebPlayerProps
     * patch: Refactor useVideo hook, now uses hook from core-react
-* v3.2.4
+* 3.2.4
     * minor: added useApplyInviteCode
     * minor: better errors from useVoucher
-* v3.2.3
+* 3.2.3
     * minor: added usePurchaseRecovery hook
     * patch: deprecated `useLastVideoByWidgetId`
-* v3.2.2
+* 3.2.2
     * minor: useRowsInScreen, useItemsInRow, useTaggedVideos - hasNextPage and loading added to pagination
     * minor: useRowsInScreen, useItemsInRow, useTaggedVideos - implementation moved to remote bundle
     * patch: Fixed Tivio startup on Tizen 6
     * minor: Added `forceCloudFnResolver` option
-* v3.2.1
+* 3.2.1
     * patch: fix of @tivio/common version
-* v3.2.0
+* 3.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 "LangCode"
-* v3.1.3
+* 3.1.3
     * patch: Hotfix made sure disabled Tivio does not break React Native
-* v3.1.2
+* 3.1.2
     * patch: Allow `conf` prop of `TivioProvider` to be `null` or `undefined` in order to turn off Tivio
-* v3.1.1
+* 3.1.1
     * patch: fixed `setUser()` crash when bundle fails to load
-* v3.1.0
+* 3.1.0
     * patch: `useAdSegment()` now returns null if no monetization is configured, ad segments are not managed in that situation
     * minor: enriched `AdSegment` type from `useAdSegment()`
     * minor: Added `setUser()` function for login and logout
-* v3.0.0
+* 3.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
@@ -163,62 +175,326 @@ _Versions <= v3.7.0 requires core-react-dom bundle < v3.0.0 (because sdk-react u
     * minor: watermarking support
     * minor: add useSearch hook
     * patch: price on video is 0 when purchased
-* v2.4.2
+* 2.4.2
     * patch: added back changelog
-* v2.4.1
+* 2.4.1
     * patch: improved doc about player wrapper
-* v2.4.0
+* 2.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
+* 2.3.4
     * patch: fix of usePurchaseSubscription not reactive
-* v2.3.3
+* 2.3.3
     * patch: fix of useUser not updating
-* v2.3.2
+* 2.3.2
     * patch: next app doesn't fail anymore due to "self is not defined"
-* v2.3.1
+* 2.3.1
     * patch: fix of @tivio/common dependency
-* v2.3.0
+* 2.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
+* 2.2.1
     * patch: disable Sentry when no config is supplied to `TivioProvider`
-* v2.2.0
+* 2.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
+* 2.1.5
     * patch fix of `useVideosInSection` hook (fetching video's monetizations)
-* v2.1.4
+* 2.1.4
     * patch: fix re-rendering of `useAd` during non-skippable ads (requires core-react-dom@2.1.9)
-* v2.1.3
+* 2.1.3
     * patch: fix changelog
-* v2.1.2
+* 2.1.2
     * patch: Fixed exported types
-* v2.1.1
+* 2.1.1
     * patch: TivioWidget now correctly reports `false` via `onEnabled` callback when in invalid internal state
-* v2.1.0
+* 2.1.0
     * patch: fix of useItemsInRow hook
     * patch: fix of useScreen hook
     * add: useRowsInScreen hook
-* v2.0.3
+* 2.0.3
     * patch: fix of useItemsInRow hook
-* v2.0.2
+* 2.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
+* 2.0.1
     * no changes
-* v2.0.0
+* 2.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
+* 1.3.6
     * ?
-* v1.3.5
+* 1.3.5
     * minor: added WebPlayer props (canReplay, showMarkers, customShortcuts, enableKeyboardShortcuts, source.poster)
-* v1.3.4
+* 1.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(null)
+```
+
+## Player
+
+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.
+
+### Tivio Player component
+
+```javascript
+import { useTivioData } from '@tivio/sdk-react'
+
+const PlayerExample = () => {
+    const bundle = useTivioData()
+
+    if (!bundle?.components?.WebPlayer) {
+        return <p>Loading...</p>
+    }
+
+    return (
+        <>
+            <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 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'))
+}
+```
+
+## Data hooks
+
+### useUser hook
+Gets information about current user.
+
+```ts
+useUser: () => {
+    user: User | null
+    error: string | null
+    isInitialized: boolean
+}
+```
+
+### useRowsInScreen hook
+Gets array of Rows objects of specific screen and subscribes to its changes.
+
+```ts
+/**
+ * Use rows in screen
+ * @param screenId - screen id (from studio.tiv.io)
+ * @param options - subscription options
+ */
+useRowsInScreen: (screenId: string, options?: PaginationOptions) => {
+    pagination: PaginationInterface<Row> | null
+    error: Error | null
+}
+```
+
+### useItemsInRow hook
+Gets array of row items objects of specific row and subscribes to its changes.
+
+```ts
+/**
+ * Use row items
+ * @param rowId - row ID
+ * @param options - subscription options
+ */
+useItemsInRow: (rowId: string, options?: SubscribeToItemsInRowOptions) => {
+    pagination: PaginationInterface<ItemsInRow> | null
+    error: Error | null
+}
+```
+
+### useVideo hook
+
+Gets Video object and subscribes to its changes.
+
+```ts
+/**
+ * Use video
+ * @param videoId - video id
+ */
+useVideo: (videoId: string) => {
+    error: string | null;
+    data: Video | null;
+}
+```
+
+### useTaggedVideos hook
+Gets videos with given tag IDs.
+
+```ts
+/**
+ * Use tagged videos
+ * @param tagIds - tag ids
+ * @param options - subscription options
+ * @public
+ */
+useTaggedVideos: (tagIds: string[], options?: SubscribeToItemsInRowOptions) => {
+    pagination: PaginationInterface<Video> | null
+    error: Error | null
+}
+```

package/dist/index.d.ts

@@ -2899,6 +2899,16 @@ export declare type UseChannelSource = (tvChannelId: string) => {
     error: Error | null;
 };
 
+/**
+ * Use channel source
+ * @param tvChannelId
+ * @public
+ */
+export declare const useChannelSource: (tvChannelId: string) => {
+    source: ChannelSourcePojo | null;
+    error: Error | null;
+};
+
 /**
  * @public
  */