@tivio/sdk-react

@tivio/sdk-react provides everything which is necessary (components, data hooks etc.) to build a custom React application above Tivio Studio. You can comfortably manage all you videos, settings such as application's screens and rows and also monetization settings in the administration of Tivio Studio while having the freedom to build your own application.

Changelog

• 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 [email protected])

• 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/[email protected]

• 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
  • patch: added support for browsers that do not implement 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 [email protected])

• 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

  • ...

Installation

Install @tivio/sdk-react along with its peer dependencies

npm i react@17 react-dom@17 @tivio/sdk-react
# or
yarn add react@17 react-dom@17 @tivio/sdk-react

Initialization

Put Tivio Provider at the top level of your application:

import { TivioProvider } from '@tivio/sdk-react'

const config = {
    secret: 'XXXXXXXXXX',
}

function App({children}) {
    return (
        <TivioProvider conf={config}>
           {children}
        </TivioProvider>
    )
}

Authentication

A logged-in user can access more features, such as making purchases. In order to authenticate a user with Tivio, use the setUser() method.

Verification of the user against 3rd party auth servers is implemented per customer.

import { setUser } from '@tivio/sdk-react'

// 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(null)

Player

You can choose whether you will use complete player component provided by Tivio or you will wrap your existing player with the Tivio Player Wrapper.

Tivio Player component

import { useTivioData } from '@tivio/sdk-react'

const PlayerExample = () => {
    const bundle = useTivioData()

    if (!bundle?.components?.WebPlayer) {
        return <p>Loading...</p>
    }

    return (
        <>
            <div
                style={{
                    height: 720,
                    width: 1280,
                }}
            >
                <bundle.components.WebPlayer
                    id="player1"
                    className="web-player"
                    source="/videos/xxxxxxxxxxxxxxxxxxxx" // dynamically change this based on video you want to play
                />
            </div>
        </>
    )
}

Player wrapper

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

import { useTivioReadyData } from '@tivio/sdk-react'

function CustomPlayer() {
    const tivioData = useTivioReadyData()

    useEffect(() => {
        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

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

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

    // 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'))
}

Data hooks

useUser hook

Gets information about current user.

useUser: () => {
    user: User | null
    error: string | null
    isInitialized: boolean
}

useRowsInScreen hook

Gets array of Rows objects of specific screen and subscribes to its changes.

/**
 * 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.

/**
 * 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.

/**
 * Use video
 * @param videoId - video id
 */
useVideo: (videoId: string) => {
    error: string | null;
    data: Video | null;
}

useTaggedVideos hook

Gets videos with given tag IDs.

/**
 * Use tagged videos
 * @param tagIds - tag ids
 * @param options - subscription options
 * @public
 */
useTaggedVideos: (tagIds: string[], options?: SubscribeToItemsInRowOptions) => {
    pagination: PaginationInterface<Video> | null
    error: Error | null
}