Add signageOS SDK into your existing application

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:

1. Install signageOS CLI Tools
2. Install signageOS SDK and Emulator
3. Upload your application build to signageOS

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.

1. Login into the CLI Tools.
2. Set the default organization for the CLI Tools.
3. Ignore everything you don't want us to see or your app doesn't need to run.
4. Add signageOS to your application
5. Test the application with our CLI Emulator, so you can build and deploy without worries.
6. 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 startwith 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

Additional resources

 

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" />