Use segmnt in a React app

​

Before you start

1. Your video is ready (vid_...). See Manage videos.
2. The host that serves your React app is a verified domain of the project. localhost cannot be verified. Use a staging host you control, such as staging.example.com, while you develop. See Integration guide, section 3.
3. Your backend has a route that returns a playback token for a video. See Create playback tokens on your server.
4. The API key stays on your server. Never put it in React code, a bundle or an environment variable that reaches the browser. The React app asks your backend for a token; it never talks to the segmnt API itself.

​

Path 1: iframe in JSX

import { useEffect, useState } from "react";

// Call YOUR backend, not the segmnt API. Your backend holds the API key.
async function fetchToken(videoId) {
  const res = await fetch(`/api/segmnt-token?videoId=${encodeURIComponent(videoId)}`);
  if (!res.ok) throw new Error(`token request failed: ${res.status}`);
  const data = await res.json();
  return data.token; // your backend returns the `token` from the playback-tokens route
}

export function SegmntVideo({ videoId, title = "segmnt video" }) {
  const [token, setToken] = useState(null);
  const [error, setError] = useState(null);

  useEffect(() => {
    let cancelled = false;
    setToken(null);
    fetchToken(videoId)
      .then((t) => { if (!cancelled) setToken(t); })
      .catch((e) => { if (!cancelled) setError(e); });
    return () => { cancelled = true; };
  }, [videoId]);

  if (error) return <p>The video is not available right now.</p>;
  if (!token) return null;

  return (
    <div style={{ position: "relative", width: "100%", aspectRatio: "16 / 9" }}>
      <iframe
        src={`https://cdn.segmnt.cloud/e/${encodeURIComponent(videoId)}?token=${encodeURIComponent(token)}`}
        title={title}
        loading="lazy"
        style={{ position: "absolute", inset: 0, width: "100%", height: "100%", border: 0 }}
        allow="autoplay; fullscreen; picture-in-picture; encrypted-media"
        allowFullScreen
        referrerPolicy="origin"
      />
    </div>
  );
}

• Fetch a token per page load. Do not store the token in localStorage, a context or a global store across sessions: it expires (4 hours by default), and a stored token stops working.
• A long-lived single-page app can outlive a token. If the player shows “expired”, ask your backend for a new token and re-render. The error codes tell you which case you are in.
• Keep the wrapper div and the aspect-ratio style, so the player resizes with its container.

​

Path 2: the player script

<script src="https://cdn.segmnt.cloud/segmnt-player.js" defer></script>

import { useEffect, useRef, useState } from "react";
import { fetchToken } from "./fetchToken"; // the same backend call as Path 1

export function SegmntPlayerEmbed({ videoId, locale = "en" }) {
  const holder = useRef(null);
  const [token, setToken] = useState(null);

  useEffect(() => {
    let cancelled = false;
    fetchToken(videoId).then((t) => { if (!cancelled) setToken(t); });
    return () => { cancelled = true; };
  }, [videoId]);

  useEffect(() => {
    if (!holder.current || !token) return;
    const iframe = window.SegmntPlayer.embed(holder.current, {
      videoId,
      token,
      locale,
    });
    return () => {
      // React may mount and unmount twice in development (StrictMode).
      // Removing the iframe on cleanup keeps that from doubling the player.
      iframe.remove();
    };
  }, [videoId, token, locale]);

  return <div ref={holder} style={{ width: "100%" }} />;
}

​

Next.js and other server-rendered setups

• Put the component in a client component ("use client" in the App Router) or render it only after mount. The iframe and SegmntPlayer exist only in the browser.
• Put the <script src=...> tag for Path 2 in your layout’s <head> (App Router: the head/metadata of the root layout; Pages Router: next/head). Keep defer.
• Fetch the token from a route handler or API route on your server, which holds the API key in a server-side environment variable. Never put the key in NEXT_PUBLIC_* or any other variable that reaches the browser.

​

Common problems

​

Where to go next

• Embed a video on any website: the plain-HTML version of both embeds.
• Create playback tokens on your server
• How playback protection works

​

Tested against the current release

• The JSX iframe path renders the same markup as the dashboard’s iframe embed: same /e/{videoId} URL shape, allow list, referrerpolicy and responsive wrapper.
• Both components from this page were run in a DOM test harness (React 18, StrictMode on) against the real player bundle: SegmntPlayer.embed(target, { videoId, token, locale }) puts one iframe in the target, the cleanup removes it on unmount, and a StrictMode double-mount still leaves one player.
• GET https://cdn.segmnt.cloud/segmnt-player.js → 200.
• GET /e/{videoId} with no token → 403 token_missing (checked on the TEST deploy), so an app with a broken token fetch shows the player’s error message, not a blank box.
• The token response fields (token, expiresAt, embedUrl, playlistUrl) match Playback tokens and the OpenAPI spec.