@tivio/sdk-react 9.5.0 → 9.7.0

package/README.md

@@ -799,6 +799,56 @@ The `sourcePlayMode` property determines how the content is played:
 - **LIVE** - Live stream mode with no seeking
 - **HYBRID** - Combines LIVE with seeking
 
+#### User Authentication Callbacks
+
+The `userAuthCallbacks` property allows you to handle user authentication flows when the player requires user login or registration. This is particularly useful for content that requires authentication (e.g., premium content).
+
+```typescript
+interface UserAuthCallbacks {
+    onGoToLogin: () => void
+    onGoToRegistration: () => void
+}
+```
+
+**Example Implementation:**
+
+```typescript
+// Usage with renderWebPlayer
+const videoController = await renderWebPlayer(
+    document.getElementById('video-player'),
+    {
+        id: 'player-main',
+        source: 'videos/PREMIUM_VIDEO_ID',
+        userAuthCallbacks: {
+            onGoToLogin: () => {
+                // Show your login modal
+                setShowLoginModal(true)
+            },
+            onGoToRegistration: () => {
+                // Show your registration modal
+                setShowRegistrationModal(true)
+            },
+        },
+    }
+)
+
+// Handle login in your modal
+const handleLogin = async (email: string, password: string) => {
+    try {
+        await tivio.signInWithEmailAndPassword(email, password)
+        console.log('Login successful')
+    } catch (error) {
+        console.error('Login failed:', error)
+        throw error
+    }
+}
+```
+
+**When are these callbacks triggered?**
+
+- **`onGoToLogin`**: Called when the player is trying to play content behind a paywall and user clicks on the login button in the overlay
+- **`onGoToRegistration`**: Called when the player is trying to play content behind a paywall and user clicks on the registration button in the overlay
+
 #### Using setSource with VideoController
 
 The `setSource` method allows you to dynamically change what's playing:
@@ -870,7 +920,7 @@ The VideoController emits various events that you can listen to:
 #### Ad events
 
 ```typescript
-videoController.addEventListener('ad_started', (adMetadata: AdMetadata | null) => {
+videoController.addEventListener('ad-started', (adMetadata: AdMetadata | null) => {
     if (!adMetadata) {
         console.log('Ad started playing (no metadata available)')
         return
@@ -960,9 +1010,25 @@ videoController.addEventListener('ad_started', (adMetadata: AdMetadata | null) =
     // Update UI, show ad overlay, etc.
 })
 
-videoController.addEventListener('ad_ended', () => {
+videoController.addEventListener('ad-ended', () => {
     console.log('Ad finished playing')
 })
+
+// Companion ads event - fires when companion ads are available for the current ad
+videoController.addEventListener('companion-ads', (companionAds) => {
+    console.log('Companion ads available:', companionAds)
+    
+    // Access companion ad properties using IMA methods
+    companionAds.forEach((companionAd, index) => {
+        console.log(`Companion Ad ${index + 1}:`, {
+            width: companionAd.getWidth(),
+            height: companionAd.getHeight(),
+            contentType: companionAd.getContentType(),
+            // HTML content as string
+            content: companionAd.getContent()
+        })
+    })
+})
 ```
 
 > ℹ️ **_Note:_** The CTA overlay element is visible in the WebPlayer only while an ad is playing and is automatically cleaned up on source changes.
@@ -1040,4 +1106,105 @@ The `WebPlayerProps` interface defines the properties that can be passed to the
 
 ### Visual Properties
 
-- **`showMarkers`
+- **`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
+}
+```

package/README.md.bak

@@ -799,6 +799,56 @@ The `sourcePlayMode` property determines how the content is played:
 - **LIVE** - Live stream mode with no seeking
 - **HYBRID** - Combines LIVE with seeking
 
+#### User Authentication Callbacks
+
+The `userAuthCallbacks` property allows you to handle user authentication flows when the player requires user login or registration. This is particularly useful for content that requires authentication (e.g., premium content).
+
+```typescript
+interface UserAuthCallbacks {
+    onGoToLogin: () => void
+    onGoToRegistration: () => void
+}
+```
+
+**Example Implementation:**
+
+```typescript
+// Usage with renderWebPlayer
+const videoController = await renderWebPlayer(
+    document.getElementById('video-player'),
+    {
+        id: 'player-main',
+        source: 'videos/PREMIUM_VIDEO_ID',
+        userAuthCallbacks: {
+            onGoToLogin: () => {
+                // Show your login modal
+                setShowLoginModal(true)
+            },
+            onGoToRegistration: () => {
+                // Show your registration modal
+                setShowRegistrationModal(true)
+            },
+        },
+    }
+)
+
+// Handle login in your modal
+const handleLogin = async (email: string, password: string) => {
+    try {
+        await tivio.signInWithEmailAndPassword(email, password)
+        console.log('Login successful')
+    } catch (error) {
+        console.error('Login failed:', error)
+        throw error
+    }
+}
+```
+
+**When are these callbacks triggered?**
+
+- **`onGoToLogin`**: Called when the player is trying to play content behind a paywall and user clicks on the login button in the overlay
+- **`onGoToRegistration`**: Called when the player is trying to play content behind a paywall and user clicks on the registration button in the overlay
+
 #### Using setSource with VideoController
 
 The `setSource` method allows you to dynamically change what's playing:
@@ -870,7 +920,7 @@ The VideoController emits various events that you can listen to:
 #### Ad events
 
 ```typescript
-videoController.addEventListener('ad_started', (adMetadata: AdMetadata | null) => {
+videoController.addEventListener('ad-started', (adMetadata: AdMetadata | null) => {
     if (!adMetadata) {
         console.log('Ad started playing (no metadata available)')
         return
@@ -960,9 +1010,25 @@ videoController.addEventListener('ad_started', (adMetadata: AdMetadata | null) =
     // Update UI, show ad overlay, etc.
 })
 
-videoController.addEventListener('ad_ended', () => {
+videoController.addEventListener('ad-ended', () => {
     console.log('Ad finished playing')
 })
+
+// Companion ads event - fires when companion ads are available for the current ad
+videoController.addEventListener('companion-ads', (companionAds) => {
+    console.log('Companion ads available:', companionAds)
+    
+    // Access companion ad properties using IMA methods
+    companionAds.forEach((companionAd, index) => {
+        console.log(`Companion Ad ${index + 1}:`, {
+            width: companionAd.getWidth(),
+            height: companionAd.getHeight(),
+            contentType: companionAd.getContentType(),
+            // HTML content as string
+            content: companionAd.getContent()
+        })
+    })
+})
 ```
 
 > ℹ️ **_Note:_** The CTA overlay element is visible in the WebPlayer only while an ad is playing and is automatically cleaned up on source changes.
@@ -1040,4 +1106,105 @@ The `WebPlayerProps` interface defines the properties that can be passed to the
 
 ### Visual Properties
 
-- **`showMarkers`
+- **`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
+}
+```