@tivio/sdk-react 9.7.0 → 9.8.0

package/README.md.bak

@@ -203,21 +203,44 @@ user.deleteUserProfile(profileId: string): Promise<void>
 
 ## Content
 
-### Assets
+### Tiles and assets
 
-In order to obtain assets (images) from a Video or Tag, you can use these methods:
+A **tile** is a single item rendered inside a content row. The tile is the
+same entity the row points to (a `Video`, `Tag`, `TvChannel`, `Series`,
+`Article` or `Application`), so anything you can read off the entity (name,
+description, ids, monetization flags, …) is also available directly on the
+tile returned by `useItemsInRow` / `row.tiles`.
 
-#### Video or Tag
-- `video.cover` - cover image (landscape)
-- `video.banner` - banner image
-- `video.circled` - circled image
-- `video.detailBanner` - detail banner image (landscape)
-- `video.portrait` - portrait image (portrait)
+Each tile carries several named image **assets** so the same entity can be
+rendered in different shapes without an extra fetch. Every named getter is a
+shortcut into the underlying `tile.assets` map — use the map directly if you
+need a custom asset that does not have a dedicated getter.
 
-#### Tag only
-- `tag.bannerMobile` - banner image mobile
+**Shared across all entity types**
 
-__All of the assets fallback to type cover or empty string if cover is not available__
+- `tile.landscape` — 16:9 thumbnail (standard rows)
+- `tile.portrait` — 2:3 poster (portrait rows)
+- `tile.circled` — 1:1 circular crop (e.g. creators)
+- `tile.square` — 1:1 square (square rows)
+- `tile.banner` — 16:9 hero banner (banner rows / top of screens)
+- `tile.bannerMobile` — narrow 16:9 banner variant for phones
+- `tile.assets` — raw `{ [assetName]: ScalableAsset }` map behind the getters
+
+**Extras by entity type (on top of the shared set above)**
+
+- `Video` — `detailBanner` (backdrop above the player), `image`, `cover`
+  (deprecated, kept for compatibility), `backgroundBlurBannerMobile`
+- `Tag` / `Article` / `Series` — `detailBanner`, `cover`
+- `TvChannel` — `logo`, `logoPendingOverlayWidth`, `cover`
+- `Application` — read via `tile.application`: `logo`, `logoLandscape`,
+  `profilePhoto`
+
+If an asset is not set on the entity, the getter returns `null` rather than
+throwing, so it's safe to fall back from a specific variant to a more
+generic one (for example `tile.landscape ?? tile.banner ?? tile.cover`).
+
+A live example that renders the same video through every getter is included
+in `examples/sdk-react/src/index.tsx` (`createAssetsShowcaseDemo`).
 
 ### Get content based on user profile
 
@@ -326,6 +349,19 @@ const favorites = await tivio.getUser()?.favorites
 favorites[0]?.removeFromFavorites()
 ```
 
+### Add to/remove from favorites by path
+
+You can also add or remove favorites using content paths directly:
+```typescript
+// Add to favorites by path
+await tivio.addToFavoritesByPath('videos/videoId')
+await tivio.addToFavoritesByPath('tags/tagId')
+
+// Remove from favorites by path
+await tivio.removeFromFavoritesByPath('videos/videoId')
+await tivio.removeFromFavoritesByPath('tags/tagId')
+```
+
 > ℹ️ **_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
@@ -799,6 +835,22 @@ The `sourcePlayMode` property determines how the content is played:
 - **LIVE** - Live stream mode with no seeking
 - **HYBRID** - Combines LIVE with seeking
 
+#### Player Authentication Configuration
+
+Use `disableTvChannelsForAnonymousUsers` property to show overlay to sign in when user is anonymous and tries to play a TV channel (free or monetized).
+Set the property to `true` inside the `player` property in Tivio config.
+
+Tivio config:
+```typescript
+const config = {
+    // ... other config properties
+    player: {
+        // ... other player properties
+        disableTvChannelsForAnonymousUsers: true, // or false
+    },
+}
+```
+
 #### 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).
@@ -906,11 +958,115 @@ The `setSource` method is particularly useful for:
 - Implementing playlists
 - Dynamic content loading
 
+#### Minimal OSD / Sticky Mini Player
+
+The player supports a minimal OSD mode designed for small or pinned containers such as a
+scroll-fixed "mini" player. When enabled, only the essential controls are rendered:
+
+- `play` / `pause` (small button in the bottom-left corner)
+- `volume`
+- `fullscreen`
+
+The mode can be toggled in two ways:
+
+1. Declaratively, via the `isMinimal` prop on `WebPlayerProps`.
+2. Imperatively, via the vanilla controller's `setIsMinimal(isMinimal: boolean)` method — useful
+   for switching on/off at runtime (e.g. when the player becomes pinned after the user scrolls
+   past it).
+
+**Example: scroll-pinned mini player**
+
+The layout is driven entirely by CSS — the JS only toggles an `is-floating` class and calls
+`setIsMinimal(true|false)` accordingly. Responsive behavior (desktop corner vs. mobile
+top-full-width) is handled with a media query, so there is no need to watch viewport size from
+React/JS.
+
+```html
+<section class="mini-player-demo">
+    <div class="mini-player-anchor">
+        <div class="mini-player" id="mini-player"></div>
+    </div>
+    <!-- ...page content... -->
+</section>
+```
+
+```css
+.mini-player-anchor {
+    position: relative;
+    width: 100%;
+    aspect-ratio: 16 / 9;
+}
+
+.mini-player {
+    position: absolute;
+    inset: 0;
+    background: #000;
+}
+
+/* Floating (desktop): pinned to bottom-right. */
+.mini-player.is-floating {
+    position: fixed;
+    inset: auto 24px 24px auto;
+    width: 360px;
+    aspect-ratio: 16 / 9;
+    z-index: 1000;
+    border-radius: 8px;
+    overflow: hidden;
+    box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
+}
+
+/* Floating (narrow viewports): pinned to top, full width. */
+@media (max-width: 600px) {
+    .mini-player.is-floating {
+        inset: 0 0 auto 0;
+        width: 100%;
+        border-radius: 0;
+    }
+}
+```
+
+```ts
+import { renderWebPlayer } from '@tivio/sdk-react'
+
+const container = document.getElementById('mini-player')!
+const anchor = document.querySelector('.mini-player-anchor')!
+
+const controller = await renderWebPlayer(container, {
+    id: 'mini-player',
+    source: 'videos/YOUR_VIDEO_ID',
+    isSameSizeAsParent: true,
+    isMutedByDefault: true,
+    autoplay: true,
+})
+
+// Pop out of the flow once the inline anchor leaves the viewport,
+// and switch the OSD between minimal and default accordingly.
+new IntersectionObserver(
+    ([entry]) => {
+        const isFloating = !entry.isIntersecting
+        container.classList.toggle('is-floating', isFloating)
+        controller.setIsMinimal(isFloating)
+    },
+    { threshold: 0.1 },
+).observe(anchor)
+```
+
+Notes:
+- The anchor stays in the flow with its original 16:9 size, so the page layout does not jump
+  when the player detaches.
+- The desktop/mobile floating layout is fully CSS-driven; resizing the browser window
+  updates it live with no extra JS.
+
+You can see this pattern in action in `examples/sdk-react/src/index.tsx` (the
+`createStickyMiniPlayerDemo` function) with styles in `examples/sdk-react/src/index.css`.
+
 **Event Handling:**
 - `addEventListener(event: string, callback: (value: T) => void)` - Add event listener
 - `removeEventListener(event: string, callback: (value: T) => void)` - Remove event listener
 
 **Utility:**
+- `setIsMinimal(isMinimal: boolean)` - Toggle the minimal OSD mode at runtime (see
+  [Minimal OSD / Sticky Mini Player](#minimal-osd--sticky-mini-player))
 - `destroy()` - Destroy player and clean up resources
 
 #### Playback Events
@@ -1111,6 +1267,11 @@ The `WebPlayerProps` interface defines the properties that can be passed to the
 - **`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)
+- **`isMinimal`** (optional, default: `false`): If `true`, the player uses a minimal OSD that
+  exposes only `play`/`pause`, `volume` and `fullscreen` controls. A small center play/pause
+  icon flashes briefly when the state toggles and then fades out.
+  Designed for small/pinned containers such as scroll-fixed mini players. See
+  [Minimal OSD / Sticky Mini Player](#minimal-osd--sticky-mini-player) for usage details.
 - **`showBufferingSpinner`** (optional, default: `true`): Whether to show buffering spinner
 
 ### Audio Properties

package/dist/index.d.ts

@@ -104,6 +104,7 @@ export declare type AdMetadata = {
     isSkippable: boolean;
     order: number | null;
     totalCount: number | null;
+    adPlacementStrategy: AdPlacementStrategy;
     customAdMetadata?: Record<string, unknown>;
     skip: () => void;
 } | null;
@@ -118,7 +119,10 @@ export declare interface AdPackInfo {
     total: number;
 }
 
+export declare type AdPlacementStrategy = 'preroll' | 'midroll' | 'postroll' | 'replacement';
+
 export declare interface AdSegment {
+    adPlacementStrategy: AdPlacementStrategy;
     id: string;
     /**
      * @deprecated alias to secondsToEnd * 1000
@@ -183,6 +187,7 @@ export declare interface AdSourceActions {
  */
 export declare interface AdSourceInterface extends CommonSourceInterface<SourceType.ADVERTISEMENT> {
     adType: AdType;
+    adPlacementStrategy: AdPlacementStrategy;
     durationMs: number;
     skipDelayMs: number | null;
     /**
@@ -233,6 +238,7 @@ export declare interface AdSourceInterface extends CommonSourceInterface<SourceT
  */
 export declare interface AdSourceParams extends CommonSourceParams<SourceType.ADVERTISEMENT> {
     id: string;
+    adPlacementStrategy: AdPlacementStrategy;
     adType?: AdType;
     actions?: AdSourceActions | null;
     apiFramework?: VastApiFramework | null;
@@ -737,6 +743,7 @@ export declare interface ChannelSourceInterface extends PlayerSourceInterface<So
     to: Date;
     poster: string | null;
     tvMode: TvMode | 'live' | null;
+    clone: (params?: Partial<ChannelSourceParams>) => ChannelSourceInterface;
 }
 
 /**
@@ -1319,6 +1326,9 @@ export declare interface DidomiWindow {
      * https://developers.didomi.io/cmp/web-sdk/reference/api
      */
     didomiOnReady: (() => void)[];
+    Didomi?: {
+        getUserConsentStatusForPurpose: (category: string) => boolean;
+    };
 }
 
 /**
@@ -1643,7 +1653,8 @@ export declare enum ForbiddenReason {
     NAME_CONTAINS_INVALID_CHAR = "NAME_CONTAINS_INVALID_CHAR",
     USER_ACCOUNT_LOCKED = "USER_ACCOUNT_LOCKED",
     USER_NOT_FOUND = "USER_NOT_FOUND",
-    UNSUPPORTED_BROWSER = "UNSUPPORTED_BROWSER"
+    UNSUPPORTED_BROWSER = "UNSUPPORTED_BROWSER",
+    ANONYMOUS_USER = "ANONYMOUS_USER"
 }
 
 /**
@@ -1869,6 +1880,10 @@ export declare interface GetSourceUrlResponse {
      * Determines session type generated for source. If no provided it will be considered 'ondemand' session type.
      */
     sessionType?: VideoSourceField['sessionType'];
+    /**
+     * Language of the source.
+     */
+    language?: LangCode;
 }
 
 export declare type GetTilesInRowResponse<U extends NextPageParamType = NextPageParamType> = PaginatedResponse<TileData, U>;
@@ -3277,6 +3292,11 @@ export declare type PlayerConfig = {
          */
         name: 'IMA SDK' | 'TIVIO AD SERVICE';
     };
+    /**
+     * If true, then TV channels are not available for anonymous users and they will be shown an overlay to sign in.
+     * @default false
+     */
+    disableTvChannelsForAnonymousUsers?: boolean;
 };
 
 /**
@@ -3400,6 +3420,11 @@ export declare interface PlayerEngineInterface {
      */
     setPlaysInline(value: boolean): void;
     setControlsList(value: string[]): void;
+    /** Gets resolution of the video element in pixels - container size, not the actual source quality resolution */
+    getVideoResolution(): {
+        width: number;
+        height: number;
+    };
 }
 
 /**
@@ -3495,6 +3520,11 @@ export declare interface PlayerInterface {
      */
     setPlaysInline?: (value: boolean) => void;
     setControlsList?: (value: string[]) => void;
+    /** Gets resolution of the video element in pixels - container size, not the actual source quality resolution */
+    getVideoResolution(): {
+        width: number;
+        height: number;
+    };
 }
 
 /**
@@ -3597,6 +3627,13 @@ export declare type PlayerState = 'idle' | 'playing' | 'paused';
  * @public
  */
 export declare interface PlayerWrapper {
+    /**
+     * Unique id of the player wrapper instance, set at construction time
+     * (e.g. by `tivio.getPlayerWrapper(id)`). Used to scope DOM ids of
+     * player-owned elements (IMA ad containers, content video element, …)
+     * so multiple players on the same page don't collide.
+     */
+    readonly id: string;
     /**
      * Report that playback of video has finished
      */
@@ -3701,6 +3738,10 @@ export declare interface PlayerWrapper {
     setCanPlay: (canPlay: boolean) => void;
     toggleMuted: () => void;
     getQualities: () => Track[];
+    getVideoResolution: () => {
+        width: number;
+        height: number;
+    };
     playNativeImaAd: (url: string) => void;
     playSourceAfterAdsRun: () => void;
     putAd: (ad: AdSourceInterface) => void;
@@ -5485,6 +5526,18 @@ export declare interface SimplifiedVideoController {
      */
     setSource(source: WebPlayerProps['source']): void;
     setAdsConfig(adsConfig: StaticAdsBreak[]): void;
+    /**
+     * Toggle the minimal OSD mode.
+     *
+     * When enabled, the player shows only a minimal set of controls (play/pause,
+     * volume and fullscreen) and a small center play/pause icon that briefly
+     * flashes when the state changes. Intended for small/pinned containers such
+     * as a scroll-fixed mini player in the corner of the page or a full-width
+     * mobile player pinned to the top of the viewport.
+     *
+     * @param isMinimal - Whether the minimal OSD should be used
+     */
+    setIsMinimal(isMinimal: boolean): void;
     /**
      * Destroy the player and clean up all resources
      */
@@ -5604,7 +5657,7 @@ export declare interface StartLiveStreamResponse {
     error?: string;
 }
 
-export declare type StaticAdsBreak = StaticAdsBreakPostrollPreroll | StaticAdsBreakMidroll;
+export declare type StaticAdsBreak = StaticAdsBreakPostrollPreroll | StaticAdsBreakMidroll | StaticAdsBreakReplacement;
 
 export declare interface StaticAdsBreakMidroll {
     type: 'midroll';
@@ -5617,6 +5670,11 @@ declare interface StaticAdsBreakPostrollPreroll {
     url: string;
 }
 
+export declare interface StaticAdsBreakReplacement {
+    type: 'replacement';
+    url: string;
+}
+
 /**
  * @public
  */
@@ -6421,6 +6479,8 @@ export declare type TivioReactBundle = {
      */
     internal: TivioInternalBundle;
     analytics: TivioAnalytics;
+    addToFavoritesByPath: (path: string) => Promise<void>;
+    removeFromFavoritesByPath: (path: string) => Promise<void>;
     destroy: () => Promise<void>;
 } & Pick<TivioSetters, 'setBundleVersion' | 'setUser' | 'setLanguage' | 'setStorageManager'> & Omit<Partial<TivioJsBundleExposedApi>, 'createPlayerWrapper'>;
 
@@ -7820,7 +7880,7 @@ export declare interface ViewCountItem {
 /**
  * @public
  */
-export declare interface VirtualChannelSourceInterface extends ChannelSourceInterface {
+export declare interface VirtualChannelSourceInterface extends Omit<ChannelSourceInterface, 'clone'> {
     tvChannelType: TvChannelType.VIRTUAL;
     program?: TvProgram | null;
     video?: Video | null;
@@ -8330,6 +8390,14 @@ export declare interface WebPlayerProps {
      * If true then OSD is shown based on condition resolved in HidableOsdContainer, e.g. on pause, on mouse move etc.
      */
     showOsd?: boolean;
+    /**
+     * If true, then only a minimal set of OSD controls is shown (play/pause, volume, fullscreen)
+     * and the big center play/pause button only flashes briefly on state change.
+     *
+     * Intended for small fixed containers (e.g. a scroll-pinned mini player in the corner
+     * of the page, or a full-width mobile player pinned to the top of the viewport).
+     */
+    isMinimal?: boolean;
     /**
      * If false, then buffering spinner is never shown.
      * If true then buffering spinner is shown while buffering.