Fonctionnement de l'API Yodadisplay Datas

Termes

Chaque affichage Yodadisplay est identifié par différents composants :

1. Une URL et son code unique (slug)
2. Un code d'agence non unique, de 6 caractères, sous la forme XYZ-01
3. Un type : devises, métaux ou fonte
4. Un modèle de panneau choisi dans Yodaforex (qui comprend les produits sélectionnés)
5. Un medium : l'URL peut être affichée dans le navigateur d'un écran, via un boitier Yodadisplay, un fire TV Stick...

Principes du Web Sockets

Si vous n'êtes pas familier avec les websocket, consultez la documentation idoine https://fr.javascript.info/websocket

L'API YodaDisplay utilise les websockets pour communiquer avec les displays. On distingue deux acteurs lors de la communication :

• Le serveur, qui est l'API YodaDisplay
• Le client, qui est le medium qui affiche les données (le code de votre URL Yodadisplay)

Tous les messages qui transitent via les websockets adoptent la structure suivante :

{
  "type": "le type de message",
  "payload": ... // Le contenu du message
}

Les types de messages sont qui peuvent être envoyés par le serveur vers le client sont les suivants :

• display-data : Contient les données à afficher
• force-refresh-request : Demande au client de redémarrer / se ré-initialiser
• error : Contient une erreur, associé à un code d'erreur, qui précède généralement la fermeture de la connexion

Les types de messages qui peuvent être envoyés par le client vers le serveur sont les suivants :

• pull-data-display : Demande au serveur de renvoyer les données à afficher (elles seront renvoyées via un message de type display-data)

Connexion au serveur

• URL : wss://v2.api.ydp.io/ws/v1/display-live-connect/{slug du medium}
• Ne nécessite pas d'authentification
• Immédiatement après la connexion, le serveur envoie un message contenant les informations d'affichage du display (structure détaillée plus bas pour le type de message display-data)
• Le serveur peut demander un redémarrage du système d'affichage en envoyant au client un message de type force-refresh-request (n'a pas de payload), auquel cas, le client devrait redémarrer / se ré-initialiser (code à prévoir de votre côté, voir les exemples de code plus bas)
• Si le serveur doit envoyer une erreur au client, il enverra un message de type error et le payload contiendra une propriété numérique nommée errorCode ainsi qu'une propriété errorMessage. Un message d'erreur peut se suivre d'une fermeture de la connexion par le serveur.
• Si le nombre maximum de connexions pour un même medium est atteint, l'appareil venant de réaliser la demande de connexion prendra la place d'un autre appareil déjà connecté. L'appareil qui s'apprêtera à se faire déconnecter recevra un message d'erreur avec un errorCode égal à -1 et sa connexion websocket sera fermée avec le status POLICY_VIOLATION (code 1008).
• Cas exceptionnel (à utiliser uniquement en cas de problème) : Pour demander manuellement un nouvel envoi des données, le client peut envoyer un message de type pull-data-display (sans payload). Il n'est pas nécessaire de demander régulièrement au serveur de renvoyer les données, celui-ci le fait automatiquement dès qu'une mise à jour est disponible via un message display-data.

Exemple Devises

Pour un display de type CURRENCY, la structure du message de type display-data retourné par le serveur est telle que :

{
  "type": "display-data",
  "payload": {
    "data": {
      "structureLayoutIdentifier": "ydp-data-currency-v1",
      "lines": [
        {
          "base": 1,
          "buyRate": 1.1588, // Lors de l'affichage, penser à toujours afficher 6 chiffres significatifs
          "buyPrice": 0.863,
          "sellRate": 1.038,
          "sellPrice": 0.9634,
          "countryIso": "US",
          "currencyIso": "USD",
          "countryDefaultName": "Etats Unis",
          "currencyDefaultName": "Dollar"
        },
        {
          "base": 100,
          "buyRate": 1.5221,
          "buyPrice": 0.657,
          "sellRate": 1.36,
          "sellPrice": 0.7353,
          "countryIso": "JP",
          "currencyIso": "JPY",
          "countryDefaultName": "Japon",
          "currencyDefaultName": "Yens"
        },
        ...
      ],
      "updatedAt": "2023-04-05T09:48:14"
    }
  }
}