Important Weavy concepts

This article discusses some important Weavy concepts. Understanding them will help you make the most of Weavy when adding it to your application.

Environment

One of the most important concepts to grasp is the environment. To put it simply, an environment is the backend/server part of Weavy that keeps track of all interactions and data created when users collaborate using Weavy functionality.

Component

A Weavy component is an interactive building block you add to your UI to enable Weavy functionality in your application. The component communicates with your Weavy environment using standard HTTP requests.

App

Many Weavy components are backed by a corresponding app in the Weavy environment. The app is required for permission and access control, and for keeping track of data generated when users interact with a Weavy component.

Apps are normally created automatically by components when needed, but for better access control and individually assigning permissions you can also use the Apps API to create apps ahead of time or to modify already created apps.

App identifiers

When referencing an app you need to specify a uid which is a string that uniquely identifies the app. One thing to consider when generating app identifiers is that it is often useful being able to do a reverse lookup from a uid to a location in your app. It is therefore a good idea to base the uid on something that identifies the location in your app where the Weavy component is being rendered. Typically you would use something like a product id, page id, path or URL.

Note that the uid cannot contain whitespace and must contain at least one non-digit.

Access control

Controlling access to apps can be done on two levels. First you can set the access property whan creating the app. This property defines the permissions for users who are not members of the app. Additionally, the directory property let's you reference a user directory and is used in combination with access to specify that only users in a specific directory can access the app.

If you want an open app where all authenticated users are allowed to create content: set access=write. This is the default when apps are created automatically by components.
If you want a read-only app where users can see content but cannot create anything: set access=read.
If you want a closed app that only members can access: set access=none.

By adding members to an app you can override the default access property on the app for individual users. Adding members to an app is done with the upsert member endpoint in the Apps API.

If you want to give a member permission to create content in the app: set access=write. This is the default when members are added to an app.
If you want to give a member permission to read content in the app: set access=read.
If you want to block a member from accessing the app: set access=none.

If you have a large number of users that should have to access an app it is often convenient to set access on the app to read or write. If needed you can also define a few members with different access, for instance none to block them from accessing the app.

For maximum control over who can access an app, set access=none on the app and define members with individual access levels. You could for instance give write access to a few members, and read access to others.

User

In order to integrate Weavy, your application must have some sort user system in place, and there must be a way to identify the currenty logged in user. Weavy then provides a mechanism for seamless authentication and for syncing profile information from your application to the Weavy environment.

Syncing users

Users in your application are automatically added to the Weavy environment as part of the authentication processs, but syncing them in advance or on a schedule can improve the experience for features like @mentions and direct messages.

To keep the user details (name, email, profile picture etc) up to date in Weavy, you can use the Users API. We recommend updating Weavy's user records whenever a user is updated in your application, such as during sign-up or when a user updates their profile.

User identifiers

As part of the authentication process and when syncing users to Weavy you need to supply a uid property. The uid is a string that uniquely identifies your user (typically your internal user id).

Note that the uid cannot contain whitespace and must contain at least one non-digit, for instance, if a user has the integer id 256 in your system you can create a uid by adding a one letter prefix, e.g. u256.