Aller au contenu

Vue d'ensemble

Ce document donne un aperçu général des principaux points d'intégration dans l'application — comment WebView, la couche Android native, la pile BLE et les API backend fonctionnent ensemble.

L'objectif est d'expliquer ce qui communique avec quoi, et quels contrats (rappels, gestionnaires, endpoints) sont impliqués, sans entrer dans les détails d'implémentation bas niveau.

Vue d'ensemble générale

À un niveau élevé, il y a trois couches principales :

  1. WebView (JavaScript Frontend)

    • Affiche l'IU.
    • Utilise bridgeWebView pour communiquer avec la couche Android native.

  2. Couche Android Native

    • Implémentée dans BaseWebViewActivity et les classes associées.
    • Expose un ensemble de gestionnaires de pont (ex. startBleScan, connBleByMacAddress, initBleData, etc.).
    • S'intègre avec la pile BLE Android et les clients réseau/API.

  3. Backend / Services Externes

    • Endpoints HTTP/REST ou GraphQL que l'application appelle pour la configuration, les métadonnées des appareils, les données utilisateur, etc.
    • Services tiers optionnels (journalisation, analytique, authentification), si configurés.

Chacune de ces couches possède un contrat clair pour pouvoir évoluer indépendamment.

1. Intégration du Pont WebView ↔ Native

Objectif : Permettre au JavaScript s'exécutant dans WebView d'appeler des fonctions natives et de recevoir des rappels.

Concepts clés :

  • bridgeWebView.callHandler(name, payload, callback)

    • Appel JS → Native (ex. startBleScan, connBleByMacAddress, initBleData).
    • payload est généralement un objet JSON sérialisé en chaîne.
    • callback reçoit une réponse JSON en chaîne de la part du natif.

  • bridgeWebView.registerHandler(name, callback)

    • Appels Native → JS (événements).
    • JS enregistre des gestionnaires tels que :
      • findDeviceCallback (appareil découvert lors d'un scan)
      • connectSuccess (appareil connecté avec succès)
      • connectFail (connexion échouée ou expirée)
      • onCompleteCallback (initialisation des données BLE terminée)
      • Tout autre événement spécifique à l'application.

Responsabilités :

  1. WebView ne communique jamais directement avec BLE ou le système d'exploitation.
  2. WebView appelle uniquement des méthodes de pont bien définies et écoute les rappels enregistrés.
  3. Le pont agit comme une fine couche API entre JS et Android.

On peut considérer cela comme une mini « API interne » exposée au frontend.

2. Intégration Couche Native ↔ Pile BLE

Objectif : Encapsuler toutes les opérations BLE derrière un ensemble stable de méthodes de pont Java ↔ JS.

Les responsabilités typiques incluent : - Vérification de l'état BLE du téléphone - getPhoneBleStatus() est exposé à JS et utilise les API Android pour vérifier :

    - La prise en charge matérielle Bluetooth
    - Si le Bluetooth est activé
    - Les permissions requises

  • Scan des appareils

    • startBleScan() / stopBleScan() correspondent aux API de scan BLE Android.
    • Lorsque des appareils sont trouvés, le natif les sérialise en JSON et appelle findDeviceCallback en JS.

  • Connexion aux appareils

    • connBleByMacAddress(macAddress) encapsule la logique de connexion.
    • En cas de succès/échec/expiration, il déclenche connectSuccess ou connectFail côté JS.

  • Initialisation des données

    • initBleData() encapsule :
      • La découverte des services et des caractéristiques
      • Les lectures initiales optionnelles
      • La préparation des mappages internes nécessaires aux opérations ultérieures de lecture/écriture/notification.

  • Lorsque l'initialisation est terminée, onCompleteCallback est déclenché en JS.

Cette intégration maintient toute la complexité BLE dans le code natif, tout en exposant une API simple de haut niveau à WebView.

3. Intégration WebView / Native ↔ API Backend

Objectif : Synchroniser l'état des appareils et les actions utilisateur avec le backend.

L'emplacement de cette logique dépend de votre architecture :

  • WebView → Backend

    • JS appelle les API HTTP/GraphQL directement depuis WebView (pour les métadonnées des appareils, les comptes utilisateurs, les tableaux de bord, etc.).

  • Native → Backend

    • Le code Android natif appelle les API lorsque les opérations BLE doivent être associées à un état côté serveur (ex. enregistrement d'un appareil, envoi de télémétrie ou synchronisation de la configuration).

Points d'intégration typiques :

  • Authentification

    • Transmission de jetons/en-têtes aux endpoints backend.
    • Gestion des jetons expirés et des flux de ré-authentification.

  • Enregistrement et métadonnées des appareils

    • Correspondance entre les adresses MAC découvertes ou les numéros de série et les enregistrements d'appareils du backend.
    • Enrichissement des données BLE avec des métadonnées côté serveur (noms, modèles, propriétaires, etc.).

  • Télémétrie / journalisation

    • Envoi optionnel des lectures BLE, des erreurs et des journaux de session au backend pour le monitoring et l'analytique.

Ces API sont généralement documentées séparément dans la section API et Endpoints (chemins, formes requête/réponse, versionnage).

4. Versionnage et Compatibilité entre les Intégrations

Comme il y a plusieurs couches, le versionnage est important :

  • Version de l'API de pont

    • L'ensemble des gestionnaires (ex. startBleScan, connBleByMacAddress) forme un contrat entre WebView et le natif.
    • Tout changement incompatible doit incrémenter une version de pont et être coordonné entre les versions de l'application.

  • Version du protocole BLE

    • La structure GATT de l'appareil (services, caractéristiques, formats de charge utile) doit être versionnée, surtout si le firmware évolue dans le temps.

La documentation des intégrations doit clairement indiquer quelles versions sont censées fonctionner ensemble.

5. Gestion des Erreurs et Nouvelles Tentatives entre les Intégrations

Les intégrations sont souvent là où la plupart des échecs surviennent, nous traitons donc la gestion des erreurs comme une préoccupation de premier ordre :

  • WebView ↔ Native

    • Toutes les réponses de callHandler doivent inclure un indicateur de succès et un message d'erreur ou un code.
    • JS doit afficher des erreurs conviviales et proposer des nouvelles tentatives.

  • Native ↔ BLE

    • Gérer les problèmes BLE courants : expirations, déconnexions, permissions, fonctionnalités non prises en charge.
    • Mapper les codes d'erreur bas niveau en résultats simples (connectFail, timeout, etc.) consommés par JS.

  • Application ↔ Backend

    • Les erreurs réseau et HTTP doivent se manifester comme des réponses d'erreur structurées, pas des plantages.
    • Mettre en œuvre des stratégies de nouvelle tentative sûres où approprié (opérations idempotentes).

Où aller ensuite

Cette vue d'ensemble des intégrations est conçue comme point d'entrée. Le comportement détaillé pour chaque intégration est documenté dans des pages dédiées :

  • Flux BLE – séquence BLE étape par étape (état → scan → connexion → initialisation → lecture/écriture/notification).
  • Initialisation WebView – comment WebView est configuré, comment le pont est attaché et quels gestionnaires sont enregistrés au démarrage.
  • API et Endpoints – référence détaillée pour les routes backend, les charges utiles, l'authentification et le versionnage.