# oovvuu-plugin <!-- omit in toc -->

Oovvuu Plugin provides a simple way for publishers to embed videos into their articles without leaving their CMS.

## Table of Contents <!-- omit in toc -->

- [Usage](#usage)
  - [via jsDelivr](#via-jsdelivr)
    - [Backwards compatibility script available for implementations before `type="module"` requirement](#backwards-compatibility-script-available-for-implementations-before-typemodule-requirement)
- [Icons](#icons)
- [API](#api)
  - [**oovvuuPlugin**](#oovvuuplugin)
- [Types](#types)
  - [**CmsConfig**](#cmsconfig)
  - [**Embed**](#embed)
- [Redirect Login Flow](#redirect-login-flow)
- [Author](#author)
- [License](#license)

## Usage

### via jsDelivr

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/oovvuu-plugin@1/dist/oovvuu-plugin.index.js" onload="setOovvuuConfig()"></script>
<script>
  function setOovvuuConfig() {
    oovvuuPlugin.setConfig({
      clientId: "client-id",
      cmsName: "cms-name",
      articleId: "article-guid",
      onAddEmbed: (embed) => {
        // Implement this to insert the embed code into the article
        console.log(JSON.stringify(embed, null, 2));
      },
      headline: "article-headline",
    });
    console.log(oovvuuPlugin.version);
  }
</script>

...

<button onclick="oovvuuPlugin.open()">Select Videos</button>
```

#### Backwards compatibility script available for implementations before `type="module"` requirement
<span style="color:orange;">**:warning: Not intended for new implementations**</span>  
This uses the old filename so existing implementations can remain working.  
This will simply insert the new script into the page head automatically.
```html
<script src="https://cdn.jsdelivr.net/npm/oovvuu-plugin@1/dist/oovvuu-plugin.min.js"></script>
```

## Icons

Oovvuu logos are available via jsDelivr.

| Image           | Example                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------- |
| oovvuu-logo.png | <img src="https://cdn.jsdelivr.net/npm/oovvuu-plugin/assets/oovvuu-logo.png" height="30" /> |
| oovvuu-mark.png | <img src="https://cdn.jsdelivr.net/npm/oovvuu-plugin/assets/oovvuu-mark.png" height="30" /> |

Example use in buttons

```html
<button>
  <img
    src="https://cdn.jsdelivr.net/npm/oovvuu-plugin/assets/oovvuu-logo.png"
    height="20"
  />
</button>

<button>
  <img
    src="https://cdn.jsdelivr.net/npm/oovvuu-plugin/assets/oovvuu-mark.png"
    height="20"
  />
  Select Videos
</button>
```

## API

### **oovvuuPlugin**

The core interface of the plugin.

**_Properties_**

| Name      | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| `version` | string | The current version of the plugin. |

**_Functions_**

`close(): void`

This closes the plugin.

`getConfig(): CmsConfig`

This gets the configuration for the plugin. It raises an exception if the configuration is not set.

`open(config?: CmsConfig): void`

This opens the plugin. An optional `config` may be passed as a convenience; it can be partial similar to `setConfig`.

`setConfig(config: CmsConfig): void`

This sets the configuration for the plugin. It allows partial updates to the configuration.

`handleLoginCallback(): Promise<void>`

This sets the handles the Auth0 login callback after a redirect login.

```js
// Update some configuration leaving the rest as is.
oovvuuPlugin.setConfig({
  articleId: "new-article-id",
  headline: "new-article-headline",
  onAddEmbed: (embed) => {
    // do something
  },
});
```

## Types

### **CmsConfig**

A configuration object for the plugin.

**_Properties_**

| Name                | Type   | Description                                                                                            |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `articleId`         | string | The unique identifier for the article.                                                                 |
| `clientId`          | string | A customer-specific identifier that will be used in the authentication process.                        |
| `cmsName`           | string | A globally unique name for the publisher's Content Management System, such as its domain name.         |
| `headline`          | string | The headline of the article.                                                                           |
| `loginCallbackPath` | string | The callback path used to handle Auth0 login callback. This page needs to call `handleLoginCallback()` |

**_Functions_**

`onAddEmbed(embed: Embed): void`

A JavaScript callback that is invoked every time the user creates an embed. The embed object is passed in.

`onClose(): void`

A JavaScript callback that is invoked when the plugin is closed.

### **Embed**

The embed object passed to the `onAddEmbed` callback.

**_Properties_**

| Name                      | Type   | Description                                                                             |
| ------------------------- | ------ | --------------------------------------------------------------------------------------- |
| `ampEmbedCode`            | string | An HTML embed to be used on amp pages.                                                  |
| `articleId`               | string | This is the id of the article as set in the plugin configuration.                       |
| `displayTitle`            | string | A title that can be displayed above the video or collection for display purposes.       |
| `embedCode`               | string | The full embed code for the chosen video or collection.                                 |
| `embedId`                 | string | The unique identifier for the embed of the chosen video or collection.                  |
| `headline`                | string | The headline for the article.                                                           |
| `linkToDownloadThumbnail` | string | A URL from where the poster image for the chosen video or collection can be downloaded. |
| `playerScriptUrl`         | string | The url for Oovvuu’s playback script.                                                   |

## Redirect Login Flow

In cases where the popup login flow is blocked by CORS, we allow the use of a redirect login flow.

This requires a dedicated page to load the plugin for handling the callback. This page needs to only call the `oovvuuPlugin.handleLoginCallback()` function which will handle the login and return the user to the previous page.

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/oovvuu-plugin@1/dist/oovvuu-plugin.index.js" onload="setOovvuuConfig()"></script>
<script>
  function setOovvuuConfig() {
    oovvuuPlugin.setConfig({
      clientId: "client-id",
      loginCallbackPath: "/path-for-callback",
    });
  }
</script>

<script>
  // Wait for page to load before attempting to call
  window.addEventListener("load", function () {
    oovvuuPlugin.handleLoginCallback();
  });
</script>
```

## Author

[Oovvuu](https://oovvuu.com/)

## License

See the [LICENSE](LICENSE) file for license rights and limitations (MIT).