1. Get started
  2. JS UI kit

Get started with the JS UI kit

The JS UI kit is a JavaScript library that you add to your existing app or website. The library enables you to quickly add collaboration features such as messaging, document collaboration, and more to your application. It handles authentication between your app and Weavy, and features an API for initializing and rendering Weavy UI components that are rendered and served from the Weavy environment.

See also: JS UI kit reference

Prerequisites

Getting started

Follow the steps below and we'll show you how to install and get started with the JS UI kit.

1. Add the JS UI kit

The easiest way to install the library is by adding it with npm install (you can also clone the open-source weavy-dropin-js repo and build it yourself).

npm install @weavy/dropin-js

import { Weavy, Chat } from "@weavy/dropin-js";

Another option is to include a <script> tag in the <head> element of your page (in the example below we reference a pre-built version from the jsDelivr CDN).

<script src="https://cdn.jsdelivr.net/npm/@weavy/dropin-js/dist/weavy.js" crossorigin="anonymous"></script>

2. Configure Weavy

Before adding apps to your page, you need to configure the url to your environment and set up the authentication flow.

The minimum configuration requires the url to your Weavy environment and a tokenFactory function that is responsible for providing an access_token for your authenticated user. Check out the authentication documentation for details on how to implement this function.

You can provide the configuration either via javascript or via the <weavy-environment /> HTML tag.

Tip: If your script may run multiple times, you can use Nullish coalescing assignment via ??= to make sure URL and tokenFactory only is assigned once.

Javascript only

Weavy.url = "{WEAVY_ENVIRONMENT_URL}"
Weavy.tokenFactory = async () => "{ACCESS_TOKEN}"

Using HTML

<weavy-environment 
  url="{WEAVY_ENVIRONMENT_URL}"
  token-factory="async () => '{ACCESS_TOKEN}'"
  />

3. Get a user access token

The tokenFactory should return a valid access_token for a user in your application. In this quickstart, we simply call the Weavy API to create a Weavy user. The response will contain an access_token that we can use.

curl -H "Authorization: Bearer {WEAVY_APIKEY}" -H "Content-Type: application/json" {WEAVY_ENVIRONMENT_URL}/api/users/demouser/tokens -d "{'name': 'Demo User', 'expires_in': 7200}"

Example of creating a user and get an user access token with the Weavy API

Replace the {WEAVY_APIKEY} and {WEAVY_ENVIRONMENT_URL} with a Api Key and url from your your Weavy account. The api request above will return an user access token for the user with the unique id demouser. If the user doesn't exist in the Weavy environment, the user is created.

In the javascript code snippet in step 2, replace {WEAVY_ENVIRONMENT_URL} with the url to your Weavy account environment and {ACCESS_TOKEN} with the token you get in response to the Weavy API request.

Please note that the tokenFactory should always return an access token for the signed in user in your application. We highly recommend that the tokenFactory function calls an endpoint on your backend which in turn requests an access token from the Weavy environment.

4. Adding apps

After initializing the Weavy instance you can start adding Weavy apps (UI components) to your website. The apps are presented using server rendered HTML and integrated by the frontend using iframe technology. See Working with apps for more information.

Initializing the app

Before you can use an app you must initialize the app in the backend. This is done from your backend using the API key. This initialization will create the app if needed and also allows you to add the user to the app.

curl -H "Authorization: Bearer {WEAVY_APIKEY}" -H "Content-Type: application/json" {WEAVY_ENVIRONMENT_URL}/api/apps/init -d "{ app: { uid: 'demochat', name: 'Demo chat', type: 'chat' }, user: { uid: 'demouser' } }"

Example of initializing an app and adding a user with the Weavy API

Load the app

In this example we initialize a chat app. As you can see you need to supply a DOM element (container) to place it in, for instance a <div>. The container can be referenced a DOM element or as a CSS selector. The app automatically adapts to the size of the container (if your container does not have a size the app will not be visible).

Using Javascript

<div id="chat-container" style="height:600px;"></div>

const chat = new Chat({ uid: "demochat" })
document.getElementById("chat-container").append(chat);

HTML only

<div id="chat-container" style="height:600px;">
  <weavy-chat uid="demochat" />
</div>

A complete example

Here is an example of how to instantiate a Messenger app. In this example we're loading the script from a CDN, configure Weavy via javascript and provide a Messenger app using HTML.

Note: You need to configure a full authentication flow and provide the url to the environment you have created in your Weavy account.

HTML


<head>
  ...
  <!-- Using package from CDN -->
  <script src="https://cdn.jsdelivr.net/npm/@weavy/dropin-js/dist/weavy.js" crossorigin="anonymous"></script>
  <script>
    Weavy.url = "{WEAVY_ENVIRONMENT_URL}",
    Weavy.tokenFactory = async () => "{ACCESS_TOKEN}"
  </script>
  ...
</head>
<body>
  ...
  <!-- A container to place the chat in (height is used to define a size on the container) -->
  <div style="height: 600px">
    <weavy-messenger />
  </div>
  ...
</body>

Troubleshooting

If things are not working as expected, check the output in the console window of your browser for any warnings and/or errors.

Weavy Docs