Skip to main content

Embedding

This guide covers how to embed Streamdiver media assets and channels on any website – cookie-free and without a consent banner.

Publishing-Suite Widget Embedding​

Media assets can be embedded on any website using the Publishing-Suite web components. Include the CSS and JS, then add the widget tag:

<link rel="stylesheet" href="https://assets.streamdiver.com/playerwidget/2/sdwebwidgets.css">
<script type="module" crossorigin src="https://assets.streamdiver.com/playerwidget/2/sdwebwidgets.js"></script>

<sd-media-widget
  tenant-name="{tenantShortcode}"
  asset-id="{assetId}"
  channel-id="{channelId}">
</sd-media-widget>

The channel-id attribute is optional but recommended when the asset belongs to multiple channels, as it determines which channel design is applied.

info

The media asset must be in a public channel for the widget to work.

Set the Channel to Public​

A channel's visibility can be updated using the visibility endpoint:

curl --request PUT \
  --url https://api.streamdiver.com/v2/channels/{channelId}/visibility \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {token}' \
  --data '{ "visibility": "public" }'

Retrieve the Embed Code from the API​

The media asset response includes a ready-to-use embed snippet in the player property:

curl --request GET \
  --url https://api.streamdiver.com/v2/media/{assetId} \
  --header 'Authorization: Bearer {token}'

The player field in the response contains the full embed HTML:

{
    "data": {
        "player": "<sd-media-widget tenant-name=\"my-tenant\" asset-id=\"1d0255cc-...\"></sd-media-widget><script ...></script><link ...>",
        "id": "1d0255cc-08af-4301-b16c-23c6c2655f77",
        "name": "sampleVideo",
        "type": "video",
        ...
    },
    "status": "success"
}

Other Publishing-Suite Widgets​

Beyond the player, the Publishing-Suite includes additional embeddable widgets:

WidgetTagDescription
Media Player<sd-media-widget>Video, audio, and image playback
Livestream<sd-livestream-widget>Live stream player
PDF Viewer<sd-pdf-viewer-widget>Document viewer
Channel Slider<sd-channel-slider-widget>Carousel of channels
Media Library<sd-media-library-widget>Searchable media library (Mediathek)
Search Box<sd-search-box-widget>Content search
Chapters<sd-media-chapter-widget>Chapter navigation
Carousel<sd-carousel-widget>Content carousel within a channel
Recommendations<sd-media-recommendations-widget>Related content suggestions

All widgets share the tenant-name and optional locale attributes. See the Publishing-Suite live demo for interactive examples.

iframe Embedding​

info

iframe embedding requires the Public Portal add-on in your API subscription.

Channels and their media assets are automatically published to the Public Portal when it is enabled.

  1. Set the channel's visibility to public:
curl --request PUT \
  --url https://api.streamdiver.com/v2/channels/{channelId}/visibility \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{ "visibility": "public" }'

  1. The asset is now visible in the tenant's Public Portal (e.g., https://{tenantShortcode}.streamdiver.com/public/media/{assetId}).

  2. Create an iframe snippet:

<iframe
  style="border: none; aspect-ratio: 16/9"
  src="https://{tenantShortcode}.streamdiver.com/public/media/{assetId}?autoplay=true"
  width="100%"
  height="100%"
  allowfullscreen="true"
></iframe>

Embedding a Channel​

To embed content within a channel context, adapt the source URL to include the channel:

<iframe
  style="border: none; aspect-ratio: 16/9"
  src="https://{tenantShortcode}.streamdiver.com/public/channels/{channelId}/media/{assetId}"
  width="100%"
  height="100%"
  allowfullscreen="true"
></iframe>

Configuration Parameters​

Add these query parameters to the iframe src URL:

ParameterTypeDescription
startnumberStart time in seconds
endnumberEnd time in seconds
autoplaybooleanEnable automatic playback
standAlonebooleanEmbed the player only (no surrounding UI)
loopbooleanEnable looped playback
mediaCoverbooleanAdapt media width to the embed container
hideControlsbooleanHide the player controls

Example with stand-alone mode and hidden controls:

<iframe
  style="border: none; aspect-ratio: 16/9"
  src="https://{tenantShortcode}.streamdiver.com/public/channels/{channelId}/media/{assetId}?standAlone=true&hideControls=true&autoplay=true"
  width="100%"
  height="100%"
  allowfullscreen="true"
></iframe>

Further Resources​