Développeurs : créez vos actions pour ICane

ICane est ouvert : n'importe quel service web peut devenir une action déclenchable par les boutons de la canne. Pas de kit de développement, pas de compte, pas de validation — deux adresses web suffisent.

Le principe

Vous publiez un service web qui décrit votre action (son nom, ce qu'elle fait, les données dont elle a besoin).
L'utilisateur ajoute votre service dans l'application ICane : onglet « Réglages », élément « Actions développeur », bouton « Ajouter une action développeur », puis il saisit l'adresse de votre service.
L'application lit votre déclaration et présente les autorisations que vous demandez, avec vos explications. Les autorisations optionnelles restent au choix de l'utilisateur.
Dans « Personnalisation des boutons », l'utilisateur affecte votre action à une combinaison de boutons de sa canne.
À chaque appui, l'application appelle votre service avec les données autorisées, et restitue votre réponse par la voix, un son ou une vibration.

Déclarer votre service (GET)

L'adresse saisie par l'utilisateur doit répondre à une requête GET par un document JSON :

{
  "title": "Café le plus proche",
  "description": "Annonce le café ouvert le plus proche et la direction à suivre.",
  "post": "https://exemple.fr/icane/executer",
  "needs": {
    "location": { "required": true, "why": "Trouver le café le plus proche de vous." },
    "compass": { "required": false, "why": "Vous indiquer la direction à suivre." }
  }
}

Champs acceptés

title (texte) : nom affiché à l'utilisateur. S'il est vide, c'est l'adresse du service qui est affichée.
description (texte) : présentation de l'action.
post (adresse) : l'URL appelée à chaque appui. Sans elle, l'action n'est pas activable.
needs (objet) : autorisations demandées, chacune sous la forme { "required": true/false, "why": "explication" }. Clés honorées : location (position GPS) et compass (cap de la boussole). La clé gyroscope est réservée pour un usage futur. Toute autre clé serait affichée à l'utilisateur mais jamais alimentée — à éviter. Une autorisation required est indispensable au fonctionnement et activée d'office ; une autorisation optionnelle est activée ou non par l'utilisateur. Le champ why explique à quoi sert la donnée : soignez-le, c'est lui qui inspire confiance.

Contraintes : répondez en 5 secondes maximum, avec un code HTTP 2xx. La déclaration est relue à l'ajout et depuis les détails de l'action ; les choix de l'utilisateur sur les autorisations optionnelles sont conservés.

Répondre aux appuis (POST)

À chaque déclenchement, l'application envoie une requête POST à votre adresse d'exécution, avec un corps JSON :

{
  "ctx": {
    "locale": "fr-FR",
    "trigger": "button_pattern",
    "location": { "lat": 44.85, "lng": -0.58, "accuracyM": 8.0, "altitudeM": 12.0, "timestamp": "2026-08-02T10:30:00Z" },
    "heading": { "headingDeg": 135.0, "timestamp": "2026-08-02T10:30:01Z" }
  }
}

locale : balise de langue BCP 47 (exemple « fr-FR ») — répondez dans cette langue.
trigger : "button_pattern" (seule valeur actuelle : appui sur la combinaison de boutons).
location (si autorisée) : lat / lng en degrés décimaux, accuracyM (précision en mètres), altitudeM, timestamp ISO 8601. Position acquise en 4 secondes maximum, en précision navigation ; champ absent si elle est indisponible.
heading (si autorisée) : headingDeg (0 à 360, nord = 0), timestamp. Capté en 2 secondes maximum ; absent si indisponible.

Votre service doit répondre en 5 secondes maximum, en JSON.

Votre réponse

{
  "say": "Le café Utopia est à 120 mètres, direction 2 heures.",
  "commands": [
    { "type": "haptic", "pattern": "short_double" }
  ]
}

say (texte) : énoncé immédiatement par la synthèse vocale du téléphone, dans la voix et la langue de l'utilisateur.
commands (liste, exécutée dans l'ordre) :
- { "type": "say", "text": "…" } : parole ;
- { "type": "haptic", "pattern": "short_double" } : vibration du téléphone en double impulsion ; toute autre valeur de pattern donne une impulsion simple ;
- { "type": "sound", "id": "sounds/information_alert.wav" } : joue un son embarqué de l'application. Sons recommandés (préfixés de sounds/) : information_alert.wav, mode_enter.wav, mode_exit.wav, connection_success.wav, flag_found.wav, hunt_complete.wav, sense_poi.wav, online.wav, offline.wav.

Toute erreur ou dépassement de délai est silencieux pour l'utilisateur : aucun message d'erreur ne le dérange.

Bonnes pratiques

Répondez vite : au-delà de 5 secondes, l'action reste muette.
Soyez bref : votre réponse est écoutée en déplacement, souvent dans la rue. Une phrase courte et utile vaut mieux qu'un paragraphe.
Utilisez HTTPS : indispensable pour que le système d'exploitation du téléphone accepte la connexion.
Ne demandez que le nécessaire : chaque autorisation superflue est une raison de ne pas installer votre action.
La position transmise est la meilleure disponible au moment de l'appui ; sa précision en mètres vous est fournie pour adapter votre réponse.

Vie privée

Les données de l'utilisateur ne transitent que vers votre service, uniquement lors d'un appui volontaire, et uniquement pour les autorisations accordées. Supprimer l'action depuis l'application délie immédiatement les boutons associés.

Note : les autorisations optionnelles sont appliquées au moment où l'utilisateur affecte l'action à une combinaison de boutons ; s'il les modifie ensuite, il doit réaffecter l'action pour que le changement prenne effet.

Une question ?

Écrivez-nous à contact@ieyes.fr : nous serons ravis de découvrir ce que vous construisez pour les utilisateurs d'ICane.