Getting started

This guide walks you through setting up Sudden alongside your existing video playback with minimal changes.

You do not need to change your player or backend. You only need to add Sudden and a small configuration.

Before you start

• You already serve video on demand in a supported format (for example via your existing CDN).
• You can deploy a small code change.
• You have a Sudden integration set up and a client ID (provided during onboarding).
• The site origins where you run Sudden (including local development origins), and the video asset sources Sudden should optimize, are allowlisted for that client ID.

Install via npm

If your site is built with a bundler, the npm package is a good way to integrate Sudden.

npm install @sudden-network/sudden

pnpm add @sudden-network/sudden

yarn add @sudden-network/sudden

bun add @sudden-network/sudden

import { loadSudden } from "@sudden-network/sudden";
 
export const setupSudden = async () => {
  const sudden = await loadSudden();
  if (!sudden) return;
 
  await sudden.init({
    clientId: "YOUR_CLIENT_ID",
    serviceWorkerPath: "/sudden.service-worker.js",
  });
 
  if (!sudden.isSupported()) {
    console.log("Sudden is not supported in this browser");
    return;
  }
 
  console.log("Sudden is running on this page");
};

import React from "react";
 
import { SuddenProvider, useSudden } from "@sudden-network/sudden/react";
 
const SuddenStatus = () => {
  const sudden = useSudden();
 
  if (!sudden) return null;
 
  if (!sudden.isSupported()) {
    return "Sudden is not supported in this browser";
  }
 
  return "Sudden is supported in this browser";
};
 
export const App = () => (
  <SuddenProvider
    config={{
      clientId: "YOUR_CLIENT_ID",
      serviceWorkerPath: "/sudden.service-worker.js",
    }}
  >
    <SuddenStatus />
    {/* your app */}
  </SuddenProvider>
);

Host the service worker loader

Sudden uses a service worker in the browser to handle video delivery. In the most common setup, you add a small loader file on your site origin (for example at https://your-domain.com/sudden.service-worker.js) and tell Sudden where it lives:

self.importScripts("https://js.sudden.network/service-worker.js");

The serviceWorkerPath must match the path of this loader file (for example "/sudden.service-worker.js"). If you already have your own service worker setup and prefer to manage registration yourself, see the Service worker page for integration patterns.

Add Sudden with a script tag

If you prefer not to use the npm package, you can add Sudden with a script tag.

<script
  id="sudden-script"
  src="https://js.sudden.network"
  crossorigin="anonymous"
  async
></script>

<script>
  const initializeSudden = async () => {
    const { sudden } = window;
    if (!sudden) return;
 
    await sudden.init({
      clientId: "YOUR_CLIENT_ID",
      serviceWorkerPath: "/sudden.service-worker.js",
    });
 
    if (!sudden.isSupported()) {
      console.log("Sudden is not supported in this browser");
      return;
    }
 
    console.log("Sudden is running on this page");
  };
 
  if (window.sudden) {
    void initializeSudden();
  } else {
    document.getElementById("sudden-script")?.addEventListener("load", () => {
      void initializeSudden();
    });
  }
</script>

Verifying that Sudden is running

• Open your test page in a supported browser.
• Start a video as usual.
• Open the browser Network tab and confirm that Sudden is handling supported video requests through the service worker.

To see savings in practice, you will need multiple viewers watching the same video around the same time. The Seeing results page explains what to look for.

Content Security Policy

If your site enforces a Content Security Policy (CSP) , update it to allow the required Sudden sources below:

• script-src must allow https://js.sudden.network
• connect-src must allow https://api.sudden.network and wss://socket.sudden.network

If CSP blocks any required source below, Sudden may not work correctly.

Where to add Sudden

For Sudden to help, it must be present on pages where you play video.

Common approaches:

• Add Sudden to your main layout so it appears on all video pages.
• If you only play video in certain sections, include Sudden only there.
• For single-page apps, call loadSudden or mount SuddenProvider in your app entry file.