@vatom/web-sdk

Allows web apps to display and interact with vatoms.

Usage no npm install needed!

<script type="module">
  import vatomWebSdk from 'https://cdn.skypack.dev/@vatom/web-sdk';
</script>

README

Vatom Inc SDK for JavaScript (Beta)

This is the official Vatom Inc Web SDK. It allows you to easily integrate your own web apps into the Vatom Inc Platform.

Prerequisite: Request an App ID

If you have not already done so, you can sign up for free on studio.vatom.com and get an App ID. You will need this App ID to run the endpoints explored in the examples below.

Installation

You can import the SDK with or without Face Module support, which provides utilities for rendering vatoms in the browser.

Install from npm

npm install @vatom/sdk

In Node.js

const VatomInc = require('@vatom/sdk')

In the browser via ES6 imports

// Core SDK only
import VatomInc from '@vatom/sdk'

// Core SDK plus Face Module support
import VatomInc, { VatomView } from '@vatom/sdk/face'

In the browser from a script tag

<!-- Core SDK only -->
<script src="https://npmcdn.com/@vatom/sdk/dist/vatom-sdk.min.js"></script>

<!-- Core SDK plus Face Module support -->
<script src="https://npmcdn.com/@vatom/sdk/dist/vatom-faces.min.js"></script>

Getting Started

Before running any of the web APIs you need to initialise the Vatom Inc application. Place the following code in your opening script tag.

let vatomNet = new VatomInc({
  "appID" : {{APPID}},
  "server" : "https://api.vatom.io/",
  "websocketAddress" : "wss://ws.vatom.io",
  "prefix" : "vatom"
});

The SDK supports multiple instances of VatomInc to be initialised.

IMPORTANT NOTE:

The prefix attribute is critical if you are using multiple instances with the same appID.

Leaving the prefix out will force the sdk to use the appID as the prefix for any stored data, Using multiple instance with the same appID and the prefix omitted will result in data override.

UserManager

Registering a User

register(payload)

Registration can be done in two ways:

  • inline register('first name','last name', 'birthday', 'language', 'password', 'tokens', 'name public', 'avatar public')
  • or as an object

Examples

let payload = {
    firstName : 'John',
    lastName : 'Smith',
    birthday : '1970-12-23',
    language : 'en',
    password : '',
    tokens : [
      {
        token : '+44 123 9876',
        token_type : 'phone_number',
        isPrimary : true
      },
      {
        token : 'example@example.com',
        token_type : 'email',
        isPrimary : false
      }
    ],
    namePublic : true,
    avatarPublic : true
}

vatomNet.UserManager.register(payload).then(data =>{
  //do something here
}).catch(err => {
  console.error(err.message);
})

Login with User Credentials

login(payload)

  • parameter one is the email address or the mobile number of the user
  • parameter two is the type of login (email / phone_number)
  • parameter three is the password
  • If the password is not set and left blank, an OTP will be sent to the users method of login, ie. email / mobile number.
vatomNet.UserManager.login("example@example.com", "email", "test").then(data => {
  //proceed with logged in user
}).catch(err => {
  console.error(err.message);
})

loginGuest(guest_id)

  • parameter one is the guest id string
vatomNet.UserManager.loginGuest(guest_id).then(data => {
  //proceed with code
}).catch(err => {
  console.error(err.message);
})

Logout the currently logged in user

logout()

Logs out the current user

vatomNet.UserManager.logout().then(data => {
  //proceed to redirect after logout
}).catch(err => {
  console.error(err.message);
})

getAccessToken()

Returns the current Access Token

vatomNet.UserManager.getAccessToken().then(data => {
  // Access Token returned is a String

}).catch(err => {
  console.error(err.message)
})

getCurrentUser()

Returns the current user information

vatomNet.UserManager.getCurrentUser().then(data => {
  //do something with the returned user data
}).catch(err => {
  console.error(err.message);
});

encodeAssetProvider(url)

Checks the current URI that was supplied against the logged in Asset Provider URI and if it is a match, builds a encoded link with the matching params

vatomNet.UserManager.encodeAssetProvider("https://cdndev.blockv.net/blockv/avatars/b9e6581c-bb70-48d1-85eb-6657ee1a3bef.1521806344051057018").then(data => {
  //proceed to use the newly returned url
}).catch(err => {
  console.error(err.message);
});

getCurrentUserTokens()

returns a list of the current user's tokens (emails / phone numbers)

vatomNet.UserManager.getCurrentUserTokens().then(data => {
  //do something here
}).catch(err => {
  console.error(err.message);
});

uploadAvatar(formData)

Example Avatar Upload


function doUpload(){
  let f = document.getElementById('avatar');
  let file = f.files[0];
  let fData = new FormData();
  fData.append('avatar', file);
  vatomNet.UserManager.uploadAvatar(fData);
}

updateUser(payload)

updates the current user with an object containing the new details of the user

Example updating a user

let payload = {
    'first_name' : 'Jane',
    'last_name' : 'Smith',
    tokens : [
      {
        token : 'jane@example.com',
        token_type : 'email'
      }
    ]
}

vatomNet.UserManager.updateUser(payload).then(data => {
  //do something here after update
}).catch(err => {
  console.error(err.message);
})

sendTokenVerification(token, token_type)

resends the verification token to the user

vatomNet.UserManager.sendTokenVerification(token, token_type).then(data => {
  //verify the token
}).catch(err => {
  console.error(err.message);
})

getRefreshToken()

returns the current refresh token

vatomNet.UserManager.getRefreshToken().then(data => {
  //do something with the refresh token
}).catch(err => {
  console.error(err.message);
})

verifyUserToken(payload)

verifies the user token that was supplied

let payload = {

    "token": "jane@example.com",
    "token_type": "email",
    "verify_code": "1234"
}
vatomNet.UserManager.verifyUserToken(payload).then(data => {
    // do something after verified
}).catch(err => {
   console.error(err.message);
})

resetPassword(token, token_type){

Sends a login OTP , The OTP may only be used for the .login() API

vatomNet.UserManager.resetPassword("+44 123 4569", "phone_number").then(data => {
     //do something after password is deleted
}).catch(err => {
     console.error(err.message)
})

vAtom Actions

  • This is a generic function that takes 3 parameters.
  • vatomId is the vatom id
  • action is the type of action :: Drop, Pickup , Transfer , Require
  • payload is any additional information sent along with the vatom id
vatomNet.Vatoms.performAction(vatomId, action, payload).then(data =>{
  //do something after performing an action with a vAtom
}).catch(err => {
  console.error(err.message);
})

vAtom Inventory

Retrieves a list of the current vAtoms, actions and faces in the users inventory

vatomNet.Vatoms.getUserInventory().then(data =>{
  // do something with the returned inventory
  // data.vatoms (array of vatoms)
  // data.faces (array of faces)
  // data.actions (array of actions)
}).catch(err => {
  console.error(err.message);
})

vAtom Delete

Deletes a vAtom in the users inventory

vatomNet.Vatoms.deleteVatom(vatomID).then(data =>{
  //do something after the vAtom has been deleted
}).catch(err => {
  console.error(err.message);
})

Discover

With the discover method you can search for vAtoms on the Vatom Inc Platform. The search will cover all the vAtoms within your current user's inventory as well as those of other users on the Platform. When searching for vAtoms owned by other users, only those vAtoms with their visibility set as public will appear.

Building discover queries

You construct a discover query using a DiscoverQueryBuilder. This class helps you to easily compose queries using a few components:

  1. Scope (required)
  2. Filters (optional)
  3. Returns (optional)

Scope

A scope must always be supplied. Scopes are defined using a key and value. The key specifies the property of the vAtom to search. The value is the search term.

Filter

Filter elements, similar to scopes, are defined using a field and value. However, filters offer more flexibility because they allow a filter operator to be supplied, e.g. Gt which filters those vAtoms whose value is 'greater than' the supplied value. The combine operator is applied between filter elements.

Return

Return type controls the response payload of the query:

  • returns vAtoms.
  • count returns only the numerical count of the query and an empty vAtom array.

Performing the Query

let filter = new VatomInc.Discover(vatomNet);
filter.setScope("vAtom::vAtomType.owner", "$currentuser");
filter.appendFilter("vAtom::vAtomType.template", "vatomic::v1::vAtom::Avatar", "Match", "And");
filter.execute();

Web socket

Important to note, the Web socket connection can only be established if the current user is authenticated. Thus, connect() should only be called after the user has successfully logged in.

The Web socket class is used to provide realtime feedback for the user when they perform certain actions on the Vatom Inc platform.

Connection

A connection to the Web socket should be established before invoking any of the listeners on the socket.

vatomNet.WebSockets.connect().then(()=>{
        //Do something with the connected sockets
}).catch(err => {
        console.error(err.message);
});

To use the information returned from the Web socket, You will need to add a few event listeners to the established connection.

There are four different event listeners you can monitor:

  • stateUpdate
  • inventory
  • activity
  • all
Listener Description
inventory Updates on the current user's inventory (vAtom addition/removal)
stateUpdate Updates on the state of any of the current user's vAtoms (vAtom diff)
activity Updates on the general platform events (user actions, chat, etc.)
all All of the above together 
vatomNet.WebSockets.connect().then(()=>{
 
  //adding a listener for state Updates
  vatomNet.WebSockets.addEventListener('stateUpdate', function(data){
        //Do something with returned state updates
    })
 
  //adding a listener for inventory calls
    vatomNet.WebSockets.addEventListener('inventory', function(data){
        //Do something with returned inventory updates
    })
 
    //adding a listener for activity
    vatomNet.WebSockets.addEventListener('activity', function(data){
        //Do something with the returned activity updates
    })
 
    //adding a listener for all
    vatomNet.WebSockets.addEventListener('all', function(data){
        //Do something with the returned data
    })
    
}).catch(err => {
        console.error(err.message);
});

Closing Web Sockets

The caller can manually force a socket connection to close by using the close() function. This will prevent the Web socket from trying to auto-connect.

vatomNet.WebSockets.close();

Activity

Threads

Fetch the activity threads of the current user.

Each thread represents an activity feed between two users. The Vatom Inc platform will automatically create and update threads when sending or receiving a vAtom.

//returns a list of threads
vatomNet.Activity.threads().then(data => {
        //do something with the returned threads
}).catch(err => {
        console.error(err.message);
})

Thread Messages

Fetch the event messages for an activity thread belonging to the current user.

To get the id required to specify the activity thread see Threads function above.

//Fetches a list of messages from the specified activity thread.
let id = 'id-of-thread'
vatomNet.Activity.threadMessages(id).then(data => {
    //do something with the returned activity thread
}).catch(err => {
        console.error(err.message)
})

Send message

Send a text message to a user on the Vatom Inc platform. This will create a new activity thread or update the existing one between the two users.

//send a message to a user on the Vatom Inc platform
let id = "id-of-the-user-to-send-to"
vatomNet.Activity.sendMessage(id).then(data =>{
    //do something with the returned message here
}).catch(err => {
        console.error(err.message);
})

Face Module

Displaying a vAtom (VatomView)

In order to visually display a vAtom, you would need to create a VatomView instance and add its element to the DOM.

let vv = new VatomView(vatomNet, << vAtom >>, FaceSelection.Icon);
document.body.append(vv.element);

Registering a Face

In order to register a native face, you would need to create a class and register is at app startup.

// create your face class.  
class MyFace {
  constructor(vatomView, vatom, faceSpec) {
    // Create element
    this.element = document.createElement('div');
    this.element.style.position = 'relative';
    this.element.style.width = '100%';
    this.element.style.height = '100%';
  }

  onResize() {}

  onLoad() {}

  onUnload() {}

  onVatomUpdated() {}

  static get url() {
    return 'native://my-face';
  }
}


// register face on app startup
VatomView.registerFace(MyFace);

Production Support

The Vatom Inc SDK for JavaScript is currently in public beta. Breaking changes may still be introduced in the coming months. This is important to consider if you are planning on releasing your application using the JavaScript SDK.

Security Disclosure

If you believe you have identified a security vulnerability with Vatom Inc, you should report it as soon as possible via email to support@vatom.io. Please do not post it to a public issue tracker.

Author

Vatom Inc

License

Vatom Inc is available under the Vatom Inc license. See the LICENSE file for more info.