Get Started with Client SDK

Reading time: 10 mins

What is Client SDK?

The Weavy Client SDK 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. Another common use-case is combining several components for more advanced scenarios.

Weavy instance

The Weavy instance is the main entry point used when embedding Weavy. It sets up a connection to a Weavy server and handles real-time communication, event distribution, and more.

Embedding Weavy into an application starts with adding a reference to the Weavy javascript library and initializing a new Weavy instance.

<script src="weavy.js"></script>


<script>var weavy = new Weavy();</script>


 

Before using the client SDK you need an instance of the Weavy backend up and running somewhere. It can be a local development machine, an instance deployed to the cloud, or an on-prem server.

Configure a client on the server

You'll need a Client configuration on the server to be able to authenticate from the Client SDK. Sign in to the Weavy server instance with an administrator account. Then navigate to https://{your-weavy-url}/manage/clients.

To add a new client, click the plus icon and specify Display Name, Client Id and Client Secret.

The Client id and Client secret should be kept secure! Do not share the information in publicly accessible areas such as GitHub, client-side code, and so forth.

Client script configurator

To obtain a copy of the client SDK you should point your browser to the client configurator which is located on https://{weavyurl}/client in your weavy installation.

You will be presented with a form where you can configure the client SDK. As you can see the url to the client SDK can be modified to get different configurations of the SDK.

Some examples:

  • weavy.js - Standard configuration of the client SDK
  • weavy.min.js - Minified standard configuration
  • weavy.jquery.js - Client SDK including jQuery
  • weavy.jquery.min.js - Minified client SDK including jQuery

Once you are happy with the configuration, you can reference the configured url directly or download and include the file in your app if necessary.

Plain HTML example

To include the client SDK in a javascript app or your own build environment, you have to load the SDK globally (if you use the standard configuration, jQuery is also required and must be loaded prior to weavy.js). When you have loaded the SDK, you can create a new Weavy() instance anywhere at any point in your app. To avoid timing issues when loading it may be a good idea to make sure you instantiate Weavy at the window DOMContentLoaded event.

<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>


<script src="https://{weavyurl}/javascript/weavy.js"></script>


<script>var weavy = new Weavy();</script>


 

If you need to load weavy.js from another javascript, you can for instance use jQuery.getScript() to load it.

Generate a JWT token

To authenticate the weavy instance, you'll need to pass a generated JWT token. You may already have a JWT generator in your system, which you may use to provide tokens.

If you don't have any JWT generator you can use the jwt.io online generator to generate a temporary token that you can use just to get the weavy client up and running for the first time.

The iss property of the JWT needs to match your configured Client ID on the server and it needs to be signed with the corresponding shared secret.

{


"sub": "123",


"name": "John Doe",


"exp": 1917239022,


"iss": "a899528f-05a7-450d-93d4-4981ad986e55"


}


 

Add Weavy to your page

Let's try to add a Posts app to your page. Add the script below to you page and make sure you have an element with the id weavy-container.

You will need to provide your JWT for authentication. Just add your generated token to the weavy client instance options.

<div id="weavy-container" style="height:500px"></div>


...


<script>


var jwt = "{your generated jwt token}";


var weavy = new Weavy({ jwt: jwt });


var space = weavy.space({ key: "demo" });


space.app({


key: "posts-demo",


type: "posts",


container: "#weavy-container"


});


</script>