Adapter une app au vertical

Le runtime overlay V2 héberge les apps en SDK app V1 comme V2. Il donne le cadre disponible ; l'app choisit sa présentation. Le SDK ne déplace pas vos boutons, votre caméra ou votre terrain de jeu. Les API kapp.overlay.layout, LAYOUT_CHANGED et resolveArea présentées ici appartiennent au SDK app V2.

Le multiformat est le fonctionnement standard du runtime overlay V2 pour tous les channels, sans feature à activer. Les overlays, les aperçus et le DEV HUB suivent les dimensions disponibles. Une app garde les seuls formats qu'elle déclare : le runtime n'invente jamais de format non déclaré.

Déclarer le format après adaptation

Dans infos.json :

{
  "overlay-formats": ["16:9", "9:16"]
}

overlay-formats est la seule déclaration des formats supportés. Absente, elle vaut historiquement ["16:9"]. Présente, sa liste est respectée, sans ajout automatique de 16:9 : ["9:16"] est donc valide pour une app uniquement verticale. Le format de la surface est choisi s'il est déclaré ; sinon, le premier format de la liste est conservé, réduit et centré dans la sortie disponible. Une liste vide, null ou un format inconnu sont des erreurs de manifeste.

L'iframe remplit toujours le cadre du format choisi, à l'origine : 1920 × 1080 en horizontal, 1080 × 1920 en vertical. Sa taille et sa position ne se déclarent pas dans le manifeste. L'app organise son contenu à l'intérieur. Une popout ou un aperçu overlay DEV HUB démarre aux dimensions du premier format déclaré (horizontal si la déclaration est absente).

L'ancien champ window est accepté mais ignoré, quel que soit son contenu : il ne change plus la taille de l'iframe, son placement ni les dimensions initiales d'une popout. Il peut être supprimé des manifestes existants. Les anciennes apps sans overlay-formats disposent désormais du cadre horizontal complet ; celles qui dépendaient de leur petite fenêtre doivent appliquer ces dimensions à un conteneur interne.

Le bootstrap des nouvelles apps déclare seulement overlay-formats: ["16:9"] pour sa géométrie. Déclarez seulement les formats réellement adaptés et testés. Une ancienne app en SDK app V1 sans déclaration reste dans le cadre horizontal ; ses médias et son interface ne deviennent pas automatiquement verticaux. Ni le SDK app V1 ni le SDK app V2 n'exigent infos.window dans leur message de démarrage.

L'orientation de la surface vient seulement des dimensions disponibles : largeur > hauteur donne horizontal ; sinon vertical, carré compris. Aucune résolution exacte n'est exigée. Le parent réduit et centre le cadre complet dans la sortie avec un seul zoom visuel. Cela fonctionne dès le lancement, sans rouvrir les préférences, et lors des redimensionnements sans redémarrer l'app.

Lire les dimensions, réagir si nécessaire

Lire le contrat commun de layout pour les dimensions, le changement de format et le nettoyage des abonnements. Appliquer le layout initial puis les mises à jour, sans rejouer une action métier.

Placer le contenu de l'app depuis ses préférences

Si le streamer doit déplacer un jeu ou un panneau, exposez une préférence containerArea dans le dashboard de l'app. Sa valeur par défaut et ses contraintes décrivent la zone du contenu. Par exemple, un flipper de 520 × 540 peut rester dans cette zone au sein de l'iframe plein cadre. Le formulaire conserve les placements ; l'app doit les appliquer à son conteneur interne :

// La préférence "placement" est déclarée comme containerArea par l'app.
const content = document.querySelector('#game');
const placeContent = () => {
    const rect = kapp.overlay.resolveArea(kapp.preferences.get('placement'));
    Object.assign(content.style, {
        position: 'absolute',
        left: `${rect.x}px`, top: `${rect.y}px`,
        width: `${rect.w}px`, height: `${rect.h}px`
    });
};
placeContent();
kapp.overlay.events.on(kapp.overlay.EVENTS.LAYOUT_CHANGED, placeContent);
// Au nettoyage : events.off(kapp.overlay.EVENTS.LAYOUT_CHANGED, placeContent).

La préférence n'est pas un placement automatique de l'iframe. L'app reste libre d'utiliser du CSS responsive, plusieurs conteneurs ou sa propre logique. Les tailles et limites du contenu appartiennent à l'app et à la configuration de ce champ, pas à infos.json.

Médias et rectangles enregistrés

Les inputs mediaFile, containerArea, containerAreas conservent les coordonnées horizontales et ajoutent une variante facultative :

const area = {
    x: 100, y: 200, w: 640, h: 360,
    portrait: {x: 40, y: 300, w: 1000, h: 600}
};
const current = kapp.overlay.resolveArea(area); // {x,y,w,h} dans le cadre courant

L'horizontal reste indépendant du vertical. Sans variante, le placement horizontal est réduit proportionnellement et centré. portrait: null revient à ce placement hérité. Une écriture horizontale qui omet portrait conserve la variante enregistrée. Le fichier, le volume et les bornes de lecture restent communs. Les rectangles sont libres, sauf contraintes explicites de l'app.

kapp.medias.playMedia(prefs.monMedia) et KMedia sélectionnent le bon placement et le suivent pendant la lecture. Un changement de format déplace l'image/vidéo existante sans la relancer. Les préférences conservent toujours les deux rectangles : ne remplacez pas la valeur sauvegardée par le résultat de resolveArea.

Les coordonnées passées explicitement à une option de lecture, à playImage, playVideo ou à setPosition sont déjà dans le cadre courant. Elles ne sont pas converties comme une préférence enregistrée. Les lecteurs directs sans coordonnées occupent le cadre courant. Pour un rectangle personnalisé, utilisez resolveArea puis actualisez votre élément lors du changement de layout. Ne multipliez pas ces coordonnées par scale.

Choisir une présentation adaptée à l'app

Examinez les tailles fixes, les coordonnées calculées sur 1920/1080, les zooms CSS/canvas existants, les éditeurs de placement personnalisés, les caméras et les terrains de jeu. Choisissez librement une disposition pertinente : réorganisation, zones différentes, caméra adaptée ou conservation d'un terrain horizontal dans une interface verticale. Une simple permutation largeur/hauteur ne convient pas à tous les jeux. Préservez le fonctionnement horizontal et les préférences existantes.

Recette obligatoire avant publication

Avec le DEV HUB, obtenez la vraie page via prepare_preview (surface overlay, puis external si l'app est interactive). Testez 1920 × 1080, 1280 × 720, 1080 × 1920 et 720 × 1280, puis une surface carrée et une taille intermédiaire. Une app à format unique doit aussi rester dans son format sur une sortie d'une autre orientation. Redimensionnez sans recharger : état de partie, actions, vidéo et son doivent continuer. Vérifiez les interactions, les placements hérités/personnalisés et l'absence de double zoom. Publiez l'app adaptée seulement après la release de la plateforme et la validation de tous ses formats déclarés.

Mesurez le viewport intérieur de la surface, pas seulement la taille extérieure de la fenêtre : les bordures du système prennent de la place et l’écran peut limiter la hauteur. Par exemple, une sortie 720 × 1280 doit transmettre format: '9:16', width: 1080, height: 1920, viewportWidth: 720, viewportHeight: 1280 et scale: 2/3. Attendez LAYOUT_CHANGED après le redimensionnement, puis vérifiez la taille et le centrage réels de l’iframe. Une lecture faite juste après la commande de taille peut encore contenir l’ancien layout. Testez aussi un démarrage directement en portrait ; un changement de format déjà réussi ne remplace pas ce cas.