TABLE OF CONTENTS


Overview

VIDIZMO’s entire portal is nothing but a lay-out of various web components intricately stitched together in a seamless fabric of HTML and CSS. All of these web components are JavaScript-based rich application controls that can be incorporated in any other web page or application.


This documentation shall help you get started with using VIDIZMO's application widgets, however if you want to read about the different available Widgets in our application and sketch out possibilities of how they can be incorporated in your own webpage or interacted with, I suggest you read: VIDIZMO Widgets Library.


This guide has been broken into the following topics:


What are Web Components?

The browser gives us an excellent tool for structuring web applications - Hyper-Text Markup Language (HTML). Let me explain how these widgets will work with the HTML in your web-page. When you introduce our widgets in your code, they are essentially custom elements or new HTML tags that are not present in the default HTML tag library. While HTML is declarative, portable, well supported, and easy to work with, its vocabulary and extensibility are limited.


This is where VIDIZMO comes in with its own elements, whose definition is contained in a separate widgets.js file. This is how it works: widgets.js finds custom elements in an HTML page and using the element's definition, it converts basic, functional mark-up into rich interactive widgets. In addition, there are a number of functions of widgets-js that allow developers to work with VIDIZMO content dynamically, after the page has loaded.


In addition, JavaScript widgets allow you to dynamically load the web page using DOM by extending the HTMLElement to inherit the entire DOM API. This means that any properties or methods that you add to the class become part of the element's DOM interface.


The next sections will walk you through the process of setting up your web site to be able to seamlessly integrate with VIDIZMO application widgets - during which you will also learn more about its powerful capabilities.


Installation Instructions

Include the widgets.js library in your Web Page

You need to include these two files on your web page, so that you can use VIDIZMO widgets there.


The js file contains specific JavaScript code that implements a widget as an element of the user interface on your website. The file contains classes for rendering the custom elements and dynamically building the DOM element.


The css file contains the default styling of VIDIZMO Widgets that help lay them out elegantly on your site.


Here are the paths of the files that you need to include in the header of your web application:

  1. {tenantUrl}/static/compiled/widgets/styles.css
  2. {tenantUrl}/static/compiled/widgets/widgets.js


For optimum web page performance, it is recommended to include the VIDIZMO Widgets library once in your HTML page template, so that you do not need to do it for every web page.


You need to include these files directly from your Portal's URL. This is a highly recommended approach because after every release, our widgets and files are updated - these changes shall remain synced on your website if you include them directly from our servers.


You can also include these files by downloading them locally from the specified path, and including it from your own application server but this is not a recommended approach and may lead to unforeseen inconsistencies in Widgets rendering.


Supported Browsers

VIDIZMO Web Application Widgets work in all major browsers:

  • Chrome
  • Opera
  • Firefox
  • Safar 7+
  • Edge/ IE11+


Who can use VIDIZMO Widgets

In order to use Widgets on your website, you need to have your site domain whitelisted in VIDIZMO Portal. There are certain authorized Portal users who can whitelist website domains in a Portal such as Managers and Administrators.


API Key Generation

The process of whitelisting your IP Address or Web Domain URL will generate a unique API key against those domains. This API key is associated with the user using whose account the key was generated from Portal Settings. You can custom-set its expiry date as well, after which the site shall no longer be able to consume our Widgets API.


Below is a demonstration of how those Keys are managed against domains and the administrative users who generated them:




This API key is also used as an access token to run administrative actions on the Portal such as user registration incase of your own organizational single sign-on. Such as when a user signs into your own website, they will be automatically registered in VIDIZMO Portal as a Viewer role on behalf of the Portal Manager/Administrator against whom the Key had been generated. More about the authentication methods have been covered in the later section.


Design the look and feel of your Widgets

When included in a web page, VIDIZMO widgets inherently adapt to your site branding, let me explain how.

Now as you understand that our web components are essentially built using custom elements which extend the basic HTML element - hence, using our custom elements is no different than using a <div> or any other element. You can then style and arrange these elements just as you would arrange any other HTML elements on your website.


VIDIZMO widgets use Bootstrap version 3 as a framework for styling and layout in combination with Font Awesome version 5.


Authenticate Users

Once you have included Widgets on your site, you want to be able to track user engagement on the content included within the Widgets, or simply want to be able to authenticate users so that they can view the content, which may otherwise be not accessible to anonymous users.


There are three ways in which you can proceed with authenticating users for the Widgets included on your site.


Use your own Organization-Wide Web Login

VIDIZMO seamlessly integrates with your web application by exchanging certain key user profile information. This information is then used to register your applications’ user as a “Viewer” in VIDIZMO Portal. 


In order to allow VIDIZMO to exchange this information, the browser window object should have the following attributes included:


AttributeData TypeIs RequiredDescription
apiKeyStringRequiredFor a successful Single Sign-On (SSO) authentication process, including the apiKey generated when authorizing widgets shall be copied here.
This API key shall be used as a token to run administrative actions on the Portal such as user registration.
currentUICultureNameStringOptionalVIDIZMO application can be converted to multiple languages. so this attribute can be used to change the portal language to any of the available VIDIZMO portal language.

emailAddressStringRequiredSet this attribute if you have already authenticated users and you want them to use VIDIZMO Widgets using Single Sign-On.
firstNameStringRequiredThis attribute would only be used once when a new user will be login using Single Sign-On.
lastNameStringOptionalThis attribute would only be used once when a new user will be login using Single Sign-On.
groupsStringOptionalFill this array if you want to create new groups in VIDIZMO and make the current user part of it. If the group(s) already exists, simply the user would be the part of it.


Note: By default, language of VIDIZMO Portal is set as English.


Note: All the users registered as Federated users will be registered on the behalf of Manager+ user against whom API Key was generated while authorizing Widgets for your domain.


Use VIDIZMO login

As soon as you load VIDIZMO widgets on a web page, based on the security policy of the Portal and the media, they will trigger the login component when there is no information found against user authentication. 

This will allow the user to enter VIDIZMO login credentials to gain access to the content within the component.


Hence, if you use VIDIZMO login, there is no additional configuration required.


Use SSO Login using VIDIZMO Supported IDPs

If you wish to use a third-party Identity Provider service, VIDIZMO provides seamless integration with various single sign-on authentication providers, more about which can be read here: Understanding Single Sign-On in VIDIZMO


Here, the user can avail the option to log in by being redirected to the login page of your preferred IDP. When you sign in here, the IDP shall pass on an auth token to VIDIZMO which shall then be passed onto your application for authentication.


You may also enable “Force Login” against a particular SSO Provider to automate user authentication if your users are already logged into their SSO Providers in a separate tab within the same browser.


Control Loading and Initialization of Widgets

By default, VIDIZMO Widgets, when included on a web page, initialize themselves as soon as the page is loaded without any need of external command.


After initialization, the widgets will render on the page only if the domain URL of the site on which they have been used is whitelisted in VIDIZMO portal


But if you want to lazy-load these web components, or want to control when the widgets initialize themselves, you need to make sure the Widget is dynamically inserted into the DOM only when it needs to be initialized.