Create a custom web interface
Create and deploy custom web interfaces for your machines as single-page applications without managing hosting and authentication.
Once deployed, apps are accessible from a dedicated URL (appname_publicnamespace.viamapplications.com) and hosting and authentication is handled for you.
When opening an app, users log in and then select a machine they have access to. Then your app is rendered and ready for use.
Requirements
Create a single page app
Build your application using your preferred framework like React, Vue, Angular, or others. While you’re developing use any machine’s credentials. For deploying your app you must add code to read the machine API key from your browsers local storage:
import Cookies from "js-cookie";
let apiKeyId = "";
let apiKeySecret = "";
let hostname = "";
let machineId = "";
machineId = window.location.pathname.split("/")[2];
({
id: apiKeyId,
key: apiKeySecret,
hostname: hostname,
} = JSON.parse(Cookies.get(machineId)!));
Create a
{
"module_id": "your-namespace:your-module",
"visibility": "public",
"url": "https://github.com/your-org/your-repo",
"description": "Your module description",
"applications": [
{
"name": "your-app-name",
"type": "single_machine",
"entrypoint": "dist/index.html"
}
]
}
{
"module_id": "acme:dashboard",
"visibility": "public",
"url": "https://github.com/acme/dashboard",
"description": "An example dashboard for a fictitious company called Acme.",
"applications": [
{
"name": "dashboard",
"type": "single_machine",
"entrypoint": "dist/index.html"
}
]
}
The applications field is an array of application objects with the following properties:
Register your module with Viam:
viam module create --name="app-name" --public-namespace="namespace"
viam module create --name="air-quality" --public-namespace="naomi"
Package your static files and your
tar -czvf module.tar.gz <static-website-files> meta.json
viam module upload module.tar.gz --platform=any --version=0.0.1
For subsequent updates run these commands again with an updated version number.
Accessing your Single Page App
After uploading your module with the application configuration, your application will be available at:
https://your-app-name_your-public-namespace.viamapplications.com
Users will be prompted to authenticate with their Viam credentials before accessing your application:
- User navigates to
your-app-name_your-public-namespace.viamapplications.com - User authenticates with Viam credentials
- User selects an organization, location, and machine
- User is redirected to
your-app-name_your-public-namespace.viamapplications.com/machine/{machine-id} - Your application is rendered with access to the selected machine
Example
For an example see Monitor Air Quality with a Fleet of Sensors.
Limitations
- Single page apps currently only support single-machine applications
- All modules with apps must have public visibility
- There is no separate deploy step; the page will always render the latest version
- Browsers with cookies disabled are not supported
Security Considerations
- Customer apps are stored in GCS buckets that are publicly available on the internet
- Avoid uploading sensitive information in your application code or assets
- API keys and secrets are stored in the browser’s localStorage or sessionStorage
- Single page apps authenticate users with FusionAuth
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!