@tivio/sdk-react 3.0.0-alpha2 → 3.1.0

package/README.md

@@ -1,7 +1,17 @@
 # @tivio/sdk-react
 
 ## Changelog
-* v3.0.0-alpha1
+
+* UNRELEASED
+* v3.1.0
+  * patch: internal refactored `useAd`, `useAdSegment`
+  * patch: `useAdSegment()` now returns null if no monetization is configured, ad segments are not managed in that situation
+  * patch: 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)
@@ -10,6 +20,15 @@
   * 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
@@ -29,7 +48,7 @@
 * 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@2.1.9)
+  * 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
@@ -61,16 +80,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
@@ -80,42 +97,42 @@ 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>
     )
 }
 ```
 
-### Usage with authorization
+## Authentication
 
-``` javascript
-import { TivioProvider, setUser } from '@tivio/sdk-react'
+A logged-in user can access more features, such as making purchases. In order to authenticate a user with Tivio, use the `setUser()` method.
 
-const tivioConf = {
-    secret: 'XXXXXXXXXX',
-}
+Verification of the user against 3rd party auth servers is implemented per customer.
 
-setUser('user-id', { some: 'payload' })
+```typescript
+import { setUser } from '@tivio/sdk-react'
 
-function App({children}) {
-    return (
-        <TivioProvider conf={tivioConf}>
-           {children}
-        </TivioProvider>
-    )
-}
+// 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):
+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'
@@ -144,48 +161,146 @@ 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'))
 }
 ```
 
+## 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.

package/dist/components/PlayerProvider.d.ts

@@ -3,11 +3,17 @@
  * nangu.TV, a.s PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  */
 import React, { FunctionComponentElement } from 'react';
+import type { PlayerWrapper } from '../types/customPlayer.types';
 export declare type PlayerProviderProps = {
     children: React.ReactNode;
     playerWrapperId?: string;
 };
-export declare type Player = any;
-export declare const PlayerContext: React.Context<any>;
+/**
+ * value
+ *  - undefined - you are trying to access this context but are not inside <PlayerContext /> that is a bug
+ *  - null - we are waiting for remote code
+ *  - Player - player is ready
+ */
+export declare const PlayerContext: React.Context<PlayerWrapper | null | undefined>;
 export declare const PlayerProvider: ({ children, playerWrapperId, }: PlayerProviderProps) => FunctionComponentElement<PlayerProviderProps>;
 export declare function withPlayerContext(id: string): <P>(WrappedComponent: React.ComponentType<P>) => (props: P) => JSX.Element;

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

@@ -13,4 +13,7 @@ export * from './useOrganizationSubscriptions';
 export * from './usePurchasesWithVideos';
 export * from './useFreePurchase';
 export * from './useRowsInScreen';
+export * from './useVoucher';
 export * from './useTivio';
+export * from './useLastVideoByWidgetId';
+export * from './useWatchWithoutAdsOffer';

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

@@ -2,7 +2,7 @@
  * Copyright (c) 2021, nangu.TV, a.s. All rights reserved.
  * nangu.TV, a.s PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  */
-import type { AdSource, UsePlayerEvent } from '../../types/customPlayer.types';
+import type { UsePlayerEvent } from '../../types/customPlayer.types';
 import type { BetOffer, Marker } from '../../types/types';
 export declare const usePlayerEvent: UsePlayerEvent;
 export declare const useMarkers: () => Marker[] | null;
@@ -12,12 +12,17 @@ interface IntroMarker {
     skip: () => void;
 }
 export declare const useIntro: () => IntroMarker | null;
-export declare const useAd: () => AdSource | null;
+export declare const useAd: () => import("../../types/customPlayer.types").AdSource | null;
 export declare const useCurrentMarker: () => Marker | null;
 export declare const useSeekState: () => boolean | null;
-interface AdSegment {
+export declare const useAdSegment: () => {
+    id: string;
     remainingMs: number;
+    secondsToEnd: number;
+    secondsToSkippable: number | null;
     canSeek: boolean;
-}
-export declare const useAdSegment: () => AdSegment | null;
+    canSkip: boolean;
+    isSkippable: boolean;
+    skip: () => any;
+} | null;
 export {};

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

@@ -1,11 +1,11 @@
-import { PaginationInterface, SubscribeToItemsInRowOptions, Tag, Video } from '@tivio/common';
+import { ItemsInRow, PaginationInterface, SubscribeToItemsInRowOptions } from '@tivio/common';
 /**
  * Use row items
  * @param rowId - row ID
  * @param options - subscription options
  */
 declare const useItemsInRow: (rowId: string, options?: SubscribeToItemsInRowOptions) => {
-    pagination: PaginationInterface<Video | Tag> | null;
+    pagination: PaginationInterface<ItemsInRow> | null;
     error: Error | null;
 };
 export { useItemsInRow, };

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

@@ -0,0 +1,2 @@
+import { Video } from '@tivio/common';
+export declare function useLastVideoByWidgetId(widgetId: string): Video | null;

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

@@ -1,4 +1,4 @@
 import { QerkoTransaction } from '@tivio/common';
-import { Voucher } from './useTransactionPayment';
-declare const usePurchaseSubscription: (monetizationId: string, voucher?: Voucher | undefined) => QerkoTransaction;
+import { NewVoucher } from './useTransactionPayment';
+declare const usePurchaseSubscription: (monetizationId: string, voucher?: NewVoucher | undefined) => QerkoTransaction;
 export { usePurchaseSubscription, };

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

@@ -1,10 +1,10 @@
 import { QerkoTransaction } from '@tivio/common';
-declare type Voucher = {
-    /**
-     * Voucher expiration date as a Date object or timestamp in ms.
-     */
+/**
+ * TODO: Duplicate, because we can't import types from core-js.
+ */
+declare type NewVoucher = {
     expirationDate: Date | number;
 };
-declare const useTransactionPayment: (videoId: string, monetizationId: string, voucher?: Voucher | undefined) => QerkoTransaction;
+declare const useTransactionPayment: (videoId: string, monetizationId: string, voucher?: NewVoucher | undefined) => QerkoTransaction;
 export { useTransactionPayment, };
-export type { Voucher, };
+export type { NewVoucher, };

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

@@ -0,0 +1,16 @@
+/**
+ * TODO: Should be in core-js, we can't import types from it, though.
+ */
+declare type Voucher = {
+    activate: () => void;
+    isUsed: boolean;
+    isExpired: boolean;
+    status: 'NEW' | 'USED';
+    voucherInfo: any;
+};
+declare const useVoucher: (voucherId: string) => {
+    activate: (() => Promise<void>) | null;
+    voucher: Voucher | null;
+    error: Error | null;
+};
+export { useVoucher, };

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

@@ -0,0 +1,4 @@
+export declare const useWatchWithoutAdsOffer: () => {
+    canPurchaseWatchWithoutAds: boolean;
+    showPurchaseDialog: () => void;
+};

package/dist/index.d.ts

@@ -23,3 +23,4 @@ export { TivioGetters } from './types/bundle.types';
 export { TivioSubscriptions } from './types/bundle.types';
 export { PlayerCapability } from './types/bundle.types';
 export { Currency } from './types/bundle.types';
+export { setUser } from './services/login';