manifest.json per i widget Livedeck: campi, permessi e codici di errore

Tutti i campi, i permessi e i tipi di impostazione del manifest.json, e il significato di ogni codice di errore.

8 min di lettura Aggiornato il 4 nov 2026

Il manifest.json descrive il tuo widget. Livedeck lo legge al caricamento, ne ricava le impostazioni dell’editor e dà al widget solo i permessi elencati. I campi sconosciuti sono un errore, così nessun refuso passa inosservato.

json
{
  "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"]
}

Campi

manifestVersion

Obbligatorio: sì

Significato: Sempre 1

name

Obbligatorio: sì

Significato: Nome del widget, massimo 60 caratteri

version

Obbligatorio: sì

Significato: Numero di versione x.y.z, per esempio 1.2.0

sdk

Obbligatorio: sì

Significato: Versione dell’SDK, oggi "1"

entry

Obbligatorio: no

Significato: File iniziale, index.html di default. Deve terminare con .html.

description

Obbligatorio: no

Significato: Breve descrizione, massimo 300 caratteri

formats

Obbligatorio: no

Significato: ["9:16"], ["16:9"] o entrambi (default: entrambi)

size

Obbligatorio: sì

Significato: Dimensione in pixel sulla canvas dell’overlay: default, min e max come [larghezza, altezza]

permissions

Obbligatorio: no

Significato: Quali dati riceve il widget (vedi sotto)

settings

Obbligatorio: no

Significato: Impostazioni che gli utenti modificano nell’editor (massimo 40)

locales

Obbligatorio: no

Significato: Lingue supportate dal tuo widget, per esempio ["de", "en"]

La canvas è di 1080 × 1920 pixel in 9:16 e di 1920 × 1080 in 16:9. Le dimensioni vanno da 16 a 3840 pixel. min e max sono i limiti quando gli utenti ridimensionano il widget nell’editor. Senza di essi vale default. Costruisci il widget in pixel fissi per default: quando gli utenti lo ridimensionano, Livedeck ingrandisce l’intera pagina insieme al riquadro (testo, immagini e spaziature crescono insieme). Se il riquadro assume una forma diversa da default, la pagina riceve lo spazio in più in quella direzione, quindi usa larghezze/altezze al 100%, flexbox o grid dove deve riempire. livedeck.context.size è la dimensione della pagina in pixel CSS e livedeck.context.scale lo zoom.

Permessi

Gli acquirenti vedono questo elenco prima di comprare, e l’editor lo mostra sotto "Ha accesso a". Chiedi solo ciò che ti serve davvero.

events.gift

Regali (evento gift)

events.chat

Messaggi in chat (chat)

events.like

Like, raggruppati (like)

events.follow

Nuovi follower (follow)

events.share

Condivisioni della LIVE (share)

events.join

Uno spettatore entra nella LIVE (join)

events.fanclub

Iscrizioni al fan club (fanclub)

events.viewers

Numero di spettatori (viewers)

stream.status

Live, offline o in verifica (stream)

media.play

Può riprodurre suoni dalle impostazioni media tramite Livedeck

host.profile

Nome e immagine del profilo dello streamer (livedeck.host)

Impostazioni

Ogni impostazione ha una key, un type e una label. La key inizia con una lettera minuscola seguita da lettere, cifre o _ (massimo 32 caratteri). Una label è un testo o un oggetto con lingue come {"de": "Farbe", "en": "Colour"}, massimo 80 caratteri. Il widget legge i valori da livedeck.settings.

text

Campi: default, maxLength (massimo 200)

Valore nel widget: Testo

number

Campi: default, min, max, step (tutti facoltativi)

Valore nel widget: Numero

range

Campi: default, min e max (obbligatori), step

Valore nel widget: Numero, mostrato come slider nell’editor

boolean

Campi: default

Valore nel widget: true o false

color

Campi: default come #rrggbb

Valore nel widget: Colore come #rrggbb

select

Campi: options (da 1 a 50, ognuna con value e label), default

Valore nel widget: value dell’opzione scelta

gift

Campi: default (ID regalo o null)

Valore nel widget: ID regalo come numero, oppure null

media

Campi: accept: audio, image o video. Nessun default.

Valore nel widget: true se l’utente ha scelto un proprio file, altrimenti false

Nota: Le impostazioni multimediali non danno mai al widget l’indirizzo del file. Riproduci i suoni con livedeck.media.play(key); ottieni immagini e clip con livedeck.media.url(key).

Se un valore manca o non è valido, il widget riceve quello predefinito. Così gli aggiornamenti con nuove impostazioni funzionano per tutti quelli che usano già il tuo widget.

Errori in manifest.json

Se il controllo fallisce con "manifest.json is invalid", sotto trovi il codice e il punto dell’errore, ad esempio settings[2].default.

manifest_not_object

Il file non è un oggetto JSON.

manifest_too_large

Il file supera i 64 KB.

manifest_invalid_json

JSON non valido (spesso una virgola di troppo o mancante).

unknown_field

Questo campo non esiste. Di solito è un errore di battitura.

required

Manca un campo obbligatorio.

wrong_type

Tipo sbagliato, ad esempio testo invece di una lista.

unsupported_manifest_version

manifestVersion non è 1.

unsupported_sdk

sdk non è "1".

invalid_name

Nome vuoto, più lungo di 60 caratteri o con caratteri di controllo invisibili.

invalid_text

Testo vuoto, troppo lungo o con caratteri di controllo invisibili.

invalid_version

Versione non nel formato x.y.z (ad esempio 1.0.0).

invalid_entry

entry non è un percorso relativo a un file .html.

invalid_format

Il formato non è "9:16" o "16:9".

duplicate

Voce duplicata.

invalid_size

Dimensione fuori dall’intervallo 16–3840 pixel, oppure default non è tra min e max.

unknown_permission

Questo permesso non esiste.

too_many_settings

Più di 40 impostazioni.

invalid_setting_key

key non corrisponde al pattern (vedi sopra).

unknown_setting_type

Questo tipo di impostazione non esiste.

invalid_default

default non corrisponde al tipo o è fuori dai limiti.

invalid_bounds

min, max, step o maxLength non è valido.

invalid_options

options mancano, sono vuote, sono più di 50 oppure un’opzione non ha value.

invalid_media_kind

accept non è audio, image o video.

invalid_locale

Questa lingua non esiste. Consentite: en, de, tr, fr, es, it, ru, ar, zh-CN, ja, he, pt, nl, pl, uk, ko, hi, id, vi, th.

Questo articolo ti è stato utile?