React HLS Player (Web)

React HLS Player plays HLS streams in React apps. Gumlet Insights attaches to the HLS.js instance provided via getHLSRef.

Step 1: 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 2: Initialise the player

Keep a ref to the <video> element. getHLSRef gives you the HLS.js instance Insights will attach to.

import React, { useRef } from 'react';
import ReactHlsPlayer from '@gumlet/react-hls-player';

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

  return (
    <ReactHlsPlayer
      src="https://video.gumlet.io/5f462c1561cf8a766464ffc4/635789f017629894d4d125a4/main.m3u8"
      autoPlay={false}
      controls
      width="100%"
      height="auto"
      playerRef={playerRef}
      getHlsRef={(hls) => {
        console.log(hls);
      }}
    />
  );
}

export default App;

Step 3: Load the Gumlet Insights SDK

Load the CDN ESM build (insights/4.0/main.mjs) once:

function 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);
  });
}

Step 4: Attach Insights to HLS.js

When getHlsRef fires, create GumletInsights and call attach(hls):

import React, { useEffect, useRef, useState } from 'react';
import ReactHlsPlayer from '@gumlet/react-hls-player';

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

function App() {
  const playerRef = useRef(null);
  const gumletInsightsRef = useRef(null);
  const [gumletLoaded, setGumletLoaded] = useState(false);

  useEffect(() => {
    loadGumletScript().then(() => setGumletLoaded(true));

    return () => {
      gumletInsightsRef.current?.detach?.();
    };
  }, []);

  async function attachInsights(hls) {
    if (!hls || gumletInsightsRef.current) return;

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

  if (!gumletLoaded) {
    return <p>Loading...</p>;
  }

  return (
    <ReactHlsPlayer
      src="https://video.gumlet.io/5f462c1561cf8a766464ffc4/635789f017629894d4d125a4/main.m3u8"
      autoPlay={false}
      controls
      width="100%"
      height="auto"
      playerRef={playerRef}
      getHlsRef={(hls) => {
        void attachInsights(hls);
      }}
    />
  );
}

function 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);
  });
}

export default App;

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

A working demo is available in this repository.

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(hls)`	Attach to the HLS.js instance from `getHlsRef`.
`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

React Player (Web)

React Native Player (iOS + Android)

React HLS Player (Web)

Step 1: Create the config

Step 2: Initialise the player

Step 3: Load the Gumlet Insights SDK

Step 4: Attach Insights to HLS.js

How to?

Add custom data

Update user details after login

Update video metadata when the title changes

Update additional slots

API documentation