OpenChat Embed library

Within OpenChat it is possible to create custom channels within a community that can be used to embed third-party content.

This can be done by simply specifying a url and nothing more and that can work perfectly well.

However, if you would like to integrate more tightly with OpenChat and create some content that is capable of communicating with the host OpenChat instance and that can be easily themed so that it looks at home within OpenChat, then this library will help you do that.

Pre-requisites

To host content within OpenChat please make sure that your content security policy allows it to be hosted within an iframe. Many third party sites will have a content security policy that prevents this. If this is the case, the content cannot be hosted within OpenChat and only the developers who control the site's content security policy can rectify that.

Furthermore, please make sure that the third party content that you are embedding complies with OpenChat's terms and conditions. We reserve the right to take down any third party content that violates these terms.

Installation

Install the library into your site in the normal way:

npm i @open-ic/openchat-embed

Usage

The library simply provides an initialise function. This initialise function will send a message to the OpenChat host to say that it is ready to initiate a handshake. When OpenChat receives this message it will respond by sending the embedded frame an init message containing some information about the host OpenChat system. Initially the embedded content will receive the currently selected theme and the username of the OpenChat user.

The library will take care of writing all of the css variables used by OpenChat into the target document. This enabled the author of the embedded content to simply make use of the same css variables within their own UI ensuring that it will match the selected theme of the host OpenChat instance.

The initialise function is an async function and you should await the promise it returns to determine when the link between the client and the host is established. The promise will resolve with an instance of an OpenChatEmbedClient. At the moment this client will only give you access to the OpenChat username, but it future iterations it may also give you the ability to interact with the OpenChat host to perform various functions.

Example Usage

<script lang="ts">
  import { initialise, type OpenChatEmbedClient } from "$lib/openchat-embed";
  import { onMount } from "svelte";

  let client: OpenChatEmbedClient | undefined = undefined;

  onMount(async () => {
    // call the library's initialise function and wait for it to complete
    client = await initialise();
  });
</script>

{#if client !== undefined}
  <div class="content">
    <h1>This is an external page</h1>
    <p>
      It's not a part of OpenChat but it should look right at home if we apply
      the right css variables.
    </p>

    <p class="smallprint">All you have to do is use the variables.</p>

    <button on:click={() => alert("click")}> Welcome {client.username}! </button>
  </div>
{/if}

<style lang="scss">
  .content {
    padding: 24px;
  }
  h1 {
    // this is the base level text color from the OpenChat theme
    color: var(--txt);
  }

  button {
    padding: 12px;
    // this is the button background color from the OpenChat theme
    background: var(--button-bg);

    // this is the button text color from the OpenChat theme
    color: var(--button-txt);

    // this is the button border radius from the OpenChat theme
    border-radius: var(--button-rd);
    cursor: pointer;
    border: none;
    min-height: 45px;
    min-width: 150px;
    position: relative;

    // this is the button text shadow from the OpenChat theme
    text-shadow: var(--button-txt-sh);

    // this is the button box shadow from the OpenChat theme
    box-shadow: var(--button-sh);

    &:hover {
      box-shadow: var(--buton-hv-sh);
    }

    &:hover {
      background: var(--button-hv);
      color: var(--button-hv-txt);
    }
  }

  .smallprint {
    font-size: 14px;
    color: var(--txt-light);
  }
</style>