kapp.overlay

Interagir avec l'overlay qui héberge l'exécution : notifications et grandes annonces à l'écran.

Service partagé appli + widget : API identique.

Quand l'utiliser (vs alternative)

• notification() / announce() : afficher un message stylé par le thème de l'overlay, sans coder le HTML/CSS toi-même.
• Si tu veux un visuel sur-mesure, code-le directement dans ton html/css plutôt que d'utiliser ce service.
• kapp.announces.screenNotification / screenAnnounce appellent ce service en interne.

Méthodes

• notification(message: string, options = {}): Promise<void> — notification à l'écran. options: { duration?, html?, title?, title_html?, target?, visual? }. async.
• announce(message: string, options = {}): Promise<void> — grande annonce à l'écran. Mêmes options. async.

(Le service expose aussi id, type, preferences et des méthodes internes emit/debug/callCoreFunction rarement utiles.)

Exemple (V2, exécutable)

await kapp.overlay.notification('Bienvenue !', {
    duration: 4,
    title: 'Nouveau follow',
    visual: { type: 'profile', url: await user.getProfileImageUrl() },
});

Le style appartient au streamer

L'apparence (couleurs, police, position, animations) vient de l'habillage que le streamer configure dans son dashboard : ce service n'expose aucune option de style, et les clés hors contrat sont ignorées côté serveur. Ton appli décrit le contenu — texte, titre, visuel — et c'est tout.

visual accepte une image de la médiathèque ({type:'image', source:'channel-media'|'library-media', token}) ou une photo de profil Twitch ({type:'profile', url}), avec fit, shape et alt optionnels. Un visuel non résolu est retiré sans faire échouer l'annonce.

target vaut main (défaut, l'overlay principal) ou current (l'overlay qui héberge réellement ton appli, résolu côté serveur — une appli ne peut pas viser un overlay arbitraire).

Pièges

• options.duration est en secondes (et non en millisecondes, contrairement à ce qu'indiquaient les anciennes versions de cette doc). Hors bornes, la valeur est ramenée dans les clous : 1 à 180 s pour une annonce, 1 à 60 s pour une notification.
• html: true permet du HTML dans le message, mais le contenu est nettoyé avant affichage : la mise en forme passe, pas les scripts ni les gestionnaires d'événements.
• Pour un rendu 100 % personnalisé, n'utilise pas overlay.* : injecte ton propre DOM.