@tivio/sdk-react 9.3.1 → 9.5.0

package/README.md

@@ -52,6 +52,17 @@ await setUser('userId', { token: 'xxx'})
 await setUser(null)
 ```
 
+## Single Sign-On (SSO) across subdomains
+If you want to enable Single Sign-On (SSO) for all subdomains under the same parent domain, you can specify the customTokenCookiesDomain in the configuration object.
+``` javascript
+import type { Config } from '@tivio/sdk-react'
+
+const config: Config = {
+  // ... other required tivio config properties
+  customTokenCookiesDomain: 'example.com' // allows SSO across example.com, app.example.com, admin.example.com, etc.
+};
+```
+
 ### Create user with email and password
 
 Returns user's firebase uid or null if error occurs
@@ -302,7 +313,7 @@ watchHistory.forEach(watchPosition => {
 
 Simply call addToFavorites or removeFromFavorites on the Video or Tag.
 ```typescript
-const video = await tivio.getVideoById('videoId')   
+const video = await tivio.getVideoById('videoId')
 await video.addToFavorites()
 await video.removeFromFavorites()
 
@@ -315,7 +326,7 @@ const favorites = await tivio.getUser()?.favorites
 favorites[0]?.removeFromFavorites()
 ```
 
-> Note: When user saves favorite without profileId, it will only be shown if the app doesn't have any active user profile.
+> ℹ️ **_Note:_** When user saves favorite without profileId, it will only be shown if the app doesn't have any active user profile.
 
 ### Get screen by ID
 
@@ -582,10 +593,64 @@ The VideoController returned by `renderWebPlayer` provides the following methods
 
 The Tivio player supports different types of sources:
 
+**PathSourceParams** - Path-based sources with ad configuration
+- Used for playing Tivio-hosted videos and TV channels with custom VAST ad configurations
+- Supports both `videos/ID` and `tvChannels/ID` paths
+- Includes `staticAdsConfig` for custom VAST ad insertion 
+- Example usage:
+```typescript
+const sourceWithAds = {
+    path: 'videos/123', // or 'tvChannels/456'
+    staticAdsConfig: [
+        {
+            type: 'preroll',
+            url: 'https://example.com/vast-preroll-ad.xml',
+        },
+        {
+            type: 'midroll',
+            from: 30000, // 30 seconds
+            url: 'https://example.com/vast-midroll-ad.xml',
+        },
+        {
+            type: 'postroll',
+            url: 'https://example.com/vast-postroll-ad.xml',
+        },
+    ],
+}
+```
+
+**VOD_TIVIO** - Tivio-hosted video-on-demand content
+- Used for playing videos that are hosted within Tivio's infrastructure
+- Example usage:
+```typescript
+const vodSource = {
+    type: SourceType.VOD_TIVIO,
+    videoPath: 'videos/123', // Video path
+    sourcePlayMode: SourcePlayMode.ON_DEMAND,
+    name: 'Tivio Video',
+    autoplay: false,
+    continuePositionMs: 10000, // Start at 10 seconds (optional)
+}
+```
+
+**CHANNEL** - TV channel content (both classic and virtual channels)
+- Used for playing live TV channels
+- Example usage:
+```typescript
+const channelSource = {
+    type: SourceType.CHANNEL,
+    path: 'tvChannels/456', // TV channel path
+    sourcePlayMode: SourcePlayMode.LIVE,
+    name: 'TV Channel',
+    autoplay: true,
+}
+```
+
 **VOD_EXTERNAL** - External video-on-demand content from third-party URLs
 - Used for playing videos that are hosted outside of Tivio's infrastructure
 - Supports various streaming protocols (HLS, DASH, MP4)
-- Example usage:
+- Optionally, you can include `staticAdsConfig` for custom ad insertion
+- Example usage (single url):
 ```typescript
 const externalSource = {
     type: SourceType.VOD_EXTERNAL,
@@ -595,9 +660,137 @@ const externalSource = {
     name: 'External Video',
     autoplay: false,
     continuePositionMs: 10000, // Start at 10 seconds (optional)
+    staticAdsConfig: [
+        {
+            type: 'preroll',
+            url: 'https://example.com/preroll-ad.xml',
+        },
+        {
+            type: 'midroll',
+            from: 20000, // 20 seconds
+            url: 'https://example.com/midroll-ad.xml',
+        },
+    ],
 }
 ```
 
+**Path-Based Sources**
+You can also use simple path strings for both video and TV channel sources:
+```typescript
+// Video path
+videoController.setSource('videos/123')
+
+// TV channel path  
+videoController.setSource('tvChannels/456')
+```
+
+#### Static Ads Configuration
+
+> ℹ️ **_Note:_** To enable ad functionality, you must configure the IMA ad service in your Tivio configuration:
+> ```typescript
+> import { AD_SERVICE_PROXY_NAME } from '@tivio/sdk-react'
+> 
+> const config = {
+>     // ... other config properties
+>     player: {
+>         adService: {
+>             name: AD_SERVICE_PROXY_NAME.IMA,
+>         },
+>     },
+> }
+> ```
+
+The `staticAdsConfig` property lets you specify custom ad insertion points within your content.
+If multiple ads are set for the same entry point, they will be played one after another in sequence. For example, if you have two preroll ads, the first will play, followed by the second. Similarly, midroll ads that share the same `from` time will be grouped and played sequentially.
+
+It supports the following ad types:
+
+**Preroll Ads** - Play before the main content starts
+```typescript
+{
+    type: 'preroll',
+    url: 'https://example.com/preroll-ad.xml',
+}
+```
+
+**Midroll Ads** - Play during the main content at specified time
+```typescript
+{
+    type: 'midroll',
+    from: 30000, // Time in milliseconds (30 seconds)
+    url: 'https://example.com/midroll-ad.xml',
+}
+```
+
+**Postroll Ads** - Play after the main content ends
+```typescript
+{
+    type: 'postroll',
+    url: 'https://example.com/postroll-ad.xml',
+}
+```
+
+**Complete Example:**
+```typescript
+const sourceWithAds = {
+    path: 'videos/123',
+    name: 'Video with Multiple Ad Types',
+    staticAdsConfig: [
+        // multiple preroll ads
+        {
+            type: 'preroll',
+            url: 'https://vasterix.joj.sk/api/v1/creative?id=0c5d96fd-2ab9-4207-a325-4607437965e3&vast=4.0',
+        },
+        {
+            type: 'preroll',
+            url: 'https://example.com/preroll-ad.xml',
+        },
+        // multiple midroll ads (with same from time)
+        {
+            type: 'midroll',
+            from: 30000, // 30 seconds
+            url: 'https://example.com/midroll-ad-1.xml',
+        },
+        {
+            type: 'midroll',
+            from: 30000, // 30 seconds
+            url: 'https://example.com/midroll-ad-2.xml',
+        },
+        // one midroll ad with different from time
+        {
+            type: 'midroll',
+            from: 60000, // 1 minute
+            url: 'https://example.com/midroll-ad-2.xml',
+        },
+        // postroll ad
+        {
+            type: 'postroll',
+            url: 'https://example.com/postroll-ad.xml',
+        },
+    ],
+}
+```
+- It is also possible to set multiple urls for external source type, e.g. when you want to use both DASH and HLS formats. Player then automatically will pick most suitable format to play depending on device capabilities.
+- Example usage (multiple urls):
+```typescript
+const externalSource = {
+    type: SourceType.VOD_EXTERNAL,
+    urls: ['https://example.com/video.m3u8', 'https://example.com/video.mpd'],
+    sourcePlayMode: SourcePlayMode.ON_DEMAND,
+}
+```
+
+**VOD_TIVIO** - Internal source type for playing content managed by Tivio
+- Used for playing videos and tv channels managed by Tivio infrastructure, e.g. everything that is uploaded through Tivio Admin application
+- For convenience, it is recommended to use shortcut format and pass the source as string in `${'videos' | 'tvChannels'}/{id}` format
+- Ids of corresponding videos and tv channel could be found in Tivio admin application
+- Example usage:
+```typescript
+const tivioVideoSource = 'videos/2BzH4xsTXW8vqYKJegXj'
+const tivioTvChannelSource = 'tvChannels/Ct4UcK6ozX3VfxaL5yP5'
+```
+- Otherwise, it is also possible to pass internal tivio source as an object with `type: SourceType.VOD_TIVIO` and additional parameters, similarly to external source type.
+
 #### Source Play Modes
 
 The `sourcePlayMode` property determines how the content is played:
@@ -614,6 +807,23 @@ The `setSource` method allows you to dynamically change what's playing:
 // Change to a different video
 videoController.setSource('videos/newVideoId')
 
+// Change to a video with custom ads
+videoController.setSource({
+    path: 'videos/newVideoId',
+    name: 'Video with Ads',
+    staticAdsConfig: [
+        {
+            type: 'preroll',
+            url: 'https://example.com/preroll-ad.xml',
+        },
+        {
+            type: 'midroll',
+            from: 30000,
+            url: 'https://example.com/midroll-ad.xml',
+        },
+    ],
+})
+
 // Change to an external video
 videoController.setSource({
     type: SourceType.VOD_EXTERNAL,
@@ -625,6 +835,18 @@ videoController.setSource({
 // Change to a TV channel
 videoController.setSource('tvChannels/channelId')
 
+// Change to a TV channel with custom ads
+videoController.setSource({
+    path: 'tvChannels/channelId',
+    name: 'TV Channel with Ads',
+    staticAdsConfig: [
+        {
+            type: 'preroll',
+            url: 'https://example.com/tv-preroll-ad.xml',
+        },
+    ],
+})
+
 // Stop playback
 videoController.setSource(null)
 ```
@@ -645,6 +867,107 @@ The `setSource` method is particularly useful for:
 
 The VideoController emits various events that you can listen to:
 
+#### Ad events
+
+```typescript
+videoController.addEventListener('ad_started', (adMetadata: AdMetadata | null) => {
+    if (!adMetadata) {
+        console.log('Ad started playing (no metadata available)')
+        return
+    }
+
+    console.log('Ad started playing', adMetadata)
+
+    if ('customAdMetadata' in adMetadata && adMetadata.customAdMetadata) {
+        console.log('Ad custom metadata:', adMetadata.customAdMetadata)
+        // customAdMetadata contains VAST trafficking parameters (from VAST AdParameters tag)
+    }
+
+    // Access CTA element for rendering custom call-to-action buttons
+    const { ctaElement } = adMetadata
+    if (ctaElement) {
+        console.log('CTA element available for rendering custom buttons', ctaElement)
+
+        const { customAdMetadata } = adMetadata
+        if (!customAdMetadata) {
+            console.log('No custom ad metadata available')
+            return
+        }
+
+        const { extensions } = customAdMetadata
+        if (!extensions) {
+            console.log('No extensions available')
+            return
+        }
+
+        const { parameters } = extensions[0]
+        if (!parameters) {
+            console.log('No parameters available')
+            return
+        }
+
+        const metadataParameters = parameters as {
+            main_title?: string
+            subtitle?: string
+            image?: string
+            button_text: string
+            url: string
+        }
+
+        const buttonText = metadataParameters.button_text as string | undefined
+
+        if (!buttonText) {
+            console.log('No button text available')
+            return
+        }
+        
+        // Example: Create a custom CTA button using React portal
+        const CTAButton = () => (
+            <div style={{
+                position: 'absolute',
+                bottom: '20px',
+                right: '20px',
+                backgroundColor: 'rgba(0, 0, 0, 0.8)',
+                color: 'white',
+                padding: '12px 24px',
+                borderRadius: '6px',
+                cursor: 'pointer',
+                fontSize: '16px',
+                fontWeight: 'bold',
+                pointerEvents: 'auto',
+            }}>
+                Learn More
+            </div>
+        )
+        
+        // Render the CTA button using React portal
+        const root = ReactDOM.createRoot(ctaElement)
+        root.render(<CTAButton />)
+    }
+
+    // adMetadata contains information like:
+    // - ctaElement?: HTMLElement (for rendering custom CTA buttons)
+    // - customAdMetadata?: Record<string, unknown> (for IMA ads with rich metadata)
+    // - type: 'ad'
+    // - subType: 'inserted' | 'original'
+    // - secondsToEnd: number
+    // - secondsToSkippable: number | null
+    // - canTriggerSkip: boolean
+    // - isSkippable: boolean
+    // - order: number | null
+    // - totalCount: number | null
+    // - skip: () => void
+    // Update UI, show ad overlay, etc.
+})
+
+videoController.addEventListener('ad_ended', () => {
+    console.log('Ad finished playing')
+})
+```
+
+> ℹ️ **_Note:_** The CTA overlay element is visible in the WebPlayer only while an ad is playing and is automatically cleaned up on source changes.
+
+#### Video state changes
 ```typescript
 // Video state changes
 videoController.addEventListener('statechange', (state) => {
@@ -717,105 +1040,4 @@ The `WebPlayerProps` interface defines the properties that can be passed to the
 
 ### Visual Properties
 
-- **`showMarkers`** (optional, default: `false`): Whether to show video markers
-- **`markerColor`** (optional): Color for video markers (CSS color value)
-- **`showTvStreamType`** (optional): Whether to show TV stream type indicator
-- **`showCookiesSettings`** (optional): Whether to show cookies settings
-- **`showOsd`** (optional, default: `true`): Whether to show the On-Screen Display (OSD)
-- **`showBufferingSpinner`** (optional, default: `true`): Whether to show buffering spinner
-
-### Audio Properties
-
-- **`isMutedByDefault`** (optional): If `true`, the player starts muted but can be unmuted
-
-### Keyboard Shortcuts Properties
-
-- **`enableKeyboardShortcuts`** (optional, default: `true`): Whether to enable keyboard shortcuts
-- **`customShortcuts`** (optional): Custom keyboard shortcuts configuration:
-  ```typescript
-  {
-    toggleFullscreen: number[],    // Array of key codes
-    togglePause: number[],
-    toggleMute: number[],
-    jumpForward: number[],
-    jumpBack: number[],
-    volumeUp: number[],
-    volumeDown: number[]
-  }
-  ```
-
-### Ad Block Properties
-
-- **`checkAdBlock`** (optional, default: `false`): Whether to check for ad blockers and show warnings
-
-## Data hooks
-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<ItemInRow> | 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
-}
-```
+- **`showMarkers`