React Usage

Requirements

• React 18+ and react-dom 18+ — declared as peer dependencies of @seeen/pulse-embed; React isn’t bundled into the package, so your app supplies its own copy (avoids shipping a second React in your bundle). React 18 and 19 are both tested in CI; earlier versions aren’t supported.

• Google IMA SDK on the host page — unlike the CDN and ad-tag embeds, the React component doesn’t inject this for you:

  <script src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>

• TypeScript — @seeen/pulse-embed ships its own type declarations (Pulse, PulseProps, Playlist, VideoPlayer, VideoPlayerProps, etc.), so no separate @types package is needed. Types are generated against TypeScript 6; TypeScript 5+ consuming the package should work fine.

Installation

pnpm add @seeen/pulse-embed

Usage

import { Pulse } from "@seeen/pulse-embed";

<Pulse
  playlist={[
    {
      src: "https://example.com/ep1.m3u8",
      posterImage: "https://example.com/ep1.jpg",
      title: "Episode 1",
    },
  ]}
  aspectRatio="16:9"
  options={{ stayVisible: true, position: "bottom-right" }}
/>;

Importing Pulse pulls in video.js’s and videojs-ima’s CSS alongside its own (auto-injected via JS, no separate stylesheet to link). Class names are prefixed (pulse-*) to avoid colliding with your own styles, but this isn’t full CSS isolation — videojs-ima relies on document.getElementById internally to find the player, which doesn’t work across a shadow DOM boundary, so Pulse renders in the normal page DOM rather than a shadow root.

Playlist item shape

type PlaylistItem = {
  src: string; // HLS (.m3u8) or MP4
  posterImage: string;
  id?: string;
  title?: string;
  description?: string;
};

Props

Prop	Type	Description
playlist	PlaylistItem[], required	Items to play in order.
aspectRatio	"16:9" | "9:16" | "4:3" | "1:1", required	Player aspect ratio.
vastTagUrl	string	VAST tag URL for the interstitial ad break. Defaults to a bundled tag if omitted.
width, height	number	Defaults to 300x250.
options.position	"top-left" | "top-right" | "bottom-left" | "bottom-right" | "sticky"	Where the player docks when scrolled out of view.
options.stayVisible	boolean	Whether the player pops out at all when scrolled out of view.

For the lower-level video.js-backed component without the playlist/pop-out behavior, @seeen/pulse-embed also exports VideoPlayer and its VideoPlayerProps.