@vatom/view-sdk

A React SDK for building custom views for Vatom digital objects. This SDK provides utilities and components to create interactive, dynamic views that render Vatoms in the Vatom ecosystem.

Table of Contents

• Installation
• Quick Start
• Core Concepts
• API Reference
• Local Development
• Publishing
• Examples
• Configuration Schema
• Support

Installation

npm install @vatom/view-sdk

or

yarn add @vatom/view-sdk

Quick Start

The SDK provides a Higher-Order Component (HOC) called withVatom that injects vatom-related props into your React component, it also provides a hook useViewSDK that provides the same props.

Using HOC

import React from 'react'
import { withVatom } from '@vatom/view-sdk'

const App = ({
  vatom,
  viewConfig,
  isLoading,
  getColor,
  getFontStyles,
  sendRequest,
  performAction,
  businessId,
  trackEvent,
  userData
}) => {
  if (isLoading) {
    return <div>Loading...</div>
  }

  return (
    <div>
      <h1>{vatom.name}</h1>
      {viewConfig.backgroundImage && <img src={viewConfig.backgroundImage.ref} alt="Background" />}
    </div>
  )
}

export default withVatom(App)

Using hook

import React from 'react'
import { useViewSDK } from '@vatom/view-sdk'

const App = () => {
  const {
    vatom,
    viewConfig,
    isLoading,
    getColor,
    getFontStyles,
    sendRequest,
    performAction,
    businessId,
    trackEvent,
    userData
  } = useViewSDK()

  return (
    <div>
      <h1>{vatom.name}</h1>
      {viewConfig.backgroundImage && <img src={viewConfig.backgroundImage.ref} alt="Background" />}
    </div>
  )
}

export default App

Core Concepts

Vatoms

Vatoms (virtual atoms) are smart digital objects that can be displayed, interacted with, and transferred. Each Vatom has properties, resources, and actions that define its behavior and appearance.

Views

Views are React applications that render Vatoms. They receive data from the Vatom through props and can interact with the Vatom platform through provided utilities.

IMPORTANT!: Views can only be used inside the Vatom Wallet to display their corresponding Vatom.

View Config

View arguments are configurable parameters that customize how a Vatom is displayed. These are defined in the config-schema.json file and can be configured through Vatom Studio.

Behaviors and actions

Behaviors are restrictions and rules on what functionalities a Vatom is able to fulfill. These are defined in Studio, depending on the template we use. Each individual behavior has its own set of actions, which are the functions that alter the state, properties or ownership of a Vatom.

API Reference

Props Injected by withVatom

vatom

Type: Object

The vatom being displayed. Contains all the Vatom's properties and metadata.

{
  id: string,
  name: string,
  description: string,
  // ... additional vatom properties
}

viewConfig

Type: Object

Configuration arguments passed to the view. These are defined in your config-schema.json file.

{
  backgroundImage: {
    type: "image/png",
    ref: "https://..."
  },
  // ... your custom view arguments
}

isLoading

Type: boolean

Indicates whether the Vatom data is still being loaded.

getColor(colorName: string)

Type: Function

Retrieves a color value from the Vatom's theme.

const primaryColor = getColor('primary')

getFontStyles()

Type: Function

Returns font styling information from the Vatom's theme.

const fontStyles = getFontStyles()

sendRequest(action: string, data: any)

Type: Function

Sends messages without response or interactions to the Vatom viewer/wallet.

sendRequest('navigate', { url: 'https://example.com' })

awaitResponse(action: string, data: any)

Type: Function

Sends messages or interactions to the Vatom viewer/wallet while awaiting for a response.

const response = await awaitResponse('someMessage', { somePaylaod })

performAction(actionName: string, payload: any)

Type: Function

Executes a Vatom action (e.g., transfer, acquire, etc.).

performAction('Transfer', { recipient: '[email protected]' })

Example of commonly used actions:

Incrementing user points:

try {
  await performAction('custom', {
    behaviorId: 'user-points-v2',
    action: 'increment-user-points-v1',
    points: 10
  })
  console.log('User points incremented successfully')
} catch (err) {
  console.err('An error occurred while incrementing points:', err)
}

Redeem token:

try {
  await performAction('Redeem')
  console.log('Token redeemed successfully')
} catch (err) {
  console.err('An error occurred while redeeming token:', err)
}

Submit quiz:

try {
  await performAction('custom', {
    behaviorId: 'quiz-v2',
    actionId: 'submit-quiz-v2',
    submittedAnswer: 'Answer to Submit'
  })
  console.log('Quiz submitted successfully')
} catch (err) {
  console.err('An error occurred while submitting answer:', err)
}

businessId

Type: const

Returns the current businessId

const currentBusinessId = businessId

trackEvent(eventName: string, data?: any)

Type: Function

Tracks an event triggered on the view.

trackEvent('BeginTransfer', { recipient: '[email protected]' })

userData

Type: const

Returns the current user's data.

const currentUserData = userData

The type of the returned user data is:

typeof userData = {
  bio: string
  default_business_id?: string
  default_space_id?: string
  email: string
  email_verified: boolean
  location?: {
    country: string
    latitude: number
    locality: string
    longitude: number
    postal_code: string
    region: string
  }
  name: string
  phone_number: string
  phone_number_verified: boolean
  picture: string
  sub: string
  updated_at: number
  wallet_address: string
  website: string
  guest: boolean
  deferred_deeplink?: string
}

Local Development

When developing locally, you need to mock the Vatom properties since the SDK won't have access to the Vatom platform.

Setup for Local Development

1. Open your App.js file
2. Replace export default withVatom(App) with export default App
3. Mock the vatom properties in your component

const App = () => {
  // Mock data for local development
  const viewConfig = {
    backgroundImage: {
      type: 'image/png',
      ref: 'https://example.com/image.png'
    },
    title: 'My Vatom'
  }

  const vatom = {
    id: 'mock-id',
    name: 'Test Vatom',
    description: 'A test Vatom for local development'
  }

  return (
    <div>
      <h1>{vatom.name}</h1>
      <img src={viewConfig.backgroundImage.ref} alt="bg" />
    </div>
  )
}

export default App

Important

Remember to revert these changes before publishing:

• Restore export default withVatom(App)
• Remove any mock data

Examples

Basic Image Display

import React from 'react'
import { withVatom } from '@vatom/view-sdk'

const ImageView = ({ vatom, viewConfig }) => {
  return (
    <div style={{ textAlign: 'center' }}>
      <h2>{vatom.name}</h2>
      {viewConfig.image && (
        <img src={viewConfig.image.ref} alt={vatom.name} style={{ maxWidth: '100%' }} />
      )}
      <p>{vatom.description}</p>
    </div>
  )
}

export default withVatom(ImageView)

Interactive View with Actions

import React, { useState } from 'react'
import { withVatom } from '@vatom/view-sdk'

const InteractiveView = ({ vatom, viewConfig, performAction, sendRequest }) => {
  const [loading, setLoading] = useState(false)

  const handleTransfer = async () => {
    setLoading(true)
    try {
      await performAction('Transfer', {
        recipient: '[email protected]'
      })
      sendRequest('showMessage', {
        message: 'Transfer successful!'
      })
    } catch (error) {
      console.error('Transfer failed:', error)
    } finally {
      setLoading(false)
    }
  }

  return (
    <div>
      <h2>{vatom.name}</h2>
      <button onClick={handleTransfer} disabled={loading}>
        {loading ? 'Transferring...' : 'Transfer to Friend'}
      </button>
    </div>
  )
}

export default withVatom(InteractiveView)

Themed View

import React from 'react'
import { withVatom } from '@vatom/view-sdk'

const ThemedView = ({ vatom, viewConfig, getColor, getFontStyles }) => {
  const primaryColor = getColor('primary')
  const fontStyles = getFontStyles()

  return (
    <div
      style={{
        backgroundColor: primaryColor,
        ...fontStyles,
        padding: '20px'
      }}
    >
      <h2>{vatom.name}</h2>
      <p>{vatom.description}</p>
    </div>
  )
}

export default withVatom(ThemedView)

Interactive View With Vatom status

import React, { useState } from 'react'
import { withVatom } from '@vatom/view-sdk'

const InteractiveViewWithStatus = ({ vatom, viewConfig, performAction, sendRequest }) => {
  const [loading, setLoading] = useState(false)

  const userPoints = vatom?.status['user-points-v2']?.total
  const submittedAnswer = vatom?.status['quiz-v2']?.submittedAnswer

  return (
    <div>
      <h2>{vatom.name}</h2>
      <p>
        The user answered: {submittedAnswer} and their points' balance is: {userPoints}
      </p>
    </div>
  )
}

export default withVatom(InteractiveViewWithStatus)

View Config Schema

Create a config-schema.json file to define configurable parameters for your view. This uses JSON Schema format and will generate form fields in Vatom Studio.

Example config-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "vatom",
  "properties": {
    "backgroundImage": {
      "type": "vatom",
      "title": "Background Image",
      "description": "The background image for the view",
      "properties": {
        "type": {
          "type": "string",
          "default": "image/png"
        },
        "ref": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "title": {
      "type": "string",
      "title": "Title",
      "description": "Display title for the view"
    },
    "showDescription": {
      "type": "boolean",
      "title": "Show Description",
      "default": true
    }
  }
}

Project Structure

my-vatom-view/
├── src/
│   ├── App.js          # Main view component
│   └── index.js        # Entry point
├── public/
├── config-schema.json  # View configuration schema
├── vatom.lock         # Generated after publishing
├── package.json
└── README.md

Development Workflow

1. Create a new view using Vatom CLI:

   vatom view new

2. Develop locally with mocked data

3. Build your view:

   npm run build

4. Publish to Vatom:

   vatom view publish

5. Test in Vatom Studio using the generated entrypoint URL

Publishing

Prerequisites

Install the Vatom CLI:

npm install -g @vatom/cli

Authentication

vatom auth

Build Your View

npm run build
# or
yarn build

Publish

vatom view publish

After publishing, a vatom.lock file will be generated containing:

{
  "id": "exIOpXe0fV",
  "businessId": "sfpGNTg9PQ",
  "entrypoint": "https://views.vatom.com/sfpGNTg9PQ/exIOpXe0fV/index.html",
  "groupId": "exIOpXe0fV"
}

Requirements

• Node.js (version 14 or higher recommended)
• React 16.8+ (for hooks support)
• Vatom CLI for publishing

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Best Practices

1. Always handle loading states - Check isLoading before rendering content
2. Validate viewConfig - Don't assume all configuration values are present
3. Handle errors gracefully - Wrap performAction calls in try-catch blocks
4. Optimize images - Use appropriately sized images for better performance
5. Test on mobile - Views are often displayed in mobile wallets
6. Use semantic HTML - Ensure accessibility for all users

Troubleshooting

View not displaying

• Ensure you've reverted local development changes (restored withVatom)
• Check that your build completed successfully
• Verify the entrypoint URL in vatom.lock

Props are undefined

• Make sure you're using withVatom HOC
• Check that you're accessing props correctly in your component

Publishing fails

• Verify you're authenticated: vatom auth
• Ensure you have the correct permissions for the business
• Check that your build output is in the correct directory

Support

• Documentation: https://developer.vatom.com
• Support Email: [email protected]
• Developer Portal: Visit the Vatom Developer Portal for guides and examples

License

Check with Vatom Inc. for license information.

Contributing

For contribution guidelines, please contact Vatom support or visit the developer portal.

Note: This SDK is designed to work within the Vatom ecosystem. Views created with this SDK are hosted and rendered by Vatom's infrastructure.