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, a Weavy 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.

App identifiers

When creating apps you must specify the uid property (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 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.

Creating apps

Some Weavy components can create their backing app automatically on first load. This is convenient for simple scenarios and for quickly getting started, but has some important limitations:

  • When an app is auto-created, the component sends the name and directory attributes and defaults access=write making the app open.
  • Once the app is created, property values are effectively "locked" and cannot be changed from client-side code. So changing the directory (or any other setting except name) returns a 403 Forbidden response instead of loading the component.

For ultimate control, we always recommend using the Apps API to create apps ahead of time. This can avoid certain situations where components fail to load because of a permission issue or an inadvertently changed property on the client side.

User

In order to integrate Weavy, your application must have a way to identify the currently 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.

Directories

User directories is an advanced concept for multi-tenant scenarios where multiple applications and/or organizations share the same Weavy environment while ensuring that users in different directories cannot see or interact with each other..

  • A user can be a member of zero, one, or more directories.
  • Users within the same directory can always interact with each other.
  • Users in different directories cannot see or interact with each other.
  • By adding users from different directories as members of the same app, they can interact with each other regardless of which directory they belong to. This enables communication across directories, which is not possible when using multiple environments.

To specify that a user belongs to a directory, use the Directories API or specify the directories property when creating or updating a user with the Users API.