manifest.json for Livedeck widgets: fields, permissions and error codes
Every field, permission and setting type of manifest.json, and what each error code means.
manifest.json describes your widget. Livedeck reads it on upload, builds the editor settings from it and gives the widget only the permissions listed in it. Unknown fields are an error so typos never hide.
{
"manifestVersion": 1,
"name": "Gift Goal",
"version": "1.0.0",
"sdk": "1",
"entry": "index.html",
"description": "A bar that fills up with gifts.",
"formats": ["9:16", "16:9"],
"size": { "default": [600, 160], "min": [300, 80], "max": [1080, 400] },
"permissions": ["events.gift", "media.play"],
"settings": [
{ "key": "goal", "type": "number", "label": { "de": "Ziel", "en": "Goal" }, "default": 100, "min": 1 },
{ "key": "giftId", "type": "gift", "label": { "de": "Nur dieses Geschenk", "en": "Only this gift" } },
{ "key": "accent", "type": "color", "label": { "de": "Farbe", "en": "Colour" }, "default": "#22c55e" },
{ "key": "doneSound", "type": "media", "label": { "de": "Ton bei Ziel", "en": "Goal sound" }, "accept": "audio" }
],
"locales": ["de", "en"]
}Fields
manifestVersion
Required: yes
Meaning: Always 1
name
Required: yes
Meaning: Name of the widget, at most 60 characters
version
Required: yes
Meaning: Version number x.y.z, for example 1.2.0
sdk
Required: yes
Meaning: SDK version, "1" today
entry
Required: no
Meaning: Start file, index.html by default. Must end in .html.
description
Required: no
Meaning: Short description, at most 300 characters
formats
Required: no
Meaning: ["9:16"], ["16:9"] or both (default: both)
size
Required: yes
Meaning: Size in pixels on the overlay canvas: default, min and max as [width, height]
permissions
Required: no
Meaning: Which data the widget gets (see below)
settings
Required: no
Meaning: Settings users change in the editor (at most 40)
locales
Required: no
Meaning: Languages your widget supports, for example ["de", "en"]
| Field | Required | Meaning |
|---|---|---|
| manifestVersion | yes | Always 1 |
| name | yes | Name of the widget, at most 60 characters |
| version | yes | Version number x.y.z, for example 1.2.0 |
| sdk | yes | SDK version, "1" today |
| entry | no | Start file, index.html by default. Must end in .html. |
| description | no | Short description, at most 300 characters |
| formats | no | ["9:16"], ["16:9"] or both (default: both) |
| size | yes | Size in pixels on the overlay canvas: default, min and max as [width, height] |
| permissions | no | Which data the widget gets (see below) |
| settings | no | Settings users change in the editor (at most 40) |
| locales | no | Languages your widget supports, for example ["de", "en"] |
The canvas is 1080 × 1920 pixels in 9:16 and 1920 × 1080 in 16:9. Sizes go from 16 to 3840 pixels. min and max are the limits when users resize the widget in the editor. Without them, default applies. Build the widget in fixed pixels for default: when users resize it, Livedeck zooms the whole page with the box (text, pictures and spacing grow together). If the box gets another shape than default, the page gets the extra room in that direction, so use 100% widths/heights, flexbox or grid where it should fill. livedeck.context.size is the page size in CSS pixels and livedeck.context.scale the zoom.
Permissions
Buyers see this list before buying, and the editor shows it under "Gets access to". Only ask for what you really need.
events.gift
Gifts (event gift)
events.chat
Chat messages (chat)
events.like
Likes, bundled (like)
events.follow
New followers (follow)
events.share
Shares of the LIVE (share)
events.join
A viewer joins the LIVE (join)
events.fanclub
Fan club joins (fanclub)
events.viewers
Viewer count (viewers)
stream.status
Live, offline or being checked (stream)
media.play
May play sounds from media settings through Livedeck
host.profile
The streamer's name and profile picture (livedeck.host)
| Permission | What the widget gets |
|---|---|
| events.gift | Gifts (event gift) |
| events.chat | Chat messages (chat) |
| events.like | Likes, bundled (like) |
| events.follow | New followers (follow) |
| events.share | Shares of the LIVE (share) |
| events.join | A viewer joins the LIVE (join) |
| events.fanclub | Fan club joins (fanclub) |
| events.viewers | Viewer count (viewers) |
| stream.status | Live, offline or being checked (stream) |
| media.play | May play sounds from media settings through Livedeck |
| host.profile | The streamer's name and profile picture (livedeck.host) |
Settings
Every setting has a key, a type and a label. The key starts with a lowercase letter followed by letters, digits or _ (at most 32 characters). A label is text or an object with languages such as {"de": "Farbe", "en": "Colour"}, at most 80 characters. The widget reads the values from livedeck.settings.
text
Fields: default, maxLength (at most 200)
Value in the widget: Text
number
Fields: default, min, max, step (all optional)
Value in the widget: Number
range
Fields: default, min and max (required), step
Value in the widget: Number, shown as a slider in the editor
boolean
Fields: default
Value in the widget: true or false
color
Fields: default as #rrggbb
Value in the widget: Colour as #rrggbb
select
Fields: options (1 to 50, each with value and label), default
Value in the widget: value of the chosen option
gift
Fields: default (gift ID or null)
Value in the widget: Gift ID as a number, or null
media
Fields: accept: audio, image or video. No default.
Value in the widget: true when the user picked a file of their own, otherwise false
| Type | Fields | Value in the widget |
|---|---|---|
| text | default, maxLength (at most 200) | Text |
| number | default, min, max, step (all optional) | Number |
| range | default, min and max (required), step | Number, shown as a slider in the editor |
| boolean | default | true or false |
| color | default as #rrggbb | Colour as #rrggbb |
| select | options (1 to 50, each with value and label), default | value of the chosen option |
| gift | default (gift ID or null) | Gift ID as a number, or null |
| media | accept: audio, image or video. No default. | true when the user picked a file of their own, otherwise false |
When a value is missing or invalid, the widget gets the default. That way updates with new settings work for everyone who already uses your widget.
Errors in manifest.json
When the check fails with "manifest.json is invalid", the code and the place are listed below it, for example settings[2].default.
manifest_not_object
The file is not a JSON object.
manifest_too_large
The file is larger than 64 KB.
manifest_invalid_json
Not valid JSON (often one comma too many or too few).
unknown_field
This field does not exist. Usually a typo.
required
A required field is missing.
wrong_type
Wrong type, for example text instead of a list.
unsupported_manifest_version
manifestVersion is not 1.
unsupported_sdk
sdk is not "1".
invalid_name
Name empty, longer than 60 characters or with invisible control characters.
invalid_text
Text empty, too long or with invisible control characters.
invalid_version
Version not in the form x.y.z (for example 1.0.0).
invalid_entry
entry is not a relative path to an .html file.
invalid_format
Format is not "9:16" or "16:9".
duplicate
Duplicate entry.
invalid_size
Size outside 16 to 3840 pixels, or default is not between min and max.
unknown_permission
This permission does not exist.
too_many_settings
More than 40 settings.
invalid_setting_key
key does not match the pattern (see above).
unknown_setting_type
This setting type does not exist.
invalid_default
default does not fit the type or is outside the bounds.
invalid_bounds
min, max, step or maxLength is invalid.
invalid_options
options are missing, empty, more than 50, or an option has no value.
invalid_media_kind
accept is not audio, image or video.
invalid_locale
This language does not exist. Allowed: en, de, tr, fr, es, it, ru, ar, zh-CN, ja, he, pt, nl, pl, uk, ko, hi, id, vi, th.
| Code | Meaning |
|---|---|
| manifest_not_object | The file is not a JSON object. |
| manifest_too_large | The file is larger than 64 KB. |
| manifest_invalid_json | Not valid JSON (often one comma too many or too few). |
| unknown_field | This field does not exist. Usually a typo. |
| required | A required field is missing. |
| wrong_type | Wrong type, for example text instead of a list. |
| unsupported_manifest_version | manifestVersion is not 1. |
| unsupported_sdk | sdk is not "1". |
| invalid_name | Name empty, longer than 60 characters or with invisible control characters. |
| invalid_text | Text empty, too long or with invisible control characters. |
| invalid_version | Version not in the form x.y.z (for example 1.0.0). |
| invalid_entry | entry is not a relative path to an .html file. |
| invalid_format | Format is not "9:16" or "16:9". |
| duplicate | Duplicate entry. |
| invalid_size | Size outside 16 to 3840 pixels, or default is not between min and max. |
| unknown_permission | This permission does not exist. |
| too_many_settings | More than 40 settings. |
| invalid_setting_key | key does not match the pattern (see above). |
| unknown_setting_type | This setting type does not exist. |
| invalid_default | default does not fit the type or is outside the bounds. |
| invalid_bounds | min, max, step or maxLength is invalid. |
| invalid_options | options are missing, empty, more than 50, or an option has no value. |
| invalid_media_kind | accept is not audio, image or video. |
| invalid_locale | This language does not exist. Allowed: en, de, tr, fr, es, it, ru, ar, zh-CN, ja, he, pt, nl, pl, uk, ko, hi, id, vi, th. |
Was this article helpful?