Skip to main content

Getting Started with WebSDK

Depending on the use case, there are multiple ways to integrate the Web SDK.

The easiest way to get started is to use the iframe-based Embed Player. It requires the least amount of code and will automatically be updated when new releases are available.

The two other alternatives are Player SDK and Core SDK - these are the recommended options if the integration requires access to the APIs, such as timed metadata or other controls. The two SDKs have very similar APIs, but the Player SDK provides controls and buffering indication built in - the Core SDK is the most stripped-down implementation for use cases where all UI components are customized.

If you are going for one of the SDK alternatives, follow the steps at Installation to get started:

Embed Player​

This is the simplest way to integrate. It allows you to add a fully functional video player to your site in no time. It will also be automatically updated when improvements are released.

Add the following HTML snippet, set channelId to the channel id credential, and done!

<iframe
  src="https://embed.vindral.com/?channelId=vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f"
  frameborder="0"
  allow="autoplay; fullscreen"
  allowfullscreen
></iframe>

See the player in action or read more about Embed Player here.

Installation​

Install @vindral/web-sdk using npm:

npm install --save @vindral/web-sdk

Equivalent for yarn:

yarn add @vindral/web-sdk

Player SDK​

The Player SDK provides a ready-to-go player with controls - perfect for cases where the embed solution is not enough, such as when access to the javascript API is needed.

Example

This example attaches a player to an element with the id root. The player will activate audio when needed and provide a minimalistic UI for controls such as fullscreen, channel switching, and language selection.

The example assumes that there is an HTML page that loads this script that has at least a div with id="root".

import { Player } from "@vindral/web-sdk"

const root = document.querySelector("#root")

const player = new Player({
  url: "https://lb.cdn.vindral.com",
  channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
  channelGroupId: "vindral_demo_pk_932730be-db0c-46a0-a592-cfce7bdc5a43",
})

// Will connect, start the stream and try to play
player.core.play()

// Attaches the player view to the DOM
player.attach(root)

Core SDK​

The Core SDK is the lowest level method to integrate that provides only a video view and audio playback - this allows for complete customization of the look of buffering indication and controls.

Example

The example assumes that there is an HTML page that loads this script that has at least a div with id="root", id="playback-state" and a button with id="activate-audio-button".

import { Vindral } from "@vindral/web-sdk"

const root = document.querySelector("#root")
const button = document.querySelector("#activate-audio-button")
const playbackState = document.querySelector("#playback-state")

button.style.display = "none"

const instance = new Vindral({
  url: "https://lb.cdn.vindral.com",
  channelId: "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f",
})

// Errors are emitted when they can not be handled internally
// fatal errors mean that the client has been unloaded and will need to be re-initialized
instance.on("error", (error) => {
  if (error.isFatal()) {
    // A fatal error has occured and the instance has been unloaded, read error.message to see what
    // This can happen if the client has been unsuccessful to connect or authentication failed
    // In this case a new Vindral instance needs to be created to restore the session
  }
})

// This event is emitted when the playback state changes - can be used to show a buffer spinner while buffering
instance.on("playback state", (state) => (playbackState.textContent = state))

// This event is emitted when timed metadata events occur
instance.on("metadata", (metadata) => console.log("metadata: ", metadata.content))

// This event is emitted when Vindral detects that the browser requires a user-initiated click event to start the audio
instance.on("needs user input", () => (button.style.display = "block"))

// Will connect, start the stream and try to play
instance.play()

// Attaches the video view to the DOM
instance.attach(root)

// This activates audio on browsers that need user input before the audio can be played
button.addEventListener("click", () => {
  button.style.display = "none"
  instance.play()
})