Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates: docs for manifest and instance manifest. #212

Merged
merged 2 commits into from
Aug 23, 2024
Merged

Updates: docs for manifest and instance manifest. #212

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dca2457
Updates: docs for manifest and instance manifest.
korvyashka Aug 20, 2024
31c5c87
Adds: reserved settings section
korvyashka Aug 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 119 additions & 17 deletions docs/EdgeApps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,39 @@ If you're familiar with Heroku, Cloudflare Workers, or any similar technology, y

Here's a content section for the document:

---

## Contents

1. [Getting Started](#getting-started)
- [Create an Edge App](#create-an-edge-app)
- [Playground Edge Apps](#playground-edge-apps)
- [Deploy the Edge App](#deploy-the-edge-app)
- [Instances](#instances)
- [Instance Manifest](#instance-manifest)
- [Instance Manifest Reference](#instance-manifest-reference)
2. [Manifest File](#manifest-file)
- [Defining a Setting](#defining-a-setting)
- [Setting a Setting](#setting-a-setting)
- [Modify the Greeting](#modify-the-greeting)
- [Getting Settings](#getting-settings)
- [Using Settings in Your Edge App](#using-settings-in-your-edge-app)
- [Global Settings](#global-settings)
- [Secret Settings](#secret-settings)
- [Reference](#reference)
- [Syntax](#syntax)
- [ID](#id)
- [Entrypoint](#entrypoint)
- [Description](#description)
- [Icon](#icon)
- [Author](#author)
- [Homepage URL](#homepage-url)
- [Auth](#auth)
- [Ready Signal](#ready-signal)
- [Settings](#settings)
- [Settings](#settings)
- [Defining a Setting](#defining-a-setting)
- [Setting a Setting](#setting-a-setting)
- [Modify the Greeting](#modify-the-greeting)
- [Getting Settings](#getting-settings)
- [Using Settings in Your Edge App](#using-settings-in-your-edge-app)
- [Global Settings](#global-settings)
- [Secret Settings](#secret-settings)
- [Reserved Setting Names](#reserved-setting-names)
3. [Global Branding Settings](#global-branding-settings)
- [Branding Settings List](#branding-settings-list)
- [screenly_color_accent](#screenly_color_accent)
- [screenly_color_light](#screenly_color_light)
- [screenly_logo_light](#screenly_logo_light)
- [Notes on Branding Settings](#notes-on-branding-settings)
4. [Security Model](#security-model)
- [Transmission and Storage Security](#transmission-and-storage-security)
Expand Down Expand Up @@ -151,6 +165,30 @@ After creating an instance, navigate to your Screenly web console. You should se

---

#### Instance Manifest

The `instance.yml` file is used to manage the instance of an Edge App. Currently, the CLI supports managing only one instance at a time.

#### Instance Manifest Reference

##### Syntax

The `syntax` field specifies the version of the instance manifest file. The current version is `instance_v1`.

##### ID

The `id` field is a unique identifier for the instance. This ID is generated by the system and is used to identify the instance across the platform.

##### Name

The `name` field specifies the name of the instance. It can be updated by modifying the value in the `instance.yml` file and executing the `screenly edge-app instance update` command.

##### Entrypoint URI

The `entrypoint_uri` field specifies the entry point for the Edge App. This field is only required when the Edge App entry point is a remote URL. It can be updated by modifying the value in the `instance.yml` file and executing the `screenly edge-app instance update` command.

---

## Manifest File

The manifest file defines various properties of an Edge App and is loosely inspired by the [Chrome extension manifest file](https://developer.chrome.com/docs/extensions/mv3/manifest/), but uses YAML (specifically [StrictYAML](https://hitchdev.com/strictyaml/)).
Expand Down Expand Up @@ -189,11 +227,71 @@ Edge Apps can have settings, which are key-value pairs that users installing the

Each setting may have a default value, an optional flag indicating if it's required, a human-readable title, and help text to assist users in configuring the app.

---
### Reference

#### Syntax

The `syntax` field specifies the version of the manifest file. The current version is `manifest_v1`.

#### ID

The `id` field is a unique identifier for the Edge App. This ID is generated by the system and is used to identify the Edge App across the platform.

#### Entrypoint

The `entrypoint` field specifies the entry point for the Edge App. It is optional and defaults to the file type. The `entrypoint` field contains the following subfields:
- **type:** Defines the type of entry point. Possible values are:
- `file`: The entry point is the `index.html` file in the Edge App directory.
- `remote_global`: The entry point is a URL that is consistent across all instances of the Edge App.
- `remote_local`: The entry point is a URL unique to each instance of the Edge App.
- **uri:** The URL of the entry point. This field is required if the type is `remote_global`.

#### Description

The `description` field provides a brief overview of the Edge App, which will be visible in the Screenly web dashboard.

#### Icon

The `icon` field is a URL pointing to an image that represents the Edge App. This image will be displayed in the Screenly web dashboard.

#### Author

The `author` field specifies the name of the Edge App's creator.

#### Homepage URL

The `homepage_url` field is a URL directing to the homepage of the Edge App.

#### Auth

The `auth` field is optional and is used to configure Edge App authentication. It includes the following subfields:
- **auth_type:** Specifies the type of authentication. Possible values are:
- `basic`: Basic authentication.
- `bearer`: Bearer token authentication.
- **global:** A boolean value that determines whether the authentication is global (`true`) or local (`false`).

For Basic authentication, the following settings are generated:
- `screenly_basic_auth_username`
- `screenly_basic_auth_password`

For Bearer authentication, the following setting is generated:
- `screenly_bearer_token`

These settings must be configured using the `screenly edge-app setting set` command.

#### Ready Signal

The `ready_signal` field is an optional boolean. When set to `true`, the Edge App must send a signal to the Screenly Player indicating it is ready to be displayed.

#### Settings

The `settings` field is a dictionary of key-value pairs that define the configurable settings for the Edge App. For more details, refer to the [Settings](#settings) section.
---

## Settings
### Settings

### Defining a Setting
#### Defining a Setting

To define a setting, you can use the following structure in your manifest file:

Expand Down Expand Up @@ -228,7 +326,7 @@ It might take a few minutes for your screen to pick up the change, but once it d



### Getting Settings
#### Getting Settings

To list the current settings, use the following command:

Expand All @@ -246,7 +344,7 @@ This will output:
+----------+-------------+---------------+----------+--------+-----------------------------------------------------------+
```

### Using Settings in Your Edge App
#### Using Settings in Your Edge App

To use the settings in your Edge App, include them in your HTML or JavaScript files as follows:

Expand All @@ -266,7 +364,7 @@ Settings are key-value pairs that users installing the app must provide at insta

---

### Global Settings
#### Global Settings

Global settings are secrets defined for the instances of an Edge App. These settings are shared across all instances of the app and are specified in the manifest file.

Expand All @@ -282,7 +380,7 @@ settings:
global: true
```

### Secret settings
#### Secret settings

Secret settings are similar to regular settings but are used for sensitive data that should not be exposed to the user. These settings are stored securely and are not visible to the user.
Secrets settings must not have a default_value.
Expand All @@ -297,6 +395,10 @@ settings:
help_text: An example of an API key
```

#### Reserved setting names

Settings starting with `screenly_` are reserved and cannot be used in the manifest file.

---
## Global Branding Settings

Expand Down
Loading