@pbj/live.js
v0.0.17
Published
PBJ Live Javascript SDK (Currently Docs only)
Downloads
4
Keywords
Readme
PBJ Live Javascript SDK
Stream your pbj.live content from your web App.
📦 Installation
1. Import the web-sdk package:
Using CDN
<script src="https://js.pbj.live/sdk.js"></script>Using NPM
npm install @pbj/live.js
or
yarn add @pbj/live.js
import Live from '@pbj/live.js';This script will expose a global Live class. Initiate the class with your organization api key:
2. Initialize the LivePlayerSDK with your api key:
const live = new Live("<Your API KEY>")🚀 Usage
When the Live class is initiated you will be able to do several things:
- Render a PBJ Live stream to a HTML element
- Retrieve information from our APIs
Elements
Embed element
Currently our recommended way to integrate with PBJ Live.
html
In your html, create a div tag with your preferred naming, we use live-element in these examples.
So in your html, add:
<html>
<body>
<!--- Add Live element here ---!>
<div id="live-element"></div>
<script src="https://js.pbj.live/v1/sdk.js"></script>
<script type="text/javascript">
var live = new Live("<Your API Key>");
// Create instance of the iframe embed
var embedPlayer = live.elements.embed()
// Mount the player to the div#live-element in our html
const liveElement = document.querySelector('#live-element');
embedPlayer.mount(liveElement, {
// (Optional) Channel ID can be passed within an object, i.e. the second parameter for the mount method.
channelId: '0c2e035f-fd07-4390-921f-1e1e865805f1',
// More about channel ID in "Using different channels" section below.
})
</script>
</body>
</html>using hooks
import React, { useEffect } from 'react';
import Live from '@pbj/live.js';
const LiveVideo = () => {
const liveElementRef = useRef();
useEffect(() => {
var live = new Live("<Your API Key>", {
environment: 'demo'
});
// Create instance of the iframe embed
var embedPlayer = live.elements.embed()
// Mount the player to the div in our html
embedPlayer.mount(liveElementRef.current, {
// (Optional) Channel ID can be passed within an object, i.e. the second parameter for the mount method.
channelId: '0c2e035f-fd07-4390-921f-1e1e865805f1',
// More about channel ID in "Using different channels" section below.
})
}, [])
return <div ref={liveElementRef}><div/>
}
In the background, this embed() method will create an iFrame that will injected into your html element, we also offer a lower level solution via the live.elements.video() method.
Using different channels
Selecting a specific channel to show in the LIVE video player requires the channel_id option to be added to the options while calling the embedPlayer.mount.
embedPlayer.mount(liveElement, {
channelId: '<Your channel ID>',
})To get the channel ID go to the dashboard and select a stream from the dropdown Select Streams. Once, you've selected this channel, copy the ID in the URL address bar. (URL format: https://pbj.live/dashboard/broadcast/Your-Channel-ID
Example:
URL: https://pbj.live/dashboard/broadcast/31d319ae-919b-4ac2-bd10-f9a390c9aa81
Channel ID: 31d319ae-919b-4ac2-bd10-f9a390c9aa81
Mount Options
The embedPlayer.mount method accepts an object as it's param. Within the main params object, it is possible to give a channelId as depicted in the examples above. It is also possible to to give an options object (within the main params object) with a number of boolean fields that can toggle player overlay content.
| Field | Default Value | Details | | ------------- | ------------- | ------------- | | hideCoverTitle | false | Toggles the Live cover title. | | hideCoverDescription | false | Toggles the Live cover description. | | hideLiveLogo | false | Toggles the Live logo on the Live Video Player. | | hideTitle | false | Toggles the Live episode title on the Live Video Player. | | hideDescription | false | Toggles the Live episode description on the Live Video Player. | | hideShoppingCart | false | Toggles the Live episode shopping cart/bag and featured products on the Live Video Player. |
const liveElement = document.querySelector('#live-element');
embedPlayer.mount(liveElement, {
channelId: '0c2e035f-fd07-4390-921f-1e1e865805f1',
options: {
hideLiveLogo: true,
hideTitle: true,
hideDescription: true,
hideShoppingCart: true,
},
});Video Element
const episode = live.elements.video();Mount to HTML object
Then mount this element to your HTML element:
const videoElement = live.elements.video({
episode: id
});
videoElement.mount("#live-video")Start video
videoElement.start();
embedPlayer.start();Stop video
videoElement.stop();
embedPlayer.stop();Remove video element
videoElement.dispose();
embedPlayer.dispose();Change volume
You can change the volume of player by calling below method, 0 being the lowest and 1 being the highest.
videoElement.volume(0.5);
embedPlayer.volume(0.7);Open full screen programatically
videoElement.openFullscreen()
embedPlayer.openFullscreen()Close full screen programatically
videoElement.closeFullscreen()
embedPlayer.closeFullscreen()Episodes Element
const episodesElement = live.elements.episodes;This returns an object of serveral methods that can be used to fetch episodes data.
Note: Methods marked as "Paginated" accept "page" and "perPage" as optional fields within the params object.
Sample method call for a paginated mehtod.
const params = { perPage: 99, page: 1 };
const episodes = episodesElement.list({params});Get a list of Episodes (Paginated)
const episodes = episodesElement.list();The episodesElement.list method will return a Promise that resolves to an array of Episode data objects.
This method along with pagination params, supports the following params.
| Field | Default Value | Details |
| ------------- | ------------- | ------------- |
| startingAt (ISO DateTime string) | Start of user's day | Helps in getting episodes having start datetime greater than startingAt. |
| daysAhead (number) | 1 | Helps in getting episodes for number of days ahead. |
Example:
const params = { perPage: 99, page: 1, startingAt: new Date().toISOString(), daysAhead: 7 };
const episodes = episodesElement.list({ params });Get a list of an Episode's Featured Products (Paginated)
const featuredProducts = episodesElement.featuredProducts({episodeId});The episodesElement.featuredProducts method will return a Promise that resolves to an array of Episode's Featured Products data.
This methods accepts an object as its parameter with a required episodeId field, along with the pagination params object.
Example:
const episodeId = '7460531a-437d-4ddd-bf25-0a87536e1256a';
const params = { per_page: 99, page: 1 };
const featuredProducts = episodesElement.featuredProducts({ episodeId, params });Get a list of an Episode's Highlighted Featured Products (Paginated)
const highlightedFeaturedProducts = episodesElement.highlightedFeaturedProducts({episodeId});The episodesElement.highlightedFeaturedProducts method will return a Promise that resolves to an array of Episode's Highlighted Featured Products data.
This methods accepts an object as its parameter with a required episodeId field, along with the pagination params object.
Example:
const episodeId = '7460531a-437d-4ddd-bf25-0a87536e1256a';
const params = { per_page: 99, page: 1 };
const highlightedFeaturedProducts = episodesElement.highlightedFeaturedProducts({ episodeId, params });Get Next or Ongoing episode
const nextEpisode = episodesElement.next();The episodesElement.next method will return a Promise that resolves to the data of the episode to go live next.
VOD (Video on Demand) Element
const vodElement = live.elements.vod;This returns an object of serveral methods that can be used to embed VOD Player and to get VOD Data.
Note: Methods marked as "Paginated" accept "page" and "per_page" as optional fields within the params object.
Sample method call for a paginated mehtod.
const params = { per_page: 99, page: 1 };
const vodItems = vodElement.getItems({params});Embed VOD Player
const vodPlayer = vodElement.embed(params);The vodElement.embed method will mount a VOD player within a container element.
This methods accepts a params object with required containerElement and videoId fields and returns an object of the VodPlayer.
Within the main params object, it is possible to give an optional options object with boolean fields that can toggle player overlay content.
| Field | Default Value | Details |
| ------------- | ------------- | ------------- |
| closable | false | Toggles a close/cross icon on top of the VOD player which when clicked calls the dispose method of the player. |
| hideProducts | false | Toggles the VOD featured prodcuts on the player. |
| hideDuration | false | Toggles the video duration details on the player. |
The dispose method can also be called using the vodPlayer object.
const containerElement = document.getElementById('vod-container-element');
const videoId = '7460531a-437d-4ddd-bf25-0a87536a406a';
const options = { closable = true, hideProducts = true };
const vodPlayer = vodElement.embed({ containerElement, videoId, options });
// To dispose the vodPlayer
vodPlayer.dispose();Get List of VOD Items (Paginated)
const vodItems = vodElement.getItems();The vodElement.getItems method will return a Promise that resolves to an array of Vod Items.
This method along with pagination params, supports a search field in params object.
const params = { per_page: 99, page: 1, search: 'vod' };
const vodItems = vodElement.getItems({ params });Note: Search filtering is present only on category, playlist and video titles and is case in-sensitive. For example: To filter all vod items having category/video/playlist title with 'sample' in them, request should be:
const params = { search: 'sample' };
const vodItems = vodElement.getItems({ params });Get a list of Videos (Paginated)
const videos = vodElement.getVideos();The vodElement.getVideos method will return a Promise that resolves to an array of Video objects.
This method along with pagination params, supports a search field in params object.
const params = { per_page: 99, page: 1, title: 'video' };
const videos = vodElement.getVideos({ params });Note: Search filtering is present only on title, description, featured product name and featured product category and is case in-sensitive. For example: To filter all videos having title, description, featured product name or featured product category name with 'sample' in them, request should be:
const params = { search: 'sample' };
const videos = vodElement.getVideos({ params });Get a specific Video
const video = vodElement.getVideo(videoId);The vodElement.getVideo method will return a Promise that resolves to an Video data object.
This method accepts a required videoId parameter.
const videoId = '7460531a-437d-4ddd-bf25-0a87536a406a';
const video = vodElement.getVideo(videoId);
Get a Video's Featured Products (Paginated)
const featuredProducts = vodElement.getVideoFeaturedProducts({ videoId });The vodElement.getVideoFeaturedProducts method will return a Promise that resolves to an Video Featured Products data object.
This methods accepts an object as its parameter with a required videoId field, along with the pagination params object.
const videoId = '7460531a-437d-4ddd-bf25-0a87536a406a';
const params = { per_page: 99, page: 1 };
const featuredProducts = vodElement.getVideoFeaturedProducts({ videoId, params });Get A Video's Featured Products Meta Information
const featuredProducts = vodElement.getVideoFeaturedProductsMeta({ videoId, params });The vodElement.getVideoFeaturedProductsMeta method will return a Promise that resolves to a Video Featured Products Meta.
A Video's featured products meta is used to get a products highlighted timings. These are the start & end times a product
is featured on the video.
This methods accepts an object as its parameter with a required videoId field, along with the pagination params object.
const videoId = '7460531a-437d-4ddd-bf25-0a87536a406a';
const params = { per_page: 1 };
const featuredProducts = vodElement.getVideoFeaturedProductsMeta({ videoId, params });Get VOD Categories (Paginated)
const categories = vodElement.getCategories();The vodElement.getCategories method will return a Promise that resolves to an array of Category objects.
This method along with pagination params, supports an optional items_per_category field in params object, which can help to include category items inside the response. The default for this field is 5.
const params = { per_page: 99, page: 1, items_per_category: 999 };
const categories = vodElement.getCategories({ params });Get a VOD Category
const category = vodElement.getCategory(categoryId);The vodElement.getCategory method will return a Promise that resolves to an Category data object.
This method accepts a required categoryId parameter.
const categoryId = 'df1904d3-7b75-4039-8bab-24e15ac2632f';
const category = vodElement.getCategory(categoryId);Get Playlist Info
const playlistInfo = vodElement.getPlaylistInfo(playlistId);The vodElement.getPlaylistInfo method will return a Promise that resolves to an Playlist info data object.
This method accepts a required playlistId parameter.
const playlistId = 'ee6904d3-7b75-4039-8bab-24e15ac2632f';
const playlistInfo = vodElement.getCategory(playlistId);Sockets
Socket Element
const liveSockets = live.sockets;The liveSockets helps to join and subscribe to a number of important realtime updates or events.
Supported joinable socket event types
- join-episode-updates
- join-episode-featured-product-updates
Note: Event types are case-sensitive.
Joining join-episode-updates socket Event
const EVENT_TYPE = 'join-episode-updates';
const socketMessage = JSON.stringify({
command: EVENT_TYPE,
});
function callback(){
// Do something after joining the event!
}
liveSockets.send(socketMessage, callback);
Joining join-episode-featured-product-updates socket Event
join-episode-featured-product-updates event type needs an episode_id field to join event updates of a particular episode.
const EVENT_TYPE = 'join-episode-featured-product-updates';
const EPISODE_ID = '0c2e035f-fd07-4390-921f-1e1e865803f7';
const socketMessage = JSON.stringify({
command: EVENT_TYPE,
episode_id: EPISODE_ID,
});
function callback(){
// Do something after joining the event!
}
liveSockets.send(socketMessage, callback);Supported subscribable socket event types
- episode-status-update
- episode-featured-product-updates
Note: Event subscription only works if the corresponding parent event has been joined.
| Subscribable Event | Parent Event | | ------------------- | ------------- | | episode-status-update | join-episode-updates | | episode-featured-product-updates | join-episode-featured-product-updates |
Subscribing to an Event
const EVENT_TYPE = 'episode-status-update';
function onUpdate(message){
// Do something with the message!
console.log(message)
}
liveSockets.subscribeToEvent(EVENT_TYPE, onUpdate);