Variables du channel

Les variables du channel sont des paires {name, value} persistantes et partagées. Les noms sont utilisés tels quels, sans préfixe automatique ni propriétaire appli. Les valeurs écrites par l'API sont des strings non vides de 255 caractères maximum.

Applis : uniquement une lecture par préférence

kapp.variables expose seulement getFromPreference(path) dans une appli. get, set et create sont absents de son SDK ; les appels directs aux endpoints correspondants sont refusés avec 403, même avec d'anciens scopes d'écriture. Pour les données propres à l'appli, utiliser kapp.dataStorageV2 ou les autres stockages V2.

Déclarer une préférence dans preferences.config.js :

scoreSource: {
    type: 'channelVariable',
    label: {fr: 'Compteur à afficher', en: 'Counter to display'},
    required: false,
}

Le streamer choisit une variable de son channel. Déclarer variables:read dans les scopes du manifeste, puis lire la valeur actuelle :

const score = await kapp.variables.getFromPreference('scoreSource');
console.log(score?.value);

La méthode retourne {name, value}, ou null si aucune variable n'est sélectionnée ou si elle a été supprimée. Le chemin désigne une préférence (scoreSource, display.scoreSource), jamais un nom ou un identifiant de variable librement choisi. Les erreurs de permission et réseau restent des rejets.

kapp.preferences.get('scoreSource') contient un instantané {id, name, value, _ref} ou null. Le scope de lecture protège aussi cet instantané, au démarrage et lors du rafraîchissement des préférences : sans le scope requis, la préférence est hydratée à null. L'exemption historique des manifestes antérieurs à la version 2 reste identique pour les deux voies ; elle ne dispense jamais de la sélection du streamer.

Seul le streamer peut changer la sélection. L'appli ne peut pas s'accorder cet accès avec preferences.set, même en remplaçant un groupe ou une collection. Les default sont interdits ; une valeur brute de manifeste ou de migration ne constitue pas une autorisation. Supprimer une variable puis recréer son nom ne transfère pas l'autorisation vers la nouvelle variable.

Les anciens scopes variables:write et variables:manage sont acceptés mais ignorés dans les manifestes existants et retirés du catalogue. Aucun scope n'autorise une appli à créer ou modifier une variable du channel.

Widgets : lecture, création et modification

Méthode	Contrat
await get(name)	Variable {name, value}, ou null sur 404. Les autres erreurs restent des rejets.
await create(name, value)	Création stricte. Rejet 409 si le nom existe ou si le plafond du channel est atteint.
await set(name, value)	Crée si absente, sinon modifie. Le plafond est vérifié uniquement en cas de création.

Les widgets peuvent lire et modifier toutes les variables de leur channel, sans scopes d'appli ni quota individuel. Ils n'ont pas de getFromPreference. Les noms sont non vides, limités à 255 caractères ; les points n'ont aucune signification particulière. Choisir des noms simples sans /.

const variable = await kapp.variables.get('score');
const next = Number(variable?.value ?? '0') + 1;
await kapp.variables.set('score', String(next));

Une création et son contrôle de quota sont protégés par un verrou serveur. Deux set() simultanés sur un nom absent créent une seule variable ; la dernière écriture exécutée fixe sa valeur. L'exemple get() puis set() ne constitue toutefois pas un incrément atomique. create() permet d'initialiser sans écraser une valeur existante.

Plafond et variables existantes

100 variables au total par channel, configurable côté serveur, en comptant les widgets, le streamer et toutes les variables historiques. Aucun quota par appli et aucune limite supplémentaire par widget. La création depuis le dashboard applique le même plafond.

À la limite, create() et un set() sur un nouveau nom rejettent avec 409. Les valeurs existantes restent modifiables, même sur un channel déjà au-dessus du plafond. Une suppression libère une place.

Les variables existantes sont conservées sans renommage ni suppression, y compris les noms avec un ancien préfixe _ ou .. Toutes sont des variables du channel ; les applis les lisent uniquement après sélection dans leurs préférences. Aucun transfert automatique vers le data storage n'est effectué.