Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Annoto widget position is set as absolute
meaning it doesn't influence the website layout. By default the application is contained inside a single DIV that is appended to the BODY.
If you require different behavior, you can put the following DIV anywhere in your DOM:
Once this DIV element is present in the DOM, when Annoto.boot() is called, it would be detected automatically by Annoto and serve as container for the Annoto app.
This is especially useful if BODY is not your main scrollable layout.
As a rule of thumb always place the container in the same scrollable element as your video.
When the Annoto widget is closed a small Fab button with comments icon is positioned next to the player to allow users to open the widget.
In some cases you might want to implement your own open/close UI and functionality.
To hide the default Fab button set the fabDisable Ux property to true:
To show/hide the widget, use the IAnnotoApi show() and hide() methods. For more details on how to obtain the api object please refer to Using the API.
Annoto Timeline allows users to spot points of interest. The timeline can be embedded in the player or it can be positioned below the player. Lets explore the timeline configuration options:
By default, the timeline will be positioned under the player:
If overlay is true, the timeline will be positioned inside the controls of the player:
Annoto supports reporting grading to LMS (Learning Management System) using the IMS LTI 1.3 AGS.
If Annoto is integrated in a 3d party system that is taking the role of LTI Tool that processes the LTI messaging requests, Annoto still supports taking care of managing the outcomes reporting.
The above setup requires the below configurations.
Once setup, Annoto backend services will take care of always keeping the grades up to date, including retries (in case of LMS rate limiting).
For Backend Webhook setup please refer to Webhook integration for details.
During LtiResourceLinkRequest
the LMS (Platform) provides the following claims:
Those claims need to be provided to the mediaDetails of the widget:
integrationKey
is provided by Annoto during setup.
Annoto providers ends users, advanced interaction with video content. In order to do it Annoto requires access to video player API. Before Annoto can perform any action it must obtain the media source and the duration of the media.
We already support a variety of widely used player types, and constantly adding new ones. If you are using a custom player or player we don't support yet, you have 2 options:
Implement a PlayerAdaptorApi and set it in Widget's player configuration. Contributions are very welcome and appreciated :)
Contact us, we are happy to help.
Annoto widget exposes api to subscribe to analytics events so that can be used in custom integrations, for example ingested and analyzed by custom BI systems.
To listen to the events use the familiar Annoto.on() api.
The widget provides two types of events:
Discrete events of user actions such as submit a comment, vote, read a reply, click on timestamp, first video play, etc.
For more details on the event callback please refer to the AnnotoStatsEventCallback interface. For full list of event types, please refer to StatsTypeEnum.
Video analytics events that provides details about the current and historical accumulated video consumption of the user.
For more details on the event callback please refer to the AnnotoVideoBenchmarkCallback definition.
Interactions events of user actions that provide details about interactions consumed and the results of the activity.
For more details on the event callback please refer to the AnnotoCtaStatsEventCallback definition.
Welcome to Annoto developers docs!
If you are a developer, IT expert or anybody interested in integrating Annoto into your website or platform you are in the right place!
For user guides and how to setup Annoto please head to our main docs site site.
The core of Annoto is the Widget, it integrates Annoto without influencing website layout, as an overlay on top of your existing video player. We recommend reading the Widget getting started docs in any case, even if your preferred solution is Annoto Player or our Kaltura Player Plugin.
If you are looking to integrate Annoto as a widget without influencing website layout, as an overlay on top your existing video player, you are in the right place :)
At the moment we support the following players:
FlowPlayer
H5P
HTML5
JwPlayer
Kaltura V2/V7
OpenEdx
Plyr
VideoJS
Vimeo
Wistia
YouTube
Page Embed
Custom Player
Simply add the following script:
And bootstrap Annoto with the desired Application configuration:
If you are using a javascript module loader such as RequireJS. Annoto exposes a standard UMD. For example for requireJS:
The code snippet below provides a quick start for:
Widget setup
How to provide media details metadata (such as title, description, custom identifier)
How to provide group (course) details (identifier, title, description). This allows to build site hierarchy of courses/channels/etc. Once provided the discussion is scoped to the group, allowing reuse of same video in multiple groups.
User SSO (Single Sign On) authentication.
Dynamically load/destroy the widget for SPA (Single page applications)
Annoto application providers flexibility in how it integrates in the website. For full configuration options, please refer to the Config Reference. Annoto API Typescript interfaces is available via the @annoto/widget-api package.
Annoto application exposes an API. To get access to the API use the "ready" event:
For full documentation, please refer to the AnnotoApi Reference.
For more elaborate example of api usage, please refer to the Quick Start.
Annoto is compatible with all major evergreen browsers (Edge, Chrome, Mozilla, Safari).
The Annoto course dashboard can be embedded in any context as a web-component:
It's built using StencilJS.
The Annoto course dashboard can be embedded in any context as a web-component. Simply add the following scripts:
The following stylesheet:
The course dashboard can now be embedded anywhere on the page using the html tag:
The dashboard web-component is built using StencilJS. Please refer to the official docs on more information on how web-components built using StencilJS can be integrated and used: https://stenciljs.com/docs/javascript
The dashboard supports various configuration options:
To authenticate a user using SSO, the component exposes the following methods:
'token' is same JWT token that is used for widget SSO. For more information please refer to Single Sign On section.
Annoto is compatible with all major evergreen browsers (Edge, Chrome, Mozilla, Safari).
After Running the Pen, hit the "Edit On Codepen" to see the demo.
Many aspects of the widget UI can be modified via CSS Variables.
To override the defaults simply use .annoto
CSS class selector. For Example:
The widget has different utility classes that are appended to the .annoto
class based on a situation. The styling can be modified using combinations of those classes. For example, the most common state is dark theme of the widget:
For dark theme styling but only when the player is in full screen:
Below is a list of the most useful utility classes:
Please notice in most cases nnc
prefix is used. but in some cases nn
is used instead.
The main colors used by the widget are: primary, secondary, tertiary, light, medium, dark, darkest, success, warning, notice, danger.
Each main color has variants for different effects: contrast, shade and tint
Some or all the colors can be modified.
If for example primary color is modified, please make sure to set all it's variants to appropriate values, a great helper tool by Ionic can be used to generate the variants: https://ionicframework.com/docs/theming/color-generator
Those are standard colors of third party, usually they do not need to be changed.
Those colors are different shades of grey used by the widget. Please notice, the main colors light, medium, dark and darkest are used for styling.
In most cases there is no need to change any of the steps.
Annoto plugin integration for the Kaltura player
If you are using custom Kaltura player embed on your platform you are in the right place!
Kaltura player allows extending its functionality via an extensive plugin system. To simplify Annoto integration within the Kaltura player, we have developed a plugin that allows adding Annoto with a simple flashvars
configuration while allowing full customisation of the Annoto Widget.
The integration of Annoto plugin consist of 3 simple steps:
Setup Annoto plugin in the Kaltura universal studio (KMC) or using custom javascript.
Add javascript to modify the configuration of the Widget to fit your needs.
(Optional) Implement Single Sign On (SSO) integration and use the widget API.
If you are using Kaltura Media Space or KAF (Kaltura integration inside LMSs), Annoto is a and can be enabled in your platform with a click of a button.
For more information on the Kaltura player toolkit and plugins please refer to .
While multiple players can be setup on a single page. The Widget can be loaded only to a single player at a time. The widget is managed by a singleton, each time one of the players calls loadWidget()
, the widget is loaded in that player.
For more details please refer to the .
Utility Class
Description
nnc-dark-theme
Used it different cases such as when widget is an overlay inside the player, player is in full screen, or configured as the default theme in the widget configuration.
nn-player-fs
Added when player is in full screen
nnc-mobile
Added when the user uses a mobile device, and the widget applies UX for mobile devices.
nn-is-open
Widget is in open state.
nn-[PAGE]-page
Changed based on the view the widget is showing. Common views:
nn-notes-page
nn-comments-page
nn-preferences-page
nnc-rtl
Widget has Right to Left layout.
In Customise Annoto Widget configuration we have learned how to listen to Kaltura player events and get access to the widget configuration and the API:
The annotoApi
can be used to accomplish various tasks such as dynamically hide/show the widget, load new configuration and maybe the most common task to perform Single Sign On (SSO) authentication:
For more information regarding SSO, please refer to the Annoto SSO Technical Guide or contact us at support@annoto.net.
When the Annoto plugin is loaded by the Kaltura player, it triggers custom events that allows you to get access to the configuration and the API for full customisation and control of the widget.
To subscribe to Kaltura player events please use Kaltura player API:
For detailed information on the Kaltura player API, please refer to http://player.kaltura.com/docs/api
annotoPluginSetup
is triggered first by the Annoto plugin and provides opportunity to modify the Annoto widget configuration before the widget is bootstrapped.
Once the widget is bootstrapped by the plugin annotoPluginReady
is triggered and provides access to the Annoto API.
Below is an example of modifying some basic widget options:
config is already setup by the Kaltura Annoto plugin, so we need only to override the required configuration, such as clientId, getPageUrl hook, etc. DO NOT CHANGE THE PLAYER TYPE OR PLAYER ELEMENT CONFIG.
For the default widget configuration used by the plugin please refer to: https://github.com/Annoto/kaltura-plugin
The plugin exposes annotoPluginReady
event that provides access to the API for implementing the SSO functionality.
Advanced topic
In some cases you might not have the required configuration for the Annoto Widget when annotoPluginSetup
is triggered, or would want to postpone the bootstrap of the widget until some condition is met.
Until delayDoneCallback
is called, the widget won't be bootstrapped and annotoPluginReady
won't be triggered.
If doneCb is not called, the widget is not bootstrapped. This can be used to dynamically decide on which videos to load the annoto plugin.
Please follow the steps below to setup the plugin:
Login to KMC at https://kmc.kaltura.com.
At the "Studio" choose your player.
Navigate to the plugins menu on the left panel:
Create a new plugin by pressing on the ‘Create New Plugin’ button and name it annoto
.
Naming the plugin "annoto" is mandatory (this is just how Kaltura works).
Define the following Configuration options:
iframeHTML5Js
: https://cdn.annoto.net/kaltura-plugin/latest/plugin.js
customerKey
: eyJhbGciOiJ...
The customer key is provided by Annoto.
Specifying the customer key is optional and can be done at Customise Annoto Widget configuration step.
If Annoto LTI is used, the customerKey is not required
If customerKey is not provided, Annoto Will load in Demo Mode.
Demo Mode allows you to try out the product but all comments created are not saved after page refresh.
Save the player settings.
The Annoto Widget is loaded inside the wistia player iframe so direct access to the Widget API and configuration is not possible.
Luckily we provide a helper script that exposes API to configure the widget and perform API actions.
The Iframe Client API requires the Wistia player Iframe embed element as constructor argument: new AnnotoIframeApi.Client(document.getElementById("wistia-player-id"))
Once configuration object is ready, call next(config)
to bootstrap the widget inside the Wistia player iframe.
config.widgets[0].player.type and element
are setup for Wistia internally by the plugin.
If player configuration callbacks are provided:
config.widgets[0].player.mediaDetails()
config.widget[0].player.mediaSrc()
They are called synchronously when next(config) is called. So the media details and the source should be already available at the time when next(config) is called.
The callbacks are called once during the setup.
It is NOT recommended to use theconfig.widget[0].player.mediaSrc()
for the Wistia player plugin.
Wistia iframe embeds take the exact same JSON parameters as a Standard embed, but they must be properly URL-encoded using a bracket syntax.
To add the Annoto plugin, add the following URL query param to the iframe src:
For example an iframe embed may look something like that:
Advanced topic
If setting up Annoto plugin via Kaltura universal studio is not possible, or simply if more customisation is required. It is possible to compile a custom Annoto plugin for the Kaltura player and add it to the player via Javascript.
Please notice, according to Kaltura documentation:
"Flashvar based resource includes will only work on relative paths. You should save absolute external resource URLs to your configuration file for them to work in your production players."
The integration of Annoto plugin consist of 3 simple steps:
Setup Annoto plugin in the Wistia player embed code.
Add javascript to modify the configuration of the Widget to fit your needs.
(Optional) Implement Single Sign On (SSO) integration and use the widget API.
Under the hood, we use for communicating with the widget in the Iframe.
annoto.onSetup()
provides opportunity to config set the , for example configure the clientId
(Annoto API key).
For more information please refer to .
The widget would not load in the Wistia player Iframe yet. The widget is bootstrapped and loaded once the setup is complete. Please read for more details.
Please refer to for the recommended setup method.
Annoto plugin is an open source and can be compiled into a single javascript file:
The plugin method is only for the , for regular embeds, please use the (set player type to wistia
).
Wistia player allows extending its functionality via an extensive . To enable Annoto integration within the we have developed a plugin that allows adding Annoto via simple configuration.
For more information on the Wistia player and plugins please refer to .