@xymatic/supernext-player-t-online

React component for SuperNext Video Player with t-online defaults pre-configured. This package provides a ready-to-use video player component with t-online branding, theming, and configuration already applied.

Installation

NPM

npm install @xymatic/supernext-player-t-online

Peer Dependencies

This package requires the following peer dependencies to be installed in your project:

• react: ^18 || ^18.0.0-0 || ^19 || ^19.0.0-0
• react-dom: ^18 || ^18.0.0-0 || ^19 || ^19.0.0-0

Make sure these are installed:

npm install react react-dom

Versioning

This package follows Semantic Versioning:

• Current version: 1.0.0
• Major version (1.x.x): Breaking changes to the API
• Minor version (x.1.x): New features, backward compatible
• Patch version (x.x.1): Bug fixes, backward compatible

The package depends on @xymatic/green-video-player version ~2.6.0 (compatible with >=2.6.0 <2.7.0).

Update Instructions

To update to the latest version:

npm update @xymatic/supernext-player-t-online

To update to a specific version:

npm install @xymatic/supernext-player-t-online@<version>

Note: When updating, check the changelog for breaking changes and ensure your peer dependencies are compatible.

Usage

Import Styles

Important: You must import the CSS file for the player to render correctly:

import '@xymatic/supernext-player-t-online/index.css'

Minimal Example

import React from 'react'
import { SuperNextVideoPlayer } from '@xymatic/supernext-player-t-online'
import '@xymatic/supernext-player-t-online/index.css'

function App() {
  return (
    <SuperNextVideoPlayer
      licenseKey="your-license-key-here"
      contentId="your-content-id-here"
    />
  )
}

Basic Example with Configuration

import React from 'react'
import { SuperNextVideoPlayer } from '@xymatic/supernext-player-t-online'
import '@xymatic/supernext-player-t-online/index.css'

function App() {
  return (
    <SuperNextVideoPlayer
      licenseKey="your-license-key-here"
      contentId="your-content-id-here"
      config={{
        templateData: {
          endCardChooser: 'GRID',
          endCardCountdownAllowPause: true,
        },
      }}
    />
  )
}

Advanced Example with Events and Plugins

import React, { useRef } from 'react'
import { SuperNextVideoPlayer, type SuperNextVideo } from '@xymatic/supernext-player-t-online'
import '@xymatic/supernext-player-t-online/index.css'

function App() {
  const playerRef = useRef<SuperNextVideo>(null)

  const handleEvent = (event: CustomEvent) => {
    console.log('Player event:', event.detail)
    // event.detail contains the event payload
    // Common event types: 'play', 'pause', 'ended', 'timeupdate', etc.
  }

  const plugins = {
    myCustomPlugin: (player: SuperNextVideo) => {
      // Custom plugin logic
      console.log('Plugin initialized', player)
    },
  }

  return (
    <div style={{ width: '800px', maxWidth: '100%' }}>
      <SuperNextVideoPlayer
        ref={playerRef}
        licenseKey="your-license-key-here"
        contentId="your-content-id-here"
        embedId="optional-embed-id"
        config={{
          templateData: {
            endCardChooser: 'GRID',
            endCardCountdown: 5,
            accentColor: '#E20074',
          },
          contents: [
            // Optional: Additional content items
          ],
        }}
        onEvent={handleEvent}
        plugins={plugins}
      />
    </div>
  )
}

Using with Embed ID

When using an embedId, the t-online template data is not automatically applied. You can still override it via config.templateData:

import React from 'react'
import { SuperNextVideoPlayer } from '@xymatic/supernext-player-t-online'
import '@xymatic/supernext-player-t-online/index.css'

function App() {
  return (
    <SuperNextVideoPlayer
      licenseKey="your-license-key-here"
      embedId="your-embed-id-here"
      config={{
        templateData: {
          // Custom template data if needed
        },
      }}
    />
  )
}

Configuration Reference

Props

SuperNextVideoProps

| Prop | Type | Required | Default | Description | | ------------ | -------------------------- | -------- | ------- | --------------------------------------------------------------------------- | | licenseKey | string | ✅ Yes | - | Your SuperNext Video Player license key | | contentId | string | ❌ No | - | Content ID to load. If not provided, use embedId | | embedId | string | ❌ No | - | Embed ID to load. When provided, t-online template data is not auto-applied | | config | Config | ❌ No | {} | Player configuration object | | onEvent | (e: CustomEvent) => void | ❌ No | - | Event handler callback | | plugins | PluginsMap | ❌ No | - | Map of plugin names to plugin functions |

Note: Either contentId or embedId must be provided.

Config Object

The config prop accepts a Config object with the following structure:

type Config = {
  templateData?: TemplateData
  contents?: Content[]
  [key: string]: any
}

templateData (TemplateData)

The templateData property allows you to customize the player's appearance and behavior. When embedId is not provided, t-online defaults are automatically merged with your custom templateData.

Common Template Data Properties:

| Property | Type | Default (t-online) | Description | | ------------------------------- | ------------------- | ----------------------------------------- | ------------------------------------ | | accentColor | string | '#E20074' | Primary accent color | | endCardChooser | 'GRID' \| string | 'GRID' | End card display style | | endCardCountdown | number | 5 | End card countdown seconds | | endCardCountdownAllowPause | boolean | true | Allow pausing end card countdown | | contentLanguage | string | 'de' | Content language code | | clickToPlayLabel | string | 'Hier klicken zum Abspielen' | Click-to-play label text | | endCardReplayLabel | string | 'Video wiederholen' | Replay button label | | showTitle | boolean | false | Show video title | | showDuration | boolean | false | Show video duration | | showPosterBg | boolean | false | Show poster background | | playerAspect | string | '16:9' | Player aspect ratio | | videoFit | string | 'contain' | Video fit mode | | rotateToFullscreen | boolean | true | Rotate to fullscreen on mobile | | forceEmulatedFullscreen | boolean | true | Force emulated fullscreen | | forceEmulatedFullscreenTablet | boolean | true | Force emulated fullscreen on tablets | | preventNativeHls | boolean | true | Prevent native HLS playback | | enableAdSupport | boolean | true | Enable ad support | | nextVideoAutoplay | boolean | true | Autoplay next video | | keepPlayingOutOfView | boolean | true | Keep playing when out of view | | autostartDelay | boolean \| number | false | Autostart delay | | hudDefinitions | object | See Theming | HUD (Heads-Up Display) definitions | | adHudDefinitions | object | See Theming | Ad HUD definitions | | dockHudDefinitions | object | See Theming | Dock HUD definitions | | unmuteHudDefinitions | object | See Theming | Unmute HUD definitions |

HLS Configuration:

hlsConfig: {
  startLevel: 1,
  maxBufferSize: 0,
  maxBufferLength: 10,
  capLevelToPlayerSize: true,
  ignoreDevicePixelRatio: true,
}

Consent & Tracking:

imaNeedsConsent: true,
trackingNeedsConsent: true,
tcf2CustomVendorId: '5f1028b8fe4aae6caa688a98',
trackNoConsent: true,

contents (Content[])

Optional array of content items. See the underlying SuperNext Video Player documentation for the Content type structure.

Configuration Examples

Minimal Configuration

<SuperNextVideoPlayer licenseKey="your-license-key" contentId="your-content-id" />

Custom Accent Color

<SuperNextVideoPlayer
  licenseKey="your-license-key"
  contentId="your-content-id"
  config={{
    templateData: {
      accentColor: '#FF5733',
    },
  }}
/>

Custom End Card Behavior

<SuperNextVideoPlayer
  licenseKey="your-license-key"
  contentId="your-content-id"
  config={{
    templateData: {
      endCardChooser: 'GRID',
      endCardCountdown: 10,
      endCardCountdownAllowPause: false,
      endCardReplayLabel: 'Watch Again',
    },
  }}
/>

Disable Autoplay

<SuperNextVideoPlayer
  licenseKey="your-license-key"
  contentId="your-content-id"
  config={{
    templateData: {
      nextVideoAutoplay: false,
      autostartDelay: false,
    },
  }}
/>

Event Model

Event Types

The player emits events via the gv-player-event CustomEvent. Listen to events using the onEvent prop.

TypeScript Types

import { SuperNextVideoPlayer } from '@xymatic/supernext-player-t-online'

// Event handler type
const handleEvent = (event: CustomEvent) => {
  // event.detail contains the event payload
  const { type, ...payload } = event.detail
}

;<SuperNextVideoPlayer
  licenseKey="your-license-key"
  contentId="your-content-id"
  onEvent={handleEvent}
/>

Event Names

Common event types emitted by the player (refer to the underlying SuperNext Video Player documentation for the complete list):

• play - Video playback started
• pause - Video playback paused
• ended - Video playback ended
• timeupdate - Playback time updated
• loadedmetadata - Video metadata loaded
• canplay - Video can start playing
• waiting - Video is waiting for data
• playing - Video is playing
• seeking - Seeking operation started
• seeked - Seeking operation completed
• volumechange - Volume changed
• fullscreenchange - Fullscreen state changed
• error - Error occurred

Event Payload Shape

The event payload structure varies by event type. Generally, event.detail contains:

interface PlayerEventDetail {
  type: string // Event type name
  // Additional properties specific to the event type
  // Common properties:
  currentTime?: number
  duration?: number
  volume?: number
  muted?: boolean
  paused?: boolean
  fullscreen?: boolean
  // ... other event-specific properties
}

Event Handling Example

import React, { useState } from 'react'
import { SuperNextVideoPlayer } from '@xymatic/supernext-player-t-online'
import '@xymatic/supernext-player-t-online/index.css'

function App() {
  const [isPlaying, setIsPlaying] = useState(false)
  const [currentTime, setCurrentTime] = useState(0)

  const handleEvent = (event: CustomEvent) => {
    const { type, ...payload } = event.detail

    switch (type) {
      case 'play':
        setIsPlaying(true)
        break
      case 'pause':
        setIsPlaying(false)
        break
      case 'timeupdate':
        setCurrentTime(payload.currentTime || 0)
        break
      case 'ended':
        setIsPlaying(false)
        setCurrentTime(0)
        break
      default:
        console.log('Event:', type, payload)
    }
  }

  return (
    <div>
      <SuperNextVideoPlayer
        licenseKey="your-license-key"
        contentId="your-content-id"
        onEvent={handleEvent}
      />
      <div>
        Status: {isPlaying ? 'Playing' : 'Paused'}
        <br />
        Time: {Math.floor(currentTime)}s
      </div>
    </div>
  )
}

Theming and Asset Hosting

HUD Icon Font

The t-online player includes a custom HUD (Heads-Up Display) icon font embedded as a base64-encoded WOFF font. This font is automatically included in the template data and does not require external hosting.

Font Details:

• Format: WOFF (Web Open Font Format)
• Encoding: Base64 data URI
• Location: Embedded in templateData.hudDefinitions.iconSet, templateData.adHudDefinitions.iconSet, templateData.dockHudDefinitions.iconSet, and templateData.unmuteHudDefinitions.iconSet
• Font Name: icomoon (Version 1.0)

Custom Icon Font

To use a custom icon font, override the iconSet property in the relevant HUD definitions:

<SuperNextVideoPlayer
  licenseKey="your-license-key"
  contentId="your-content-id"
  config={{
    templateData: {
      hudDefinitions: {
        iconSet: 'https://your-cdn.com/path/to/font.woff', // or base64 data URI
        scenes: {
          // ... your HUD scene definitions
        },
      },
    },
  }}
/>

Cache Guidance

Icon Font Caching

Since the icon font is embedded as base64 in the template data:

• No external requests: The font is included in the JavaScript bundle, so no additional HTTP requests are needed
• Cache behavior: The font is cached as part of your application bundle
• CDN considerations: If you host a custom font externally, ensure proper cache headers:
  • Cache-Control: public, max-age=31536000 (1 year)
  • ETag or Last-Modified headers for cache validation

CSS Caching

The player CSS should be cached appropriately:

<!-- In your HTML or via your bundler -->
<link rel="stylesheet" href="path/to/@xymatic/supernext-player-t-online/index.css" />

Recommended cache headers for CSS:

• Cache-Control: public, max-age=86400 (24 hours) for development
• Cache-Control: public, max-age=31536000 (1 year) for production with versioning

Template Data Caching

Template data is embedded in the component configuration:

• Inline configuration: Template data is serialized as JSON in the component's inline script tag
• Bundle size: Large template data (including base64 fonts) increases bundle size
• Optimization: Consider code splitting if template data becomes too large

Custom Theming

You can customize the player's appearance by overriding template data properties:

<SuperNextVideoPlayer
  licenseKey="your-license-key"
  contentId="your-content-id"
  config={{
    templateData: {
      accentColor: '#FF5733',
      hudDefinitions: {
        iconSet: 'custom-font-url-or-base64',
        scenes: {
          baseMixin: {
            slots: {
              // Customize HUD slots
            },
          },
        },
      },
      // Customize other styling properties
      playButtonStyle: {
        height: 'min(35%, 100px)',
      },
      titleLabelStyle: {
        background: 'rgba(0, 0, 0, 0.7)',
        padding: '1em',
      },
    },
  }}
/>

Asset Hosting Best Practices

1. Use CDN for custom assets: Host custom fonts, images, and other assets on a CDN with proper cache headers
2. Base64 for small assets: For very small assets (< 10KB), consider embedding as base64 to reduce HTTP requests
3. Version assets: Use versioned URLs or query parameters for cache busting when needed
4. Compress fonts: Use WOFF2 format when possible for better compression
5. Lazy load: Consider lazy loading non-critical assets

TypeScript Support

This package includes TypeScript type definitions. Import types as needed:

import {
  SuperNextVideoPlayer,
  type SuperNextVideo,
  type Content,
  type TemplateData,
  type SuperNextVideoProps,
} from '@xymatic/supernext-player-t-online'

Type Definitions

• SuperNextVideo: The underlying player element type (for refs)
• Content: Content item type
• TemplateData: Template data configuration type
• SuperNextVideoProps: Component props type

Plugins

Register custom plugins using the plugins prop:

<SuperNextVideoPlayer
  licenseKey="your-license-key"
  contentId="your-content-id"
  plugins={{
    myPlugin: (player) => {
      // Plugin initialization
      console.log('Plugin loaded', player)
    },
  }}
/>

Plugins are automatically registered with the player instance. Plugin names are converted to kebab-case for data attributes (e.g., myPlugin becomes data-my-plugin).

Ref Access

Access the underlying player instance using a ref:

import React, { useRef, useEffect } from 'react'
import { SuperNextVideoPlayer, type SuperNextVideo } from '@xymatic/supernext-player-t-online'
import '@xymatic/supernext-player-t-online/index.css'

function App() {
  const playerRef = useRef<SuperNextVideo>(null)

  useEffect(() => {
    if (playerRef.current) {
      // Access player methods and properties
      console.log('Player instance:', playerRef.current)
    }
  }, [])

  return (
    <SuperNextVideoPlayer
      ref={playerRef}
      licenseKey="your-license-key"
      contentId="your-content-id"
    />
  )
}

Migrating from @xymatic/green-video-player-react

This package replaces @xymatic/green-video-player-react for T-Online integrations. It provides the same API with T-Online defaults pre-configured, so no template data setup is needed.

1. Swap the dependency

npm uninstall @xymatic/green-video-player-react
npm install @xymatic/supernext-player-t-online

2. Update imports

- import { GreenVideoPlayer } from '@xymatic/green-video-player-react'
- import '@xymatic/green-video-player-react/index.css'
+ import { SuperNextVideoPlayer } from '@xymatic/supernext-player-t-online'
+ import '@xymatic/supernext-player-t-online/index.css'

All named exports are available under the new package:

import {
  SuperNextVideoPlayer,
  type SuperNextVideoProps,
  type SuperNextVideo,
  type Content,
  type TemplateData,
  type PlayerEvent,
  type PlayerEventMap,
  type PlayerEventName,
  type SnPlayerCustomEvent,
  PLAYER_EVENT_TYPES,
} from '@xymatic/supernext-player-t-online'

3. Remove T-Online template data boilerplate

If you were manually passing T-Online-specific templateData (HUD definitions, branding, accent colors, etc.), you can remove it. This package applies T-Online defaults automatically when no embedId is provided.

  <SuperNextVideoPlayer
    licenseKey="..."
    contentId="..."
-   config={{
-     templateData: {
-       adHudDefinitions: { ... },
-       accentColor: '#E20074',
-       // ...hundreds of lines of T-Online config
-     },
-   }}
+   // T-Online defaults are applied automatically
  />

You can still override individual templateData properties via config.templateData — your overrides are merged on top of the defaults.

4. What changed

| Area | @xymatic/green-video-player-react | @xymatic/supernext-player-t-online | |------|-------------------------------------|--------------------------------------| | Template data | Generic defaults, T-Online config must be passed manually | T-Online defaults built-in | | Component API | GreenVideoPlayer with licenseKey, embedId, contentId, config, onEvent, plugins | SuperNextVideoPlayer — same props | | Event types | Exported | Exported (same types) | | PLAYER_EVENT_TYPES | Exported | Exported (same constants) | | CSS | @xymatic/green-video-player-react/index.css | @xymatic/supernext-player-t-online/index.css | | Storybook | Included in devDependencies | Removed (not needed for distribution) |

5. No breaking API changes

The component props, ref forwarding, event handling, and plugin registration all work identically. The only behavioral difference is the default templateData — T-Online theming is applied automatically instead of requiring manual configuration.

Author

SuperNext GmbH