React Player (Web)

React Player plays HLS and DASH (and more) in React apps. Gumlet Insights attaches to the underlying media stack once it is ready — typically the HLS.js instance when playing an HLS URL.

Step 1: Install dependencies

npm install react-player @gumlet/insights-js-core

Or load the Insights SDK from the CDN (shown in the full example below).

Step 2: Create the config

All data is associated with a workspace ID from Workspaces. Pass it as workspace_id — this is the only required field.

Optional first-party metadata: custom data options.

const gumletConfig = {
  workspace_id: 'YOUR_WORKSPACE_ID', // required
};

Step 3: Load Insights and attach to the player

Keep a ref to ReactPlayer. After the SDK script loads, wait until the underlying HLS.js instance exists, then call attach.

import React, { useEffect, useRef } from 'react';
import ReactPlayer from 'react-player';

function App() {
  const playerRef = useRef(null);
  const timerRef = useRef(null);
  const gumletInsightsRef = useRef(null);

  const gumletConfig = {
    workspace_id: 'YOUR_WORKSPACE_ID', // required
  };

  const loadGumletScript = () => {
    return new Promise((resolve) => {
      if (document.querySelector('script#gumlet-sdk-script')) {
        resolve();
        return;
      }
      const script = document.createElement('script');
      script.src = 'https://cdn.gumlytics.com/insights/4.0/main.mjs';
      script.type = 'module';
      script.id = 'gumlet-sdk-script';
      script.onload = () => resolve();
      document.body.appendChild(script);
    });
  };

  useEffect(() => {
    let cancelled = false;

    loadGumletScript().then(() => {
      timerRef.current = setInterval(async () => {
        const hls =
          playerRef.current?.player?.player?.hls ??
          playerRef.current?.getInternalPlayer?.('hls');

        if (!hls || cancelled || gumletInsightsRef.current) return;

        const gumletInsights = new window.gumlet.GumletInsights(gumletConfig);
        await gumletInsights.attach(hls);
        gumletInsightsRef.current = gumletInsights;
        clearInterval(timerRef.current);
      }, 100);
    });

    return () => {
      cancelled = true;
      if (timerRef.current) clearInterval(timerRef.current);
      gumletInsightsRef.current?.detach?.();
    };
  }, []);

  return (
    <ReactPlayer
      ref={playerRef}
      url="https://video.gumlet.io/5f462c1561cf8a766464ffc4/61b8ac77b7e0439691e7c2af/1.m3u8"
      playing
      controls
      width="100%"
      height="auto"
    />
  );
}

export default App;

HLS.js path

This example attaches to React Player’s internal HLS.js instance. For progressive MP4 (no HLS), attach the underlying HTMLVideoElement instead via getInternalPlayer() / the video ref when it is available.

Once integrated, you should start seeing data on your real-time dashboard.

How to?

Add custom data

Pass supported first-party fields on the config object. Full list: custom data options.

const gumletConfig = {
  workspace_id: 'YOUR_WORKSPACE_ID', // required
  userId: '123',
  userEMail: 'oceane.bourgeois@example.com',
  customVideoId: 'HIMYMSeason1Episode1',
  customVideoTitle: 'Pilot',
  customData1: 'campaign-a',
  customData2: 'variant-b',
  customData3: '',
  customData4: '',
  customData5: '',
};

gumletInsights.updateCustomUserData({
  userId: '123',
  userEMail: 'christelle.robert@example.com',
});

Update video metadata when the title changes

gumletInsights.updateCustomVideoData({
  customVideoId: 'HIMYMSeason1Episode2',
  customVideoTitle: 'Episode 2',
});

Update additional slots

gumletInsights.updateCustomData({
  customData1: 'campaign-b',
  customData2: 'variant-c',
  customData3: '',
  customData4: '',
  customData5: '',
});

API documentation

Method	Description
`new gumlet.GumletInsights(config)`	Create the SDK. Requires `workspace_id`.
`attach(player, opts?)`	Attach to HLS.js, Shaka (`mediaElement` required), or an `HTMLVideoElement`.
`detach()`	Remove listeners from the current player.
`updateCustomUserData(data)`	Update supported user fields (`userId`, `userEMail`).
`updateCustomVideoData(data)`	Update `customVideoId` / `customVideoTitle`.
`updateCustomData(data)`	Update `customData1`–`customData5`.

Full package docs: https://www.npmjs.com/package/@gumlet/insights-js-core

Shaka Player (Web)

React HLS Player (Web)

React Player (Web)

Step 1: Install dependencies

Step 2: Create the config

Step 3: Load Insights and attach to the player

HLS.js path

How to?

Add custom data

Update user details after login

Update video metadata when the title changes

Update additional slots

API documentation