Préférences d'annonce

Un champ announces permet au streamer de choisir le contenu, les variations et les canaux de diffusion. L'appli décide quand le jouer. Le moteur d'annonce s'exécute côté serveur.

Déclarer le formulaire

Objet à exporter depuis preferences.config.js :

{
  "type": "group",
  "groupItems": {
    "messages": {
      "type": "group",
      "groupItems": {
        "onWin": {
          "type": "announces",
          "label": { "fr": "À la victoire", "en": "On win" },
          "default": {
            "enabled": true,
            "messages": ["#user# wins #amount# points!"],
            "screenNotification": { "enabled": true }
          },
          "defaults": {
            "fr": {
              "enabled": true,
              "messages": ["#user# gagne #amount# points !"],
              "screenNotification": { "enabled": true }
            }
          },
          "wuOptions": {
            "tags": {
              "user": { "fr": "Le gagnant", "en": "Winner" },
              "amount": { "fr": "Points gagnés", "en": "Points won" }
            }
          }
        }
      }
    }
  }
}

wuOptions.tags décrit les tags disponibles dans le formulaire ; l'appli fournit leurs valeurs au déclenchement. Le défaut localisé est une configuration complète, pas seulement un patch de messages.

L'ancienne forme { type: 'chatMessage', message: '...', aiEnrich: false } n'est pas la forme structurée à produire pour une nouvelle préférence. Ne recopie pas l'ancien exemple de wuOptions.prototypeData des annonces : cette option historique est tolérée, mais le formulaire actuel ne l'utilise pas pour préremplir de nouvelles annonces. Pour une collection de champs announces, le prototype se place sur la collection selon les règles générales.

Déclencher la préférence

Dans infos.json, ajoute announces:play à la liste des scopes. Dans une fonction async de l'appli :

await kapp.announces.play('messages.onWin', { user: 'Sam', amount: '250' });

Le serveur relit les réglages effectifs du streamer. Une préférence hydratée porte sa référence _ref ; discord.webhook est seulement un booléen. L'URL privée ne sort pas du serveur.

Passer cette préférence hydratée, avec sa référence intacte, à announce() utilise la même voie référencée. Fabriquer un payload libre relève d'un autre contrat et de scopes par piste : voir service annonces.

Activation et vérification

• enabled: false désactive globalement l'annonce.
• Les pistes explicitement actives sont utilisées. Si aucune n'est active, le moteur se replie sur les pistes par défaut du channel : tout décocher ne signifie donc pas forcément « ne rien diffuser ».
• Sans piste après ce repli, rien n'est joué. Sans message global ni variation propre à une piste, rien n'est joué non plus.
• Une piste avec ses propres variations peut jouer sans message global.

Pour la recette, choisir explicitement une notification écran et un message reconnaissable, puis vérifier les tags. Tester ensuite la désactivation globale et le repli sur les pistes du channel si nécessaire. await play() confirme l'acceptation par la plateforme, pas l'arrivée à l'écran : la diffusion peut être différée.

La liste des pistes, tags automatiques, délais, erreurs et options d'affichage reste centralisée dans announces. Ne recrée pas une diffusion séparée côté client pour chaque piste.