# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.annoto.net/developers/widget/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.