# Getting Started

{% hint style="success" %}
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 :)
{% endhint %}

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:

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

And bootstrap Annoto with the desired Application configuration:

```markup
<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>
```

{% hint style="info" %}
If you are using a javascript module loader such as RequireJS. Annoto exposes a standard [UMD](https://github.com/umdjs/umd). For example for requireJS:
{% endhint %}

```javascript
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)&#x20;

```typescript
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](https://annoto.github.io/widget-api/interfaces/Config.IConfig.html). Annoto API Typescript interfaces is available via the [@annoto/widget-api package](https://www.npmjs.com/package/@annoto/widget-api).

## Using the API

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

```javascript
// 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](https://annoto.github.io/widget-api/interfaces/Api.IAnnotoApi.html).

{% hint style="info" %}
For more elaborate example of api usage, please refer to the [Quick Start](#quick-start).
{% endhint %}

## Browser Compatibility

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