npm package: @intheroomglobal/speakeasy-embed
Description: In The Room speakeasy embed
Author: Lee Ellam
Latest version: 0.5.2

# Speakeasy Embed

Library to embed Speakeasy experiences within a website.

## Installation

You can install using your favourite package manager, or import from jsdelivr directly into your webpage.

### Using npm (or yarn, or pnpm)

```
npm install @intheroomglobal/speakeasy-embed
```

### HTML

```html
<script type="module">
  import SpeakeasyEmbed from "https://cdn.jsdelivr.net/npm/@intheroomglobal/speakeasy-embed/dist/browser/embed.js";

  SpeakeasyEmbed.embed({
    id: "<YOUR EXPERIENCE ID>"
  });

  // ...

  SpeakeasyEmbed.destroyAll();
</script>
```

## Usage

The embed can either be called programmatically, or auto-initialised via a script tag for users who do not wish to set anything up themselves. Embeds can be instantiated with `const embed = new SpeakeasyEmbed(...)` and destroyed with `embed.destroy()` if you want to keep track of the instance yourself, or instantiated via factory method `SpeakeasyEmbed.embed(...)` and destroyed via `SpeakeasyEmbed.destroyAll()` if you don't need fine grained control. Options passed remain consistent between both methods.

Styles are automatically injected when using script embeds. In JavaScript, you can `import '@intheroomglobal/speakeasy-embed/dist/es/embed.css';` and have your bundler take care of the CSS (or create a `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@intheroomglobal/speakeasy-embed/dist/es/embed.css" />` manually).

Passing a `version` date string will ensure you are using the latest version of the Speakeasy API. The easiest way is to pass the current date of use, in `yyyy-mm-dd` format. The earliest supported version is `2024-01-01`.

### Bubble

A chat-bubble style experience. Opens on click, and maximises once interacted with.

#### JS

```js
import SpeakeasyEmbed from "@intheroomglobal/speakeasy-embed";

new SpeakeasyEmbed({
  id: "<YOUR EXPERIENCE ID>",
  version: "2024-01-01"
});
```

#### Script embed

```html
<script
  src="https://cdn.jsdelivr.net/npm/@intheroomglobal/speakeasy-embed/dist/browser/embed.js"
  id="<YOUR EXPERIENCE ID>"
  data-version="2024-01-01"
></script>
```

### Inline

An inline experience that shows in an element on the page in the regular flow. Maximises once interacted with.

#### JS

```js
import SpeakeasyEmbed from "@intheroomglobal/speakeasy-embed";

new SpeakeasyEmbed({
  id: "<YOUR EXPERIENCE ID>",
  parent: ".some-selector", // Either selector or DOM element
  version: "2024-01-01"
});
```

#### Script embed

```html
<script
  src="https://cdn.jsdelivr.net/npm/@intheroomglobal/speakeasy-embed/dist/browser/embed.js"
  id="<YOUR EXPERIENCE ID>"
  data-parent=".some-selector"
  data-version="2024-01-01"
></script>
```

### Fullscreen

A fullscreen experience. Cannot be minimised, so should live on it's own page.

#### JS

```js
import SpeakeasyEmbed from "@intheroomglobal/speakeasy-embed";

new SpeakeasyEmbed({
  id: "<YOUR EXPERIENCE ID>",
  fullscreen: true,
  version: "2024-01-01"
});
```

#### Script embed

```html
<script
  src="https://cdn.jsdelivr.net/npm/@intheroomglobal/speakeasy-embed/dist/browser/embed.js"
  id="<YOUR EXPERIENCE ID>"
  data-fullscreen
  data-version="2024-01-01"
></script>
```

## Additional options

### Aspect Ratio

To change the aspect ratio of the embed

#### JS

```js
new SpeakeasyEmbed({
  id: "<YOUR EXPERIENCE ID>",
  aspectRatio: "16:9",
  version: "2024-01-01"
});
```

#### Script embed

```html
<script
  src="https://cdn.jsdelivr.net/npm/@intheroomglobal/speakeasy-embed/dist/browser/embed.js"
  id="<YOUR EXPERIENCE ID>"
  data-aspect-ratio="16:9"
  data-version="2024-01-01"
></script>
```

### Inline experiences

To prevent experiences maximising when interacted with. Ignored by fullscreen embeds.

#### JS

```js
new SpeakeasyEmbed({
  id: "<YOUR EXPERIENCE ID>",
  inline: true,
  version: "2024-01-01"
});
```

#### Script embed

```html
<script
  src="https://cdn.jsdelivr.net/npm/@intheroomglobal/speakeasy-embed/dist/browser/embed.js"
  id="<YOUR EXPERIENCE ID>"
  data-inline
  data-version="2024-01-01"
></script>
```

### Styling issues

The embeds are built in such a way as to work with most websites out of the box. If you have CSS issues (usually layer based problems with drag and drop editors such as Wix, Squarespace, etc), you can add a style tag to target the conversation to fix the issue.

```html
<style>
  .speakeasy-embed__iframe {
    z-index: 101;
  }
```