NAV

Edge Apps

Getting Started

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 cd ~/tmp/edge-app.

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 Groundbreaking Clock App" --in-place

Please note the --in-place parameter. This is necessary if you are creating an app with existing screenly.yml and 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

With the 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 available 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 index.html file.

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:

Other than that, you can develop your Edge App just like you would do with a regular static HTML site. You can break out JavaScript, CSS, images etc into separate files and just include them as you normally would.

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:

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        |             | ✅        |
+----------+-------------+-----------+

Using 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)

Promote 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)

Settings

Secrets

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.

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.

Debugging

Coming soon.

Gotchas

Runtime Environment

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.

Metadata

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:

Cross-Origin Resource Sharing (CORS)

Cross-origin resource sharing is a mechanism that allows restricted resources on a web page to be accessed from another domain outside the domain from which the first resource was served. Some APIs (particularly public ones) use CORS to restrict access. Sometimes you need to bypass CORS. To do this, we provide you with a handy CORS proxy mitigation strategy. The way it works is very straight forward. Instead of accessing the API directly from JavaScript, you instead access it via the CORS proxy. The CORS proxy will simply remove the CORS policy so that you can circumvent the restriction.

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 cors_proxy_url.

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

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).

Manifest File

The manifest file defines various properties of an Edge App and is loosely inspired by Chrome extension manifest file, but uses YAML (StrictYAML to be precise).

When you create a new Edge App using the CLI (screenly edge-app create --name <APP NAME>), a manifest file named screenly.yaml is automatically created in the current directory.

Manifest Reference

app_id: 01H7DD8SV32F9FKWXXXXXXXXXX
entrypoint: index.html
description: 'Displays the current weather and time'
icon: 'https://example.com/some-logo.svg'
author: 'Screenly, Inc'
homepage_url: 'https://www.screenly.io'
settings:
   google_maps_api_key:
    type: secret
    title: API Key
    optional: false
    help_text: Specify a commercial Google Maps API key. Required due to the app's map feature.
  greeting:
    type: string
    default_value: "Cowboy Neil"
    title: greeting
    optional: true
    help_text: An example of a string setting that is used in index.html

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 two 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.