1. Reference
  2. UIKit JS

UIKit JS

UIKit JS 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.

Deprecated: UIKit JS is obsolete and should not be used for new development. We suggest switching over to UIKit Web which is our recommended UIKit for most scenarios.

Installation

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

After installing the library you can simply import the components you need.

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>

Configuration

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.

Weavy.url = "{WEAVY-SERVER}"
Weavy.tokenFactory = async (refresh) => "{ACCESS_TOKEN}"

Authentication

Next step is to configure authentication. In this quickstart, we simply call the Weavy API with curl on the command line to obtain an access_token, but in a real world scenario you should follow the steps in the authentication article for implementing a proper tokenFactory function.

curl https://{WEAVY-SERVER}/api/users/demouser/tokens -H "Authorization: Bearer {API_KEY}" --json "{ 'name': 'Demo User', 'expires_in': 7200}"

Replace the {WEAVY-SERVER} and {API-KEY} placeholders with the url and API key to your environment . The request above will return an user access token for a user with the unique id demouser (if the user doesn't exist in the Weavy environment, the user is created).

In the javascript snippet in the conguration section, replace {WEAVY-SERVER} with the url to your environment and {ACCESS_TOKEN} with the token you got in response to the Weavy API request.

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 Apps for more information.

Initialize app

Before the chat component can be loaded in your application, a corresponding Weavy app must be initialized in your Weavy environment. This is normally done from your backend code with a server-to-server request using an API key, but in this quickstart we show you how to initialize the app on your command line using curl.

curl https://{WEAVY-SERVER}/api/apps/init -H "Authorization: Bearer {API-KEY}" --json "{ app: { uid: 'demochat', name: 'Demo chat', type: 'chat' }, user: { uid: 'demouser' } }"

Example of initializing an app with the Weavy API. This request creates the app if needed and also adds the demouser as a member of the app.

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

Example: Loading app with Javascript

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

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

Example: Loading app with HTML

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

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