Skip to main content

Advanced usage

This guide covers advanced playback scenarios for @quickplay/player-react, including ads, Janus WebRTC, analytics metadata, and programmatic player control.

Use IMA CSAI with QuickplayPlayer​

QuickplayPlayer detects CSAI automatically when the platform asset includes a VMAP URL in csaiAdCuePointVmap. You do not need a separate ad mode flag.

For playback-time success, ensure the IMA SDK script is loaded and google.ima is available. If the SDK is missing, the player falls back to content playback without ads.

Customize ad request parameters​

Use adTagProcessor to add targeting parameters or dynamic metadata.

<QuickplayPlayer
  source={source}
  adTagProcessor={(params, asset) => ({
    ...params,
    ppid: userId,
    cust_params: `section=${section}&user_type=${userType}`,
  })}
/>

Use Janus WebRTC for low latency​

Janus mode is detected from authorized asset data. When asset.custom.janusServerUrl is present, the player switches to Janus WebRTC without extra mode flags.

<QuickplayPlayer
  source={source}
  config={{
    janusOptions: {
      janusServer: 'wss://janus.example.com',
      streamId: 42,
      iceServers: [{ urls: 'stun:stun.example.com:3478' }],
      janusConfiguration: {
        enableDebug: true,
        timeout: 15000,
      },
    },
  }}
/>

Note: Janus stream values returned in asset custom fields override fallback values in janusOptions.

Track analytics content metadata​

QuickplayPlayer auto-derives analyticsContent for you — it no longer requires apps to manually build and pass business metadata. It resolves the content's title/id from the same Data Store lookup used for display title/subtitle, and withholds analytics session creation until that resolve settles, so a session is never reported before the name is known.

Pass analyticsContent explicitly only when you need to override the auto-derived value (for example, to attach extra business metadata the Data Store entry doesn't carry):

<QuickplayPlayer
  source={source}
  analyticsContent={{
    contentId: 'video-123',
    title: 'My Video',
    duration: 3600,
    genre: 'Sports',
  }}
/>

Keep live program metadata in sync​

On a live/channel stream, QuickplayPlayer keeps the on-screen title/subtitle in sync with the currently airing program automatically — no app-side wiring required:

  • The displayed title/subtitle refreshes to the new program via EPG without interrupting playback.
  • Playback itself stops, re-authorizes, and restarts automatically when the current program's air window ends.

This works out of the box whenever a dataStoreService/EPG service is available from QuickplayPlatformProvider — there's no prop to opt in.

Access and control the player instance​

Use onPlayerReady to hold a Player instance and trigger playback actions.

import { useRef } from 'react';
import type { Player } from '@quickplay/player-react';

function VideoWithControls() {
  const playerRef = useRef<Player | null>(null);

  return (
    <>
      <QuickplayPlayer
        source={source}
        onPlayerReady={(player) => {
          playerRef.current = player;
        }}
      />
      <button onClick={() => playerRef.current?.seek(30)}>Skip 30s</button>
    </>
  );
}

Improve diagnostics​

Use higher log verbosity during troubleshooting to identify authorization, network, and playback issues.

import { LoggerLevel } from '@quickplay/player-react';

<QuickplayPlayer source={source} config={{ logLevel: LoggerLevel.VERBOSE }} />;

For runtime error handling, wire onError into your monitoring stack.

<QuickplayPlayer
  source={source}
  onError={(error) => {
    Sentry.captureException(error);
  }}
/>

Render headless video​

Render video without any control UI using controls={false}:

<QuickplayPlayer source={source} controls={false} className="video-element" />

Report the player version​

The package exports a version string you can send to analytics or logging services:

import { version } from '@quickplay/player-react';

// Log to console
console.log('Player version:', version); // for example, "7.0.8"

// Report to analytics
analytics.track('player_init', { playerVersion: version });

Troubleshoot common issues​

Use this section to diagnose frequent integration problems.

npm install fails with 401 or 404

  • Run npm config get @quickplay:registry — the output must be https://firstlight.jfrog.io/artifactory/api/npm/javascript-sdk-local/
  • Re-authenticate: npm login --scope=@quickplay
  • Check ~/.npmrc for correct credentials
  • Verify your API key is Base64-encoded in the _password field

Provider doesn't initialize

  • Confirm you've provided either configUrl or config, not both
  • Verify your config URL returns valid JSON
  • Check that network requests aren't blocked by CORS or a firewall
  • Look for error messages in the browser console

"useQuickplayPlatform must be used within a QuickplayPlatformProvider"

A component is calling the hook outside of the provider's scope. The provider must be an ancestor of the component calling the hook:

// Correct
<QuickplayPlatformProvider configUrl="...">
  <App />
</QuickplayPlatformProvider>

// Wrong — provider is not an ancestor
<App />
<QuickplayPlatformProvider configUrl="..." />

Player doesn't render

  • QuickplayPlatformProvider must wrap QuickplayPlayer (not required for ContentPlayer)
  • All required source fields must be present
  • The player auto-registers custom elements on import — no manual registration step is needed

Playback doesn't start

  • Verify the drmScheme matches the content encryption
  • Check network connectivity to the CDN and license server
  • Enable verbose logging with config={{ logLevel: LoggerLevel.VERBOSE }}
  • Review console logs for specific failure messages

Best practices​

Keep these principles in mind as your integration grows.

  • Prefer configUrl over hardcoding endpoints so you can update platform configuration without redeploying.
  • Use the right component: QuickplayPlayer for Quickplay-hosted content, ContentPlayer for external streams or custom auth flows.
  • Wrap with an error boundary. React ErrorBoundary prevents unexpected player crashes from breaking your entire app.
  • Keep credentials server-side. Never expose API keys or secrets in client code.
  • Test content types separately. VOD, live, and DRM content each have distinct failure modes.
  • Wire onError to your monitoring service for production visibility before you ship.

Next steps​

After advanced setup, review exact prop signatures.