kapp.overlay

Dimensions et placements V2

layout décrit le format utilisé, les dimensions logiques width/height, les dimensions disponibles viewportWidth/viewportHeight, le zoom scale déjà appliqué et le rectangle reference. events.on(EVENTS.LAYOUT_CHANGED, callback) informe d'un redimensionnement sans redémarrer l'exécution. resolveArea(area) résout un rectangle sauvegardé avec sa variante portrait sans modifier les données. Voir Adapter une app au vertical, également lisible avec read_sdk_doc {service: "vertical"}.

L'app gère son interface responsive. Les widgets V2 suivent la surface sans déclaration de formats. Sans nouveau contexte parent, le SDK conserve l'horizontal historique.

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 :

• isExternal(): boolean — API recommandée pour savoir si l'app tourne dans la popout interactive ;
• displayMode: 'overlay' | 'external' — contexte réel de cette exécution : rendu OBS non cliquable ou popout interactive ;
• id, type, preferences et les méthodes internes emit/debug/callCoreFunction, rarement utiles.

displayMode est indépendant du launch-mode du manifeste. Une app launch-mode: oneshot + externable: true peut donc observer l'une ou l'autre valeur selon le bouton utilisé par le streamer.

const interactive = kapp.overlay.isExternal();
document.body.classList.toggle('external-ui', interactive);

Les pages overlay OBS neutralisent les clics (pointer-events: none). La popout ne les réactive que lorsque displayMode === 'external'. Une preview DEV en runtime technique oneshot mais en displayMode: 'overlay' reste donc volontairement non cliquable, comme OBS.

Ne pas confondre type et displayMode

kapp.overlay.type décrit le runtime parent historique : main, secondary ou oneshot. Le oneshot de cette liste est le runtime de la page popup ; ce n'est ni la preuve que l'app a launch-mode: oneshot, ni l'API à utiliser pour détecter une popout. Pour adapter l'interface au contexte cliquable, utilise kapp.overlay.isExternal(). displayMode reste disponible si tu as besoin de la valeur brute.

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.