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.