Skip to main content

StreamLayer Integration

What you learn​

This article is intended for front-end developers integrating DIVA Player with a third-party video workflow. By the end of this article, DIVA Player will display StreamLayer advertisement overlays (such as pause ads) alongside your video on Web and WebTV, sourced from per-video VAST URLs.

note

StreamLayer is a third-party interactive overlay SDK that displays contextual advertisements and interactive content alongside video playback. When integrated with DIVA Player, StreamLayer renders pause ads (for example, when the viewer pauses the video), using a per-video VAST URL to source ad creatives.

Before starting​

  • Your video setup is working and you have a <videoId> and basic configuration for your platform.
  • You have a StreamLayer SDK key. Contact your StreamLayer account manager to obtain one.
  • For each video, you have a StreamLayer event ID and a VAST URL. Obtain these values from your video engineering team.
  • Configure StreamLayer in your Settings:

Integration steps​

Step 1 — Configure setting.streamLayerSetting​

Configure setting.streamLayerSetting in your player configuration to provide the SDK key required to activate StreamLayer.

See setting.streamLayerSetting for the complete setting schema and defaults.

Step 2 — Add streamLayer in videoMetadataProvider​

In your videoMetadataProvider, add the streamLayer field in VideoMetadata.

See VideoMetadata.streamLayer for the full metadata definition.

Step 3 — (Optional) Provide the StreamLayer external URL​

As an alternative to the per-video streamLayer.vastURL metadata, you can provide an external URL for StreamLayer through streamLayerExternalUrlProvider. Your project constructs the URL — for example from the videoMetadata — and returns it from the provider. Return undefined when no external URL applies.

caution

Use either the per-video streamLayer.vastURL metadata (Step 2) or the streamLayerExternalUrlProvider player config (Step 3) to source the StreamLayer content — do not use both together.

See streamLayerExternalUrlProvider for the full signature.

Full code samples​

import React from "react";
// DIVA Player SDK
import { DivaWebComponent } from "@deltatre-vxp/diva-sdk/diva-web-sdk";
import type { DivaConfiguration, VideoMetadata, VideoMetadataClean } from "@deltatre-vxp/diva-sdk/diva-web-sdk";
// Import SDK style
import "@deltatre-vxp/diva-sdk/diva-web-sdk/index.min.css";

const libs = {
  mux: "https://cdnjs.cloudflare.com/ajax/libs/mux.js/6.2.0/mux.min.js",
  shaka: "https://cdnjs.cloudflare.com/ajax/libs/shaka-player/4.11.2/shaka-player.compiled.js",
  hlsJs: "https://cdn.jsdelivr.net/npm/hls.js@1.5.7",
  googleIMA: "https://imasdk.googleapis.com/js/sdkloader/ima3.js",
  googleDAI: "https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js",
  googleCast: "https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1",
  threeJs: "https://cdnjs.cloudflare.com/ajax/libs/three.js/0.148.0/three.min.js",
};

export const App = () => {
  const config: DivaConfiguration = {
    videoId: "<videoId>",
    libs,
    setting: {
      general: {
        culture: "en-GB",
        timeToDisableAutoplay: 5400000,
      },
      // Step 1 — add streamLayerSetting
      streamLayerSetting: {
        sdkKey: "YOUR_STREAMLAYER_SDK_KEY",
        isEnable: true,
        showingDelay: 0,
      },
    },
    dictionary: {
      messages: {},
    },
    // Step 2 — return streamLayer in video metadata
    videoMetadataProvider: async (
      videoId: string,
      currentVideoMetadata?: VideoMetadataClean,
      playbackState?: { chromecast?: boolean }
    ): Promise<VideoMetadata> => {
      const metadata = {
        title: "Video Title",
        sources: [
          {
            uri: "<stream URL>",
            format: "HLS",
          },
        ],
        videoId: "<videoId>",
        streamLayer: {
          eventID: "YOUR_EVENT_ID_HERE",
          // Optional: set vastURL here to source ad creatives from metadata.
          // If you set vastURL, do NOT use streamLayerExternalUrlProvider below — use one or the other.
          // vastURL: "YOUR_VAST_URL_HERE",
        },
      };
      return metadata;
    },
    // Step 3 — construct the StreamLayer external URL as per your requirement
    // (use this OR streamLayer.vastURL, not both)
    streamLayerExternalUrlProvider: (videoMetadata: VideoMetadataClean) => {
      // Build the external URL for the StreamLayer content based on the video metadata
      return `https://your-streamlayer-url`;
    },
  };

  return <DivaWebComponent config={config} />;
};

Reference​

See StreamLayer References for the complete API surface, including:

  • Player configuration and metadata fields — streamLayerSetting and streamLayer values used by the built-in StreamLayer integration.
  • TypeScript interfaces — the StreamLayerSetting interface and the streamLayer metadata shape.