Articles sur : Intégrations

Connecter des applications externes par WebSocket

PlayAbility peut échanger en temps réel des données de commande avec une autre application par l’intermédiaire d’un serveur WebSocket sur le port 13123. Vous décidez si les clients peuvent envoyer des entrées, recevoir l’état des sorties de PlayAbility, ou effectuer les deux.

Avant de commencer

L’application externe doit prendre en charge les connexions WebSocket et les messages JSON de PlayAbility.
PlayAbility doit rester ouvert ou continuer à s’exécuter dans la zone de notification.
Le serveur WebSocket actuel est uniquement local. Le client doit s’exécuter sur le même ordinateur que PlayAbility.

Utilisez ce point de terminaison :

ws://127.0.0.1:13123

Activer le serveur WebSocket

Ouvrez Connecteurs dans PlayAbility.
Sélectionnez WebSocket & MCP.
Dans Paramètres WebSocket, activez Activer le serveur WebSocket.
Choisissez les autorisations minimales dont votre intégration a besoin :
- Activez Autoriser les entrées WebSocket pour permettre au client d’envoyer des entrées de manette, clavier ou souris.
- Activez Autoriser les sorties WebSocket pour diffuser l’état des sorties de PlayAbility aux clients connectés.
Laissez Sortie WebSocket pleine vitesse désactivée, sauf si le client a besoin d’un débit supérieur au rythme normal d’environ 30 mises à jour par seconde.

La sortie pleine vitesse consomme davantage de ressources processeur et réseau.

Exiger une clé d’authentification

L’authentification est recommandée même pour une connexion locale, car d’autres logiciels exécutés sous votre compte pourraient sinon se connecter au serveur.

Activez Exiger une clé d’authentification.
Utilisez la valeur générée dans Clé d’authentification, ou sélectionnez Générer une nouvelle clé.
Affichez et copiez la clé dans le client de confiance.
Conservez-la comme un secret. Ne l’incluez pas dans des captures d’écran, des fichiers de configuration publics ou des messages d’assistance.

Après la connexion, le client reçoit un message semblable à celui-ci :

{
  "type": "CONNECT",
  "info": "WebSocket Server Started",
  "authRequired": true
}

Lorsque l’authentification est requise, le client doit envoyer ce message avant toute autre requête :

{
  "type": "AUTH",
  "key": "YOUR_AUTHENTICATION_KEY"
}

Une authentification réussie renvoie :

{
  "type": "AUTH_OK"
}

Envoyer une entrée de test simple

Vérifiez que Autoriser les entrées WebSocket est activé, puis envoyez un appui et un relâchement :

{
  "events": [
    {
      "type": "button",
      "code": "A",
      "value": true
    }
  ]
}

{
  "events": [
    {
      "type": "button",
      "code": "A",
      "value": false
    }
  ]
}

Envoyez toujours un relâchement pour les commandes qui peuvent rester maintenues. Les valeurs d’axe vont de -1 à 1 ; celles des gâchettes vont de 0 à 1.

Vérifier l’intégration

Connectez le client à ws://127.0.0.1:13123.
Vérifiez qu’il reçoit le message CONNECT.
Si l’authentification est activée, vérifiez qu’il reçoit AUTH_OK.
Envoyez un appui sur un bouton, puis son relâchement.
Vérifiez que PlayAbility ou l’application cible reçoit l’action.

Dépannage

La connexion est refusée

Vérifiez que Activer le serveur WebSocket est activé.
Vérifiez que PlayAbility est toujours en cours d’exécution.
Vérifiez que le client utilise le port 13123.
Vérifiez si un autre processus utilise déjà le port 13123.
Utilisez 127.0.0.1 ou localhost, et non une adresse provenant d’un autre appareil.

Le client se déconnecte avec une erreur d’autorisation

Envoyez le message AUTH avant toute entrée ou requête.
Copiez de nouveau la clé actuelle et supprimez les espaces accidentels.
Si vous avez sélectionné Générer une nouvelle clé, mettez à jour le client avec la nouvelle valeur.

Le client se connecte, mais les entrées ne fonctionnent pas

Activez Autoriser les entrées WebSocket.
Validez le JSON ainsi que le type, le code et la valeur de l’événement.
Vérifiez que Sortie Principale et le type de sortie concerné sont activés.
Envoyez à la fois les événements d’appui et de relâchement.

Aucun état de sortie n’est reçu

Activez Autoriser les sorties WebSocket. N’activez la sortie pleine vitesse que si le rythme normal de diffusion est insuffisant.

Sécurité et limitation réseau

Laissez l’authentification activée et ne communiquez chaque clé qu’à un logiciel de confiance.
Générez une nouvelle clé si la clé actuelle a pu être divulguée.
Ne considérez pas Autoriser les entrées WebSocket comme l’unique barrière de contrôle d’accès. Laissez l’authentification activée et désactivez le serveur WebSocket lorsque l’intégration n’est pas utilisée.
Dans les versions actuelles, le serveur est lié à localhost. L’IP du réseau local affichée dans le panneau ne rend pas le serveur accessible depuis un autre ordinateur ou téléphone.
Ne redirigez pas le port 13123 vers Internet.

Articles connexes

Mis à jour le : 30/07/2026

Cet article a-t-il répondu à vos questions ?

Merci !