@kaltura/unisphere-ui-kaltura-player-react

React wrapper component for Kaltura Player with dynamic script loading, lifecycle management, and comprehensive error handling.

Features

• 🚀 Dynamic script loading with timeout and retry
• 🔄 Full player lifecycle management (init, cleanup, prop changes)
• 🛡️ Comprehensive error handling for all edge cases
• 🎨 Built-in loading and error UI (Kaltura DS / MUI)
• 📘 Full TypeScript support
• ♿ Accessible UI components

Installation

This package is part of the Unisphere UI workspace and is not published to npm.

Usage

Basic Example

import { KalturaPlayer } from '@kaltura/unisphere-ui-kaltura-player-react';

function App() {
  return (
    <KalturaPlayer
      config={{
        partnerId: 12345,
        uiconfId: 67890,
        entryId: '0_abc123',
        ks: 'your-kaltura-session-token',
      }}
      width="640px"
      height="360px"
      autoPlay={false}
    />
  );
}

With Callbacks

import { KalturaPlayer } from '@kaltura/unisphere-ui-kaltura-player-react';

function App() {
  const handleReady = (player) => {
    console.log('Player ready:', player);
  };

  const handleError = (error) => {
    console.error('Player error:', error);
  };

  return (
    <KalturaPlayer
      config={{
        partnerId: 12345,
        uiconfId: 67890,
        entryId: '0_abc123',
        ks: 'your-kaltura-session-token',
        serverUrl: 'https://cdnapisec.kaltura.com', // optional
      }}
      width="100%"
      height="500px"
      autoPlay={true}
      onReady={handleReady}
      onError={handleError}
      className="my-player"
      scriptTimeout={15000}
    />
  );
}

Using Hooks Directly

import { useKalturaScript, useKalturaPlayer } from '@kaltura/unisphere-ui-kaltura-player-react';

function CustomPlayer() {
  const { status, error, retry } = useKalturaScript(12345, 67890);

  const { playerInstance } = useKalturaPlayer(
    {
      partnerId: 12345,
      uiconfId: 67890,
      entryId: '0_abc123',
      ks: 'token',
    },
    'my-player-target',
    status
  );

  // Custom rendering logic
  return <div id="my-player-target" />;
}

API

KalturaPlayer Props

| Prop | Type | Required | Default | Description | | --------------- | ------------------------------------- | -------- | -------------- | ------------------------------------------ | | config | KalturaPlayerConfig | Yes | - | Player configuration | | targetId | string | No | auto-generated | DOM element ID for player | | width | string \| number | No | '100%' | Player width (string for %, number for px) | | height | string \| number | No | '360px' | Player height | | autoPlay | boolean | No | false | Auto-play video on load | | onReady | (player: any) => void | No | - | Callback when player is ready | | onError | (error: KalturaPlayerError) => void | No | - | Callback on error | | className | string | No | - | CSS class for container | | scriptTimeout | number | No | 10000 | Script load timeout (ms) |

KalturaPlayerConfig

| Property | Type | Required | Description | | ----------- | -------- | -------- | --------------------------------------------------- | | partnerId | number | Yes | Kaltura partner ID | | uiconfId | number | Yes | UI configuration ID | | entryId | string | Yes | Entry ID to play | | ks | string | Yes | Kaltura Session token | | serverUrl | string | No | Kaltura server URL (default: cdnapisec.kaltura.com) |

Error Handling

The component handles these error scenarios:

• Script Load Failures: Network errors, timeouts, blocked resources
• Invalid Configuration: Missing or malformed config values
• Initialization Errors: Player API failures, missing target element
• Network Errors: General connectivity issues

Errors include:

• type: Error category for programmatic handling
• message: User-friendly error message
• recoverable: Whether retry is possible

Development

Build

npx nx run unisphere-package-kaltura-player-react:build

Lint

npx nx run unisphere-package-kaltura-player-react:lint

License

AGPL-3.0