WidgetEmbeddedVideo

Use WidgetEmbeddedVideo when you want inline video playback embedded in a page region, instead of a browse widget (row or grid) that previews items and opens the player experience.

On Web, you create it using the BlazeSDK.WidgetEmbeddedVideo(...) method.

When to use WidgetEmbeddedVideo

Use WidgetEmbeddedVideo when you need:

Inline playback in a layout: the video plays inside a section of your page (for example, an article, a feed item, or a detail page module).
Autoplay based on visibility: playback starts when the embedded widget is in view and pauses when it is out of view.
One focused playback surface: you want a single embedded player, not a list of items to browse.

Use WidgetRowView or WidgetGridView (with contentType: 'video') when you need:

Content discovery: show many videos as a row or grid so viewers can browse and select.
A widget-first UI: thumbnails and metadata drive the interaction, and playback happens after selection.

How it behaves

WidgetEmbeddedVideo is an embedded widget that:

Loads videos using a data source (labels or content IDs) you provide in embedded-widget options, not generic IWidgetViewOptions. BlazeSDK.WidgetEmbeddedVideo(...) does not support widgetRemoteIdentifier.
Plays when the widget enters the viewport and pauses when it leaves. The SDK uses viewport visibility (about 50% in view) to decide when to play.
Uses the same delegate system as other Web SDK widgets so you can react to load and playback events.

If you render multiple embedded videos on the same screen, plan how you will avoid multiple streams playing at once. The SDK pauses when a widget leaves the viewport, but two widgets can be visible at the same time.

Create an embedded video widget (JavaScript)

This example follows the same lifecycle used in the JavaScript getting started guide: initialize, wait for onBlazeSDKConnect, then create the widget.

<div id="embedded-video" style="width: 100%; height: 360px;"></div>

<script>
  document.addEventListener('onBlazeSDKConnect', () => {
    const dataSource = BlazeSDK.DataSourceBuilder().labels({
      labels: BlazeSDK.LabelBuilder().singleLabel('featured-videos'),
      maxItems: 10,
    });

    BlazeSDK.WidgetEmbeddedVideo('embedded-video', {
      dataSource,
      contentType: 'video',
      delegates: {
        [BlazeSDK.Delegations.onWidgetDataLoadCompleted]: (e) => {
          if (e.detail.contentCount === 0) {
            const container = document.querySelector('#embedded-video');
            if (container) container.style.display = 'none';
          }
        },
      },
    });
  });

  BlazeSDK.Initialize('YOUR_API_KEY');
</script>

Tips and constraints

Container sizing: Set a fixed height for the container element so the player can lay out correctly.
Scroll containers: If the embedded widget lives inside a scrollable container, test the in-view behavior.
Prefer data sources over deprecated APIs: Don’t rely on deprecated web component methods like setting content IDs after render. Prefer DataSourceBuilder and widget options.

When to use WidgetEmbeddedVideo

How it behaves

Create an embedded video widget (JavaScript)

Tips and constraints

Related pages