Appearance
Permissions : identifier le bon contrôle
Trois autorisations différentes peuvent intervenir. Aucune ne remplace les autres.
| Contrôle | Qui le fournit ? | Effet |
|---|---|---|
| Scope applicatif Kappapps | Développeur, infos.json.scopes de l’appli | Autorise l’opération de cette appli. Les mots chat:write ou apps:run ne sont pas des scopes OAuth Twitch. |
| Autorisation OAuth Twitch | Compte Twitch concerné lors de sa connexion | Autorise l’appel à Twitch ; ajouter un scope au manifeste n’accorde pas cette autorisation. Une reconnexion peut être nécessaire. |
| Feature du channel | Configuration et droits du channel | Rend un parcours disponible, par exemple Twitch Rewards pour un trigger TWREW. Une API ou un manifeste correct ne l’active pas. |
Un widget n’a pas de manifeste ni de liste de scopes applicatifs à inventer. Le contrôle des scopes ci-dessous concerne les applis. Cela ne supprime pas authentification, appartenance au channel, autorisations Twitch, features, quotas ou validations métier du widget. Les plugins et panneaux n’héritent pas des globaux du SDK : leurs hôtes contrôlent leur accès.
Matrice des opérations courantes
Déclarer seulement les scopes nécessaires, en plus des autres prérequis indiqués par la fiche de l’API.
| Opération dans une appli | Scope applicatif |
|---|---|
Lire les événements du chat / écrire avec chat.say | chat:read / chat:write |
| Shoutout Twitch / lire ou modifier les réglages du chat | chat:shoutout / chat-settings:read / chat-settings:write |
| Diffuser ou répondre aux plugins viewers | app-plugin-viewers:write |
| Diffuser au plugin streamer / appeler une fonction de ce plugin | app-plugin-streamer:write / app-plugin-streamer:call |
| Jouer une annonce configurée par référence | announces:play |
| Annonce libre vers chat, Discord, événement dashboard ou service | Respectivement chat:write, discord:message, dashboard-event:create, app-service:call ; cumuler les pistes choisies. |
| Distribuer les récompenses de l’appli | rewards:distrib |
| Lire / enregistrer / appeler des services | app-service:read / app-service:create / app-service:call |
Lire une variable choisie par le streamer (channelVariable) | variables:read ; lecture seule via variables.getFromPreference(path) |
| Lister ou lire / téléverser les médias du channel | file:read / file:write |
Lire le catalogue d’items du channel / les données du live (stream.getData) | channel-items:read / stream-data:read |
Lire les teams Kappapps et leurs membres (teams.get, team.getChannels) | teams:read, exigé pour toutes les versions de manifeste |
Modifier titre et catégorie du stream (twitch.setInfos) | channel-infos:write |
Découvrir ou lancer une appli/widget avec apps | apps:run |
| Timeout ou avertissement d’un viewer | moderation:manage |
| Bannir / débannir un viewer sur Twitch | moderation:ban (contrat de manifeste 4) |
| Blacklister un viewer | blacklist:manage |
Créer un trigger temporaire ou réagir à une préférence trigger | triggers:manage |
| Gestion VIP/modérateur | chat-roles:manage |
| Modifier la monnaie / les items d’un viewer | currency:manage / items:manage |
| Sondages / prédictions natifs Kappapps | kapp-poll:manage / kapp-prediction:manage |
| IA : contenu structuré, son, traduction, modération, correction | ai:generator, ai:sound, ai:trad, ai:moderate, ai:proofread |
| Générer une image IA | ai:draw (contrat de manifeste 4) |
| Statut d’abonnement ou de follow d’un viewer | channel-stats:read, plus autorisation Twitch correspondante |
| Sondage / prédiction Twitch | poll:manage / prediction:manage |
| Hype train, pubs (lecture / actions), objectifs, charité, bits, marqueurs | twitch-hype-train:read, twitch-ads:read / twitch-ads:manage, twitch-goals:read, twitch-charity:read, twitch-bits:read, stream-markers:read ; voir twitch |
| Vérifier un message par AutoMod / lire ou changer le Shield Mode | moderation:check / shield-mode:read / shield-mode:manage |
Cette matrice couvre tous les scopes vérifiés par les méthodes du SDK. Les sondages Twitch (poll:manage) et les sondages natifs Kappapps (kapp-poll:manage) ont des scopes différents. twitch-rewards:manage et hard-moderation:manage protègent des routes que le SDK n’expose pas : ne pas les déclarer sans besoin. Les méthodes sans scope dans cette matrice (YouTube, statuts, état du live, réglages du channel) n’en exigent pas ; RCON est réservé aux applis.
kapp.ai.draw() et le bannissement/débannissement Twitch sont accessibles aux widgets et à toutes les applis. Les applis déclarent respectivement ai:draw et moderation:ban dès le contrat de manifeste 4 ; les contrats antérieurs restent exemptés jusqu'à une nouvelle version. Les quotas IA, autorisations Twitch et protections des viewers restent applicables.
Le changement de rôle Kappapps (setRole / users.role.set) reste réservé aux widgets et aux applis officielles ; une appli tierce reçoit 403 quels que soient ses scopes. kapp.ai.generate() est réservé aux applis. Voir IA et users.
Les applis ne peuvent ni créer ni modifier les variables du channel. Les anciens scopes variables:write et variables:manage sont acceptés mais ignorés ; ils n'accordent aucun accès supplémentaire. Voir variables.
teams:read protège une nouvelle API : aucune ancienne version de manifeste n'est exemptée. La lecture reste limitée aux teams dont le channel courant est membre. Voir teams du channel.
Twitch et features
Le statut d’abonnement requiert aussi channel:read:subscriptions côté Twitch ; le suivi des followers requiert moderator:read:followers. Un refus OAuth ne se corrige pas en ajoutant ces chaînes à infos.json.scopes. La méthode de statut et le compteur global ont des contrats de retour différents : ne pas interpréter systématiquement une absence de donnée comme false ou zéro.
Le vertical ne dépend d’aucune feature : une appli déclare ses formats dans overlay-formats ; un widget suit la surface et ne déclare pas de formats. Voir layout.
Services, rôles et identité
domains et granted_role décrivent les consommateurs d’un service. Le contrôle d’un rôle dépend du trajet d’appel et de l’acteur identifié ; il ne remplace ni un scope, ni une validation des données. Ne pas traiter le login ou l’ID passé dans un argument comme une identité authentifiée. Un service destiné aux applis/widgets doit être conçu pour ces appelants ; réserver les mutations sensibles aux parcours disposant de contrôles adaptés. Lire appels de services.
Diagnostiquer un refus
- Identifier l’opération exacte, sa cible, le contexte app/widget/plugin et la version installée.
- Lire l’erreur : HTTP 403 de scope, refus OAuth, feature absente, cible indisponible et 429 sont des causes différentes.
- Comparer les scopes du manifeste effectivement installé, pas seulement ceux du fichier local.
- Vérifier autorisation Twitch, feature et appartenance au channel avant de modifier le code.
Des anciennes versions de manifeste sont exemptées de certains contrôles. Cette compatibilité historique est relative à chaque scope ; ce n’est pas une permission implicite pour une nouvelle appli et cela ne dépend pas du numéro commercial de sa version. Ne pas abaisser la version du manifeste pour contourner un refus. Une requête acceptée ne certifie pas la fin d’une action asynchrone.