The new article version on the Developer portal
There is an up-to-date version of this article on the Developer portal. Please see it here.
You will be redirected in 10 seconds to the new portal.
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
During this process, you will build your current application as an Applet. Applet is a universal wrapper for your existing HTML5/JS application that you can seamlessly deploy to supported devices.
Prerequisites
- signageOS Account
- created Organization in Box (create one here)
- Node.js >= 10.15.0
- NPM
- a shell environment (like bash, zsh, powershell...)
- a source-code editor (like VSCode, Sublime, WebStorm...)
We will be using VSCode
and 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.
sos login
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 .gitignore
or .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.
node_modules/
my_secret_file.md
Add signageOS Emulator and JS SDK
To use the features we offer you need to add signageOS dependencies to the project.
-
@signageos/front-display
will install a built-in Emulator for testing signageOS JS API and emulating device runtime. It's mandatory to continue this tutorial. -
@signageos/front-applet
is 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 dist
).
To start testing your application within the Emulator run command sos applet start
with parameters:
# run your compiled app in signageOS Emulator
sos applet start --applet-dir dist --entry-file-path dist/index.html
Parameter | Description |
---|---|
--applet-dir |
root directory of your compiled application, usually dist
|
--entry-file-path |
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 steps
NEXT: Deploy your Applet
DEV: Send Applet to the device directly from CLI
Additional resources
SignageOS CLI Documentation On Our Github
Check the whole CLI repository and all commands on our GithubReact JS Quick Start Guide
Visit our React JS repository for further details.Angular Quick Start Guide
Visit our Angular repository for further details.Vue JS Quick Start Guide
Visit our Vue JS repository for further details.Are you getting any error? Check our FAQ section below.
FAQ
What is the difference between npm start and sos applet start?
The npm start
will run our prepared compilation pipeline and emulator with hot reloaded enabled. This works only for projects generated by our CLI Tool.
The 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.
Troubleshooting
Error while uploading applet to signageOS via sos applet upload
?
The error might be caused by some of these situations:
Missing .sosignore
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 /dist
folder.
Make sure you definitely ignore the .git
folder!
Empty files
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.: .gitignore
, .nojekyll
, etc.
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:
Option A)
import sos from '@signageos/front-applet';
Option B)
const sos = require('@signageos/front-applet');
Option C)
<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.