First, you need to install the Screenly CLI. The CLI is used to both generate and to upload Edge Apps.
With the CLI installed, and logged in (
screenly login), we can create our Hello World example.
To do this, we first need to create a new directory where the Edge App will live. For production applications, this would likely be a source controlled folder (e.g.
git), but let's just create a temporary folder for now with
mkdir -p ~/tmp/edge-app and jump into it with
Create an Edge App
$ screenly edge-app create --name hello-world
When you run the
screenly edge-app create command, two files will be created in the current directory:
screenly.yml is where the metadata lives. In this file, you can define settings, secrets and various other meta data. In our Hello World example, we have a single setting called
greeting, which is used in the Edge App.
index.html is our entry-point so to speak. It is what the client (i.e. the player) will load. This particular file is very simple and just includes some styling and various meta data examples.
Playground Edge Apps
Getting started with our existing Playground Edge Apps would help easing your introduction to our Edge Apps development. To test your abilities with them, you need to clone our Playground GitHub Repository first. After cloning it, please get into one of the example Playground Edge App folder and execute following command:
Let's say our target is the Clock App. Enter into directory (
Playground/edge-apps/clock) and execute the following command to create an Edge App.
$ screenly edge-app create --name "My Groundbraking Clock App" --in-place
Please note the
--in-place parameter. This is necessary if you are creating an app with existing
index.html files, like our Playground Edge Apps do. Otherwise you'll be getting errors about conflicting files. Of course it's not mandatory if you are creating a brand new Edge App. It's here just to make your already overloaded developer life a little bit easier.
Upload the Edge App
$ screenly edge-app upload Edge app successfully uploaded.
Now in order to consume this Edge App, we first need to upload the Edge App using the
upload command. This will automatically create a new version (you can see your versions using
screenly edge-app version list). With the Edge App successfully uploaded, you now need to promote it to a channel (stable or candidate) in order to use it in on the player.
List Edge App versions
$ screenly edge-app version list +----------+-------------------------+-----------+----------+ | Revision | Description | Published | Channels | +----------+-------------------------+-----------+----------+ | 1 | Screenly Clock Edge App | ✅ | | +----------+-------------------------+-----------+----------+
Promote the Edge App
upload command you'd only upload the Edge App and its assets to the server. To make it available for screens you need to promote it. This way it will be avilable for further process.
$ screenly edge-app version promote --latest Edge app version successfully promoted.
Once you have promoted a release, we can now start using this. If you head over to your Screenly web console, you should see your Edge App listed. Just schedule this as you would with a regular asset.
With the asset scheduled on your screen, you should see the headline "Hello stranger!". As it turns out, this is actually a setting (configured in
screenly.yml). We can override this using the
edge-app setting command to change this.
Modify the greeting
$ screenly edge-app setting set greeting='Cowboy Neil'
It might take few minutes for your screen to pick up on the change, but once it has, the headline should change from "Hello Stranger!" to "Hello Cowboy Neil!".
Sample Edge Apps
Creating an Edge App
To create an Edge App, you need to use the CLI and invoke it using
edge-app create <name>. This will fire off a number of API calls and create a file called
screenly.yml in the current directory (you can learn more about this file here), as well as a sample
To create an Edge App, simply run:
$ screenly edge-app create --name <name>
Once you have initiated your Edge App, you can start adding content. We make a few assumptions about your Edge App:
- No files below the current can be references (just like you can't use the
Dockerfileoutside the current working directory)
- The following file names are reserved by the system:
screenly.yml- Reserved for the manifest file.
screenly.js- Reserved for on-device usage to interact with the system.
Uploading an Edge App
To upload your Edge Apps to Screenly, you use the
edge-app upload command. This will copy all files in the current directory and generate a release.
When you upload subsequent releases, you'll notice a few more things:
screenly.yamlwill be bumped to a newer version.
- The new asset will automatically be added to the system as a new version.
- If you try to upload a new revision without any local changes, the upload will fail with
Failed to upload edge app: Cannot upload a new version: No changes detected.
Upload an edge app from the current directory:
$ screenly edge-app upload
Edge Apps Versions
You can list all Edge Apps in a given account, along with their versions with the
edge-app version list command. This will also tell you what version is the current version.
List Edge Apps (and versions)
$ screenly edge-app version list +----------+-------------+-----------+ | Revision | Description | Published | +----------+-------------+-----------+ | 1 | | ✅ | +----------+-------------+-----------+
version list, you can determine what the 'Active Revision' is. This is the version that is corresponding to the asset that is showing on your screen(s).
To promote a new release, you can use the
version promote command. This will automatically deploy the version you've specified. To roll back, you can promote the previous version.
You also have the option to use
--latest to employ the most recent version of the app.
Promote a version
$ screenly edge-app version promote \ --revision=1 \ --channel=candidate Promote 1 of Edge App 'Weather App' (XXXXXXXXXXXXXXXXXXXXXXXXX)? (y/n)
Pomote to latest version
edge-app version promote --latest
Delete a version
$ screenly edge-app version delete v2 Delete v2 of Edge App 'Weather App' (XXXXXXXXXXXXXXXXXXXXXXXXX)? (y/n)
Defining a secret
settings: [...] api_key: type: secret title: API Key optional: false help_text: An example of an API key
Setting a secret
$ screenly edge-app secret set api_key='ABC123'
Screenly's secrets function similarly to settings, but with a distinct security model. They are write-only, ensuring they can't be retrieved via the API or web interface once written. To use secrets, you define them in
screenly.yml, but you do not set a value.
From a consumption perspective (i.e. to use them on the device), secrets are exposed the same way as settings. Thus you can't have a secret and a setting by the same name.
The transmission and storage protocols employ enhanced security. Every Screenly device has its unique pair of public/private keys. For the Screenly Player Max, these keys are securely held in its Trusted Platform Module (TPM), which allows the use of robust x509 cryptography. When we send payload to a Screenly Player, we encrypt it using the device's unique public key, ensuring that only the intended device can decrypt it. Furthermore, secrets on the Player Max are fully encrypted on disk using the TPM, making them inaccessible even if the hard drive is compromised.
For the standard Screenly Player, which doesn't have a TPM, we still utilize robust x509 cryptography with certificates securely stored on disk. While these devices do not offer hardware-level security for stored secrets, our encryption still ensures a high level of protection for your sensitive data.
Edge App emulator
After making the Edge App, you can use the Edge App emulator to test it in your web browser.
- To do this, open your terminal and navigate to the Edge App directory.
- Run this command:
Run Edge App emulator
$ screenly edge-app run
This will provide you with a URL to access your Edge App in your browser.
If you don't have the sample data in your Edge App directory, you can create it by running this command:
Add mock data to run Edge App emulator
$ screenly edge-app run --generate-mock-data
After generating the mock data, run the Edge App emulator again to see your app in action.
- You need to use relative paths to assets (e.g.
static/image.svgrather than absolute paths (e.g.
Security is at the core of Edge Apps and there are a number of steps we've taken to ensure they are secure.
The first is the browser sandboxing. Edge Apps are running inside the browser with appropriate security profiles.
Next, the actual Edge App runtime environment is isolated itself. This means that Edge Apps cannot communicate or read files/data from another Edge App. This goes not only for files, but also for environment data (such as settings), but also of course for secrets.
Sample Edge App Use
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Metadata</title> <script src="screenly.js?version=1"></script> </head> <body > <p>I'm <span id="screen-name"></span>.</p> </body> <script> document.getElementById("screen-name").innerText = screenly.metadata.screen_name; </script> </html>
There are numerous scenario where you want to use some sort of metadata for your Edge Apps. For instance, you might want to build a wayfinding apps that shows the location from where the screen is located to a particular destination.
Since the screen already knows a lot about itself, including where it is in the world, we've exposed this to the Edge App framework.
This data includes:
- name: The human readable name you have given the screen.
- hostname: The unique hostname (which also corresponds with the id) the screen has been given.
- coordinates: The latitude and longitude coordinates where the screen has been set to. You can edit this location in the web interface.
- Returned as a dict.
- location: The human readable location as shown in the web interface.
- hardware: The hardware for the given device.
- version: The software version of the Screenly device.
- tags: The tags/labels assigned to the screen.
- Returned as a dict.
Cross-Origin Resource Sharing (CORS)
For instance, if you're trying to access the API end-point
https://api.example.com/v1, but it has a CORS policy preventing you from accessing it. To bypass this policy, you can use the CORS that Edge Apps comes with built-in. The way it works is that it prefix your URL with the value from
In the example code, you can just use
bypass_cors_url instead of
api_url and you can interface with it as per usual.
[...] <head> <script src="screenly.js?version=1"></script> </head> <body> [...] <script> cost api_url = 'https://api.example.com/v1'; cost bypass_cors_url = screenly.cors_proxy_url + api_url; </script> [...] </body>
Monitoring is in invite-only beta.
When building Edge Apps, you sometimes need the ability to monitor performance of the device running the Edge App. This is particularly true for low-powered devices, like Raspberry Pis where you have very limited resources to work with.
To help you with this, we've decided to adopt Prometheus, as the platform to expose metrics.
With the monitoring feature enabled, the device will the Prometheus end-point on port
9100, where we expose data from Node Exporter. This allows you to scrape metrics and visualize them with a tool like Grafana (which in turn you can visualize with Screenly).
When you create a new Edge App using the CLI (
screenly edge-app create), a manifest file named
screenly.yaml is automatically created in the current directory.
app_id: 01H7DD8SV32F9FKWXXXXXXXXXX description: 'My Edge App' icon: 'https://example.com/some-logo.svg' author: 'Screenly, Inc' homepage_url: 'https://www.screenly.io' settings: greeting: type: string default_value: "Cowboy Neil" title: name optional: true help_text: An example of a setting that is used in index.html google_maps_api_key: type: secret default: "" optional: false title: API Key help_text: Specify a commercial Google Maps API key. Required due to the app's map feature.
Edge Apps are allowed to have settings which are basically key-value pairs the user installing the app must provide at install time, and can later edited. The values in these settings are exposed to the app via environment variables or secrets. There are three types of settings:
Each setting may have a default value, a flag to say if it's optional, a human readable title and a help text. See the example below.