TABLE OF CONTENTS
- What are Web Components?
- Installation Instructions
- Who can use VIDIZMO Widgets
- Design the look and feel of your Widgets
- Authenticate Users
- Control Loading and Initialization of Widgets
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.
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.
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.
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:
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.
VIDIZMO Web Application Widgets work in all major browsers:
- Safar 7+
- Edge/ IE11+
Who can use VIDIZMO Widgets
In order to use Widgets on your website, you need to enable the Widgets app in your portal. There are certain authorized Portal users who can enable this app such as Managers and Administrators.
However, if your content/portal is not anonymously accessible, then you will need to generate an API key against your site domain to register users from your site directly into VIDIZMO portal.
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.
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:
|Attribute||Data Type||Is Required||Description|
|apiKey||String||Required||For 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.
|currentUICultureName||String||Optional||VIDIZMO 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.|
|emailAddress||String||Required||Set this attribute if you have already authenticated users and you want them to use VIDIZMO Widgets using Single Sign-On.|
|firstName||String||Required||This attribute would only be used once when a new user will be login using Single Sign-On.|
|lastName||String||Optional||This attribute would only be used once when a new user will be login using Single Sign-On.|
|groups||String||Optional||Fill 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.