Do you already have a working app and now you would like to deploy it worldwide to signage devices? By using signageOS Tools you can do exactly that. Let us show you how it's done.
To get your existing application up and running you'll need only these few following steps:
- Install signageOS CLI Tools
- Install signageOS SDK and Emulator
- Upload your application build to signageOS
- signageOS Account
- created Organization in Box (create one here)
- Node.js >= 10.15.0
- a shell environment (like bash, zsh, powershell...)
- a source-code editor (like VSCode, Sublime, WebStorm...)
We will be using
zsh in this tutorial.
Getting the setup
In the following picture, you can see a demo application that I'll be using throughout this tutorial as an example. It's a simple web application compiled by Webpack. But you can use tools and compilators you like.
Now let's get started with a detailed description of each step where I'll show you how easy it is to start using signageOS SDK within your existing application.
Install signageOS CLI Tools
Even if you already have signageOS CLI Tools installed on your system, please, check if the CLI Tools are up to date. For the following steps, you'll need version
1.2.0 or newer.
By using the following command you will get the newest version of the CLI Tools on to your system.
npm install @signageos/cli@latest -g
Thanks to the signageOS CLI Tools you don't have to change anything in your current application. But before you upload and build your application, there is a few things to have in mind.
- Login into the CLI Tools.
- Set the default organization for the CLI Tools.
- Ignore everything you don't want us to see or your app doesn't need to run.
- Add signageOS to your application
- Test the application with our CLI Emulator, so you can build and deploy without worries.
- Upload runnable code
Login into the CLI Tools
Before you start with uploading your tested application you need to login using you Box account in to the CLI Tools.
Set default organization for the CLI Tools
Default organization is used later in the process as a target under which you upload your Applet to signageOS.
sos organization set-default
Ignore unneeded files
If you are already using
.npmignore you are already set. But in case you want to ignore more or different files you can use
.sosignore. It works exactly the same as the previously mentioned ignore files.
Add signageOS Emulator and JS SDK
To use the features we offer you need to add signageOS dependencies to the project.
@signageos/front-displaywill install a built-in Emulator for testing signageOS JS API and emulating device runtime. It's mandatory to continue this tutorial.
@signageos/front-appletis a library that includes signageOS JS SDK and APIs
# Emulator of real device in Chrome npm i -SE @signageos/front-display # signageOS JS SDK and APIs npm i -SE @signageos/front-applet
Test the application
signageOS CLI enables you to test your application in the built-in Emulator (front-display library). Make sure you compiled your application (usually via
npm run build or similar command) and your compiled application is in the target folder (usually
To start testing your application within the Emulator run command
sos applet startwith parameters:
# run your compiled app in signageOS Emulator sos applet start --applet-dir dist --entry-file-path dist/index.html
||root directory of your compiled application, usually
||path to file that starts your compiled application, usually `dist/index.html`|
A more advanced option is to run start the Emulator with your application from within any location by using the following command:
sos applet start \ --project-dir /Users/name/my-awesome-application \ --applet-dir /Users/name/my-awesome-application/dist \ --entry-file-path /Users/name/my-awesome-application/dist/index.html \ /
Upload the application to signageOS
Your application is tested in Emulator and working, you are logged in with your signageOS account in the CLI and the default organization is set. Let's upload.
After this step, your Applet is uploaded to signageOS and you can see it in the Box. From this point on, you can start deploying the Applet to supported devices.
cd my-awesome-application sos applet upload --entry-file-path dist/index.html
Now you are ready to deploy your new Applet to supported devices. Continue by selecting any of the deployment options below.
NEXT: Deploy your Applet
DEV: Send Applet to the device directly from CLI
SignageOS CLI Documentation On Our GithubCheck the whole CLI repository and all commands on our Github
React JS Quick Start GuideVisit our React JS repository for further details.
Angular Quick Start GuideVisit our Angular repository for further details.
Vue JS Quick Start GuideVisit our Vue JS repository for further details.
Are you getting any error? Check our FAQ section below.
What is the difference between npm start and sos applet start?
npm start will run our prepared compilation pipeline and emulator with hot reloaded enabled. This works only for projects generated by our CLI Tool.
sos applet start will only run the emulator without hot reload and compilation. It just runs your application. It works with projects generated by our CLI Tools. But it's main purpose is to run already existing application that use different technologies and project structure.
Error while uploading applet to signageOS via
sos applet upload?
The error might be caused by some of these situations:
If you do not have the
.sosignore file in your project, the
.gitignore is used instead. A solution to that is to add
.sosignore and put there all files and folders that are not supposted to be in the final built application. Usually the only thing you do not ignore is the
Make sure you definitely ignore the
Right now, there is a bug that prevents you to use
sos applet upload if your files or files in folders are completely empty. Please, check your project (usually the
/dist) folder for any empty files e.g.:
sos is undefined and cannot use the JS API
In case you do not have
sos object available, you need to manually add it to your project by one of the following options:
import sos from '@signageos/front-applet';
const sos = require('@signageos/front-applet');
<script src="..path/to/the/front-applet.js" />
You can manually download the library here: https://2.signageos.io/lib/front-applet/4.0.0/bundle.js. You can also download any other version by changing the
4.0.0. to other version that is available.