Getting Started

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

Setup

Simply add the following script:

<script src="https://cdn.annoto.net/widget/latest/bootstrap.js"></script>

And bootstrap Annoto with the desired Application configuration:

<script>
  // Minimal Application configuration
  var config = {
    /* set to your client id after registration. */
    clientId: '',
    widgets: [
      {
        player: {
          /* type of the player */
          type: 'youtube',
          /* DOM element or DOM query selector of the player */
          element: '#player-element'
        }
      }
    ],
  };

  window.Annoto.boot(config);
</script>

If you are using a javascript module loader such as RequireJS. Annoto exposes a standard UMD. For example for requireJS:

requirejs(["https://cdn.annoto.net/widget/latest/bootstrap.js"], function(Annoto) {
    //This function is called when annoto-bootstrap.js is loaded.
    Annoto.boot(config);
});

Quick Start

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)

import { Annoto, IAnnotoApi, IConfig } from '@annoto/widget-api';
  
interface Global extends Window {
  Annoto: Annoto;
}
const global = window as Global;

const annotoConfig: IConfig = {
  clientId: 'eyJhbGciOiJIUzI1...', // ClientId provided by Annoto
  group: {
    id: '2613a9a5-7245', // custom group/course/channel identifier
    title: 'Annoto Getting Started Course',
    // description: '...', // (optional)
  },
  hooks: {
    mediaDetails: (): IMediaDetails | Promise<IMediaDetails> => {
      return {
        title: 'Quick Start',
        // id: '7245-asfa', // (optional) unique media identifier
        description: 'Quick start for setup on custom platform', // (optional)
      };
    }
  },
  widgets: [
    {
      player: {
        type: 'videojs', // type of the player
        element: '.video-js' // DOM element or DOM query selector of the player
      }
    }
  ],
};

let annotoAPI: IAnnotoApi; // api object placeholder

/**
 * call to authenticate the user using SSO
 * @param token - JWT user token
 */
const authAnnoto = async (token: string) => {
  if (annotoApi) {
    return await annotoApi.auth(token);
  }
  console.log('Annoto api or sso token not ready yet');
}

/**
 * boot Annoto or loaded a new configuration (for example on DOM change)
 */
const loadOrBootAnnoto = async (config: IConfig) => {
  if (annotoApi) {
    return annotoApi.load(config);
  }
  
  global.Annoto.on('ready', (api: IAnnotoApi) => {
    annotoApi = api;
    authAnnoto();
  });
  return global.Annoto.boot(config);
}

/**
 * Destroy the widget and remove from DOM
 * Can be used by single page applications when leaving the page
 */
const destroyAnnoto = async () => {
  if (annotoApi) {
      return annotoApi.destroy();
  }
}
 
// Somewhere on the page with video where annoto needs to be loaded
loadOrBootAnnoto(annotoConfig);

Configuration

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.

Using the API

Annoto application exposes an API. To get access to the API use the "ready" event:

// Application configuration
const annotoConfig = {
  /* ... */
};
  
let annotoAPI;
window.Annoto.on('ready', function (api) {
  annotoAPI = api;
  // Authenticate SSO User
  annotoApi.auth(userToken);
});

window.Annoto.boot(config);

For full documentation, please refer to the AnnotoApi Reference.

For more elaborate example of api usage, please refer to the Quick Start.

Browser Compatibility

Annoto is compatible with all major evergreen browsers (Edge, Chrome, Mozilla, Safari).