Skip to content

Plugins

Using plugins, you can extend the functionality of your space. Plugins allow you to register new UI buttons, add panels, and create overlays.

Plugins are JavaScript files which are downloaded and run within their own sandbox. This means they have no access to the DOM or any of the normal web APIs.

Getting Started

All plugins inside of Vatom Spaces extend an abstract class called BasePlugin and all components extend an abstract class called BaseComponent.

Creating, uploading and updating plugins can be done by using the Vatom CLI.

Vatom CLI

The Vatom CLI allows you to generate a number of custom tools to be used within the Vatom ecosystem. These include: behaviors, designs, plugins, and views.

The following documentation will cover how you can use the Vatom CLI to create a custom plugin, which you can publish to the Vatom Marketplace for sale. You are able to set your own price and earn money on every install. Vatom Plugins are enhancements to an already feature-rich offering by Vatom Spaces. To learn more, visit Vatom Spaces.

Prerequisites

Ensure you have NodeJS version 12.18.0 or higher installed.

To check which version you have installed, simply type node -v into your terminal. You should see v12.18.0 or higher.

Ensure that you have the "Developer" role set on your user account. To do that, you can follow the below steps:

1. Sign up

To begin development, you must first create a Vatom Account by registering at studio.vatom.com

2. Find your Business ID

Your business ID is used to create your plugin, so you should copy the ID down for ease of use in the future.

To find your business ID, go to your profile settings inside Vatom Studio and look at the URL. Your business ID will be in the same place that YOUR-BUSINESS-ID is in the below URL.

https://studio.vatom.com/YOUR-BUSINESS-ID/settings

3. Add a Developer role

Without the developer role, you will be unable to sideload your plugin for testing. The button to sideload will not be visible unless you have the developer role on your profile.

Developer role

Go to Vatom Studio. Click on your profile pic > Settings > Users

Then click on '+ Add Role' and choose 'Developer'

4. Banking details

Configure your banking info by signing up on Stripe. This is also serving as your KYC. This is required to receive payments for your plugin.

Banking Info

Go to Vatom Studio. Click on your profile pic > Settings > Banking Info

Then click on 'Configure Banking Info'

5. Business profile

Convert individual account to business profile if you would like to add a business photo, add more than 1 user to your business profile and manage your business account. This step is not required if you don't wish to customize your page in the Vatom Market

Business profile

Go to Vatom Studio. Click on your profile pic > Settings > Profile

Then click on 'Upgrade to Business Account'

Installing the Vatom CLI

You can use npm or npx to install the Vatom CLI

npm i -g @vatom/cli
npx -p @vatom/cli vatom

To check which version of the Vatom CLI you have, you can execute the following:

vatom --version
npx -p @vatom/cli vatom --version

Make sure you have version 2.2.4 or above.

Authentication

Once everything is installed, you need to authorize your Vatom Account. To do that, you need to execute the following:

vatom auth
npx -p @vatom/cli vatom auth

This will open a tab in your browser that will let you sign in. If the sign-in process is successful, you will see the success message as seen below.

✔ You have successfully authenticated the Vatom CLI to your Vatom Studio account.

Create A Plugin

You can use the Vatom CLI to generate some boilerplate code to help you start.

vatom plugin new
npx -p @vatom/cli vatom plugin new

You will be prompted to answer a few questions about your plugin.

The steps below show an example of the process of creating an "Emoji" plugin, which will be created in the directory ~/emoji-plugin.

In the below steps, remember that emoji-plugin is interchangeable with whatever you chose to name your plugin.

Great! We'll get you ready to make a new plugin in no time. Just a few questions:

~/
? Plugin id (e.g. myplugin). May not contain spaces: emojiplugin
? Version number (e.g. 1.0.0): 1.0.0
? Plugin name: Emoji Plugin
? Short description (max: 255 chars): Allows users to express themselves with emoji's that float up and out of their avatar 🙌
? Long description: Allows users to express themselves with emoji's that float up and out of their avatar 🙌
? Configuration Instructions: Install the "Emoji" plugin and begin using it by selecting it from the bottom menu bar. You can then select the emoji you wish for your avatar to show.
? Category:
  Kids
  Education
  Accessibility
❯ Fun
  Social & Communication
  Art
  Developer Tools
  ...
? Business ID: YOUR-BUSINESS-ID
? Price (0): 1.99
? Release Notes (Add what you have updated, changed or fixed): Current functionality of initial release

Once you've answered all of the prompts, your plugin will be generated and you should see a successful message resembling the message below.

Creating plugin directory named "Emoji Plugin"...
...
...
...
  ✔ Creating plugin..

You're all setup! The new plugin has been output to "~/emoji-plugin"

Plugin File

To find your main plugin file, you need to first be in the same folder where your plugin was created. Once you are in that folder, the src/index.js file is the entry point to the plugin, so you can change that file to make changes to your plugin.

Adding Assets

NB

Assets are mandatory. You have to include an icon and images for the gallery.

The /icon directory is reserved for one icon, of size 150px x 150px, which is what will show alongside your plugin in the Vatom Marketplace once you publish.

The /gallery directory is used to help your users understand what your plugin does. We recommend that you add 3 - 5 screenshots or gifs of your plugin in action!

Publish A Plugin

Once you are finished developing your plugin, it's time to publish your first version! Let's bundle up your plugin and generate a /dist directory which will be uploaded to the Vatom Marketplace.

To do this, we can use npm or yarn

npm run build
yarn build

When you are ready to publish the plugin, you can execute the following to re-authenticate and then publish your plugin.

vatom auth
vatom plugin publish
npx -p @vatom/cli vatom auth
npx -p @vatom/cli vatom plugin publish
Permissions

Reminder, you must have the "Developer" role on your user profile in order to publish a plugin. You can refer to the Prerequisites section for more info.

Once your plugin has been published successfully, the vatom.lock file will be updated with an entrypoint.

"entrypoint": "https://plugins.vatom.com/YOUR-BUSINESS-ID/YOUR-PLUGIN-ID/plugin.js"

Versioning

When you make updates to your plugin, you should publish a new version. To do this, you can execute the following:

vatom plugin version
npx -p @vatom/cli vatom plugin version

You should then follow the steps to update your plugin to a new version.

~/emoji-plugin
? Semantic Version: (Use arrow keys)
  major
❯ minor
  patch
? Price (0): 2.01
? Release Notes: feat: added new emoji animation

After you answered the prompts, your vatom.lock file will be updated with the new semantic version, price, and release notes.

  ✔ Versioning plugin..

You're all setup! The new plugin has been output to "~/emoji-plugin"

Before you publish, remember to re-build your project, re-authenticate, and publish your new version!

npm run build
yarn build
vatom auth
vatom plugin publish
npx -p @vatom/cli vatom auth
npx -p @vatom/cli vatom plugin publish

Plugin Lifecycle

A plugin will generally go through a couple lifecycle events, which you can use to provide functionality. These are from the BasePlugin class and include:

  • onLoad() - First event called when the plugin loads. This is normally where you would register your UI menus and components.
  • onSettingsUpdated(field, value) - Called when a user has changed a setting in your plugin.
  • onUnload() - Called when your plugin is about to be removed.

Next Steps

For more information, you can check the Components guide, take a look at some examples, or go directly to the API documentation.

Back to top