@tivio/sdk-react 9.7.0 → 9.8.0

package/CHANGELOG.md

@@ -0,0 +1,369 @@
+## Changelog
+
+## 9.8.0
+  * minor: add addToFavoritesByPath and removeFromFavoritesByPath methods to tivio entity
+  * patch: fix support of multiple players on the same page
+  * patch: fix support of multiple players on the same page
+  * minor: add minimal OSD to web player
+  * minor: add setIsMinimal method to video controller
+  * minor: fix IMA ads playback
+  * minor: fix IMA black screen when multiple WebPlayers are on one page: scope ad container / video / click element DOM ids per `playerWrapper.id`.
+
+## 9.7.1
+  * patch: add replacement type to ad static config
+
+## 9.7.0
+  * minor: add optional enableGtmPlayerEvents parameter into TivioConfig
+  * minor: add companion-ads events
+  * minor: add replacement of VAST macros and Vasterix templates
+  * minor: add possibility to use Single Sign-On (SSO) for all subdomains under the same parent domain
+  * minor: add optional enableGtmPlayerEvents parameter into TivioConfig
+  * minor: add getTagsByIds method
+
+## 9.6.0
+  * minor: change ad_started and ad_ended events to ad-started and ad-ended
+  * patch: fix crash when custom token in cookies is expired or invalid
+  * minor: add userAuthCallbacks -> onGoToLogin and onGoToRegistration to WebPlayerProps
+
+## 9.5.0
+  * minor: add possibility to use Single Sign-On (SSO) for all subdomains under the same parent domain
+  * minor: add staticAdsConfig to source types
+  * minor: add ad_started and ad_ended events to video controller
+  * minor: add ctaElement to ad_started event
+  * minor: add customAdMetadata to ad_started event
+
+## 9.4.0
+  * minor: add support for multiple urls in external sources
+
+## 9.3.1
+  * patch: fix documentation
+
+## 9.3.0
+  * minor: add getFavorites, getWatchPositions, getWatchHistory methods to user entity
+  * minor: add GetUserProfileDataOptions type to exported types
+  * minor: add FavoriteWithData and WatchPositionWithData types to exported types
+  * minor: add profileId to FavoriteWithData and WatchPositionWithData types
+  * minor: update documentation
+
+* 9.2.0
+  * minor: remove deprecated TivioWidget component
+  * minor: remove deprecated TivioWidgetError component
+  * minor: remove deprecated TivioWidgetLoader component
+  * patch: deprecate PurchasesWithVideosContextProvider
+  * minor: remove unused WebProfileScreen component
+  * minor: remove unused ChannelContext context
+  * minor: added video controller return from renderWebPlayer
+  * minor: update docs usage of renderWebPlayer and video controller
+
+* 9.2.0-alpha.4
+  * patch: expose getUser, resetPassword and signOut methods in RemoteBundleState type
+  * patch: more precise types for user profile fields and methods
+  * patch: add missing jsdocs for some User type fields
+
+* 9.2.0-alpha.0
+  * minor: add renderWebPlayer method for rendering outside of React
+  * minor: "expose createTivio"
+
+* 9.1.7
+  * patch: update remote controller component API
+
+* 9.1.6
+  * minor: add remote controller
+
+* 9.1.5
+  * patch: expose purchase loyalty points through types
+  * patch: enable setUser check
+
+* 9.1.4
+  * patch: disable setUser check
+  * patch: rollback "add renderWebPlayer method for rendering outside of React"
+  * patch: rollback "expose createTivio"
+
+* 9.1.3
+  * patch: add renderWebPlayer method for rendering outside of React
+  * patch: expose createTivio
+
+* 9.1.4
+  * patch: disable setUser check
+
+* 9.1.3
+  * minor: add renderWebPlayer method for rendering outside of React
+  * minor: expose createTivio
+
+* 9.1.2
+  * patch: update PurchaseEndpointPayload type (cityName, externalId, geoPoint)
+
+* 9.1.1
+  * patch: fix changelog
+
+* 9.1.0
+    * patch: add gateway to Purchase type
+    * minor: add QerkoPaymentWebhookByApiKeyRequest to exported types
+
+* 9.0.0
+    * patch: remove i18next and react-i18next from externals and dependencies
+    * patch: do not send react-spring to core-react-dom bundle, remove react-spring from dependencies
+    * patch: clean-up externals in webpack config
+    * patch: send only required dependencies to the bundle
+    * major: change purchase statuses lifecycle
+    * minor: add originalPurchaseId to PurchaseEndpointPayload
+
+* 8.0.0
+    * major: deprecated usePurchasesWithVideos hook removed
+    * patch: add id to user type
+    * patch: add @types/react to peerDependencies
+
+* 7.1.0
+    * minor: export useTvChannelHook
+    * patch: bump "react-i18next", "i18next" versions.
+
+* 7.0.1
+    * patch: fix dependency to @tivio/common
+
+* 7.0.0
+    * major: delete deprecated useWatchWithoutAdsOffer hook
+    * major: consolidate duplicated source types
+    * patch: add new properties to PlayerInterface
+    * patch: expose getSeekingMatrixPreviewByTime in Video interface
+    * major: delete deprecated useBetOffer hook
+    * major: rework of source types
+    * major: make useChannelSource deprecated
+
+* 6.0.1
+    * patch: fix dependency to @tivio/common
+
+* 6.0.0
+    * major: delete usePlayerEvent hook
+    * major: replace uri attributes in types with url
+    * major: delete uri attributes from types
+    * minor: add purchase expiration to PurchaseEndpointPayload
+    * minor: add optional videoId parameter to useOrganizationSubscription hook
+
+* 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
+    * major: fix typing for useReferralInfo, now correctly showing that `null` can be returned
+    * major: fix typing for `WebRowProps.onTileClick`, now correctly showing that `null` can be accepted
+    * minor: add analytics
+    * minor: add getSourceUrl function to video and tv channel types
+    * minor: add uri property to tv channel type
+    * minor: add useChannelSource to hooks
+
+* 4.5.0
+    * minor: extend PurchaseEndpointPayload type with purchase previousStatus and newStatus fields
+
+* 4.4.1
+    * patch: added waitForTags param in useSearch hook for videos
+
+* 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
+
+* 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
+    * minor: monetization property deleted from Video type
+    * minor: monetization now has originalPrice and promotion properties available
+    * patch: remove not used OrganizationSubscriptionsContext, **this change requires bundle 3.20.0 or newer**
+
+* 4.2.0:
+    * minor: fix useSearch loading type
+    * patch: added italian language to `LangCode` enum
+
+* 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
+
+* 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
+
+* 4.0.0
+    * minor: Types cleanup
+    * MAJOR: Remove deprecated and unused stuff
+        * auth
+            * changePassword
+            * changeUserPhoto
+            * removeUserPhoto
+            * getPurchasedVodsWithInitializedVideos
+            * initializeUser
+            * createFreePurchase
+        * components
+            * videoAdBanner
+        * getters
+            * getExportedConfig
+            * getChannelById
+            * getSectionById
+            * getWidgetById
+        * hooks
+            * useLastVideoByWidgetId
+            * useScreen
+            * useFreePurchase
+            * useWidget
+            * useChannel
+            * useSection
+            * useVideosInSection
+            * useSectionsInChannel
+            * useChannelsInWidget
+        * subscriptions
+            * subscribeToWidget
+            * subscribeToChannel
+            * subscribeToSection
+            * subscribeToVideosInSection
+            * subscribeToSectionsInChannel
+            * subscribeToChannelsInWidget
+            * subscribeToScreen
+---
+_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)_
+
+* 3.7.0
+    * minor: purchase contains created and updated
+
+* 3.6.3
+    * patch: improve README.md
+
+* 3.6.2
+    * patch: Fix types
+
+* 3.6.1
+    * patch: Fix README
+
+* 3.6.0
+    * minor: Update types
+
+* 3.5.2
+    * patch: All types are available again.
+
+* 3.5.1
+    * patch: remove incorrect dependency (@tivio/types)
+
+* 3.5.0
+    * minor: Types change - Video.price and Video.detailedPrice can be null
+    * minor: Types change - Video.cover is marked as deprecated
+
+* 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
+* 3.3.2
+    * patch: Adding new optional parameters (where, orderBy) to useTaggedVideos hook
+* 3.3.1
+    * patch: Fixed types of `setUser`
+* 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
+* 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
+* 3.2.4
+    * minor: added useApplyInviteCode
+    * minor: better errors from useVoucher
+* 3.2.3
+    * minor: added usePurchaseRecovery hook
+    * patch: deprecated `useLastVideoByWidgetId`
+* 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
+* 3.2.1
+    * patch: fix of @tivio/common version
+* 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"
+* 3.1.3
+    * patch: Hotfix made sure disabled Tivio does not break React Native
+* 3.1.2
+    * patch: Allow `conf` prop of `TivioProvider` to be `null` or `undefined` in order to turn off Tivio
+* 3.1.1
+    * patch: fixed `setUser()` crash when bundle fails to load
+* 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
+* 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
+    * major: TivioProvider requires currency
+    * minor: add voucher support (see usePurchaseSubscription and useTransactionPayment hooks)
+    * minor: device limit support
+    * minor: drm (Widevine, PlayReady) support
+    * minor: watermarking support
+    * minor: add useSearch hook
+    * patch: price on video is 0 when purchased
+* 2.4.2
+    * patch: added back changelog
+* 2.4.1
+    * patch: improved doc about player wrapper
+* 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)
+* 2.3.4
+    * patch: fix of usePurchaseSubscription not reactive
+* 2.3.3
+    * patch: fix of useUser not updating
+* 2.3.2
+    * patch: next app doesn't fail anymore due to "self is not defined"
+* 2.3.1
+    * patch: fix of @tivio/common dependency
+* 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
+* 2.2.1
+    * patch: disable Sentry when no config is supplied to `TivioProvider`
+* 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 }`
+* 2.1.5
+    * patch fix of `useVideosInSection` hook (fetching video's monetizations)
+* 2.1.4
+    * patch: fix re-rendering of `useAd` during non-skippable ads (requires core-react-dom@2.1.9)
+* 2.1.3
+    * patch: fix changelog
+* 2.1.2
+    * patch: Fixed exported types
+* 2.1.1
+    * patch: TivioWidget now correctly reports `false` via `onEnabled` callback when in invalid internal state
+* 2.1.0
+    * patch: fix of useItemsInRow hook
+    * patch: fix of useScreen hook
+    * add: useRowsInScreen hook
+* 2.0.3
+    * patch: fix of useItemsInRow hook
+* 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
+* 2.0.1
+    * no changes
+* 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`
+* 1.3.6
+    * ?
+* 1.3.5
+    * minor: added WebPlayer props (canReplay, showMarkers, customShortcuts, enableKeyboardShortcuts, source.poster)
+* 1.3.4
+    * ...

package/README.md

@@ -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