Minuteur Flex — Guide du développeur
Guide du développeur

Intégration du Minuteur Flex : créer des minuteurs depuis votre application

Disponible dans le Minuteur Flex 6.3.0 et les versions ultérieures.

Votre application ou votre agent IA peut envoyer un minuteur au Minuteur Flex sur iPhone, iPad et Android. Le Minuteur Flex l'ouvre soit prêt à être ajusté et lancé, soit le lance immédiatement. Dans les deux cas, il s'affiche sur les écrans Flex Timer connectés de l'utilisateur.

Par exemple, une application d'entraînement qui connaît déjà l'exercice en cours peut lancer son compte à rebours sur le Minuteur Flex fixé au mur de la salle de sport, sans que l'utilisateur ait à configurer le minuteur dans le Minuteur Flex.

  • Un format unique sur toutes les plateformes : un minuteur est un petit objet JSON, décrit ci-dessous et dans le schéma JSON flextimer-timer.schema.json.
  • Trois façons de l'envoyer : un lien flextimer://timer (iOS et Android), une intention Android ou l'action Créer un minuteur à partir de JSON de l'application Raccourcis sur iOS.
  • L'utilisateur garde le contrôle : avant que votre application puisse lancer des minuteurs, le Minuteur Flex demande une seule fois à l'utilisateur de l'y autoriser.

Exigences

  • Minuteur Flex 6.3.0 ou ultérieur sur iOS 15+ ou Android. L'action Raccourcis nécessite iOS 16+.
  • Disponible pour tous les utilisateurs du Minuteur Flex. Aucun compte ni clé API n'est nécessaire de votre côté.
  • L'utilisateur doit être connecté au Minuteur Flex (ou l'utiliser en tant qu'invité).

Démarrage rapide

Une application de musculation lance un minuteur pour le squat dos : 5 séries, avec 2 minutes de repos après chacune.

{
  "version": 1,
  "name": "Squat dos 5x5",
  "segments": [
    { "timerMode": "RestDriven", "name": "Squat dos", "numberOfSets": 5, "restType": "fixed", "fixedRestDuration": 120 }
  ]
}

Encodez le JSON en base64url et ouvrez ce lien :

flextimer://timer?data=<JSON en base64url>&start=1&source=My%20Gym%20App&replace=1

La première fois, le Minuteur Flex demande à l'utilisateur si My Gym App peut lancer des minuteurs. Une fois l'autorisation accordée, vos minuteurs se lancent immédiatement. replace=1 ferme le minuteur que votre application a lancé précédemment, afin que le passage à l'exercice suivant ne laisse pas l'ancien minuteur ouvert.

let json = try JSONSerialization.data(withJSONObject: timer)
let data = json.base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")
var link = URLComponents(string: "flextimer://timer")!
link.queryItems = [
    URLQueryItem(name: "data", value: data),
    URLQueryItem(name: "start", value: "1"),
    URLQueryItem(name: "source", value: "My Gym App"),
    URLQueryItem(name: "replace", value: "1"),
    URLQueryItem(name: "x-success", value: "mygymapp://flextimer-done"),
]
UIApplication.shared.open(link.url!)

Pour vérifier que le Minuteur Flex est installé avec canOpenURL(_:), ajoutez flextimer à LSApplicationQueriesSchemes dans votre Info.plist.

iOS : Raccourcis

L'application Raccourcis inclut une action Créer un minuteur à partir de JSON avec les champs suivants :

  • JSON du minuteur : le minuteur.
  • Démarrer immédiatement : identique à start.
  • Nom de l'application : identique à source.
  • Remplacer les minuteurs antérieurs de cette application : identique à replace.

Utilisez-la dans des automatisations, ou depuis Siri, l'intelligence Apple et les agents IA qui exécutent des raccourcis. L'action se termine après la création du minuteur, de sorte que l'action suivante d'un raccourci s'exécute ensuite.

Android : envoyer une intention

val intent = Intent("com.gymnext.timer.action.CREATE_TIMER").apply {
    setPackage("com.gymnext.timer")
    putExtra("json", timerJson)
    putExtra("start", true)
    putExtra("source", "My Gym App")
    putExtra("replace", true)
}
startActivity(intent)
  • Extras : json, data ou url, plus source, x-success et x-error. start et replace peuvent être des booléens ou les chaînes "1" / "true".
  • Vérifier que le Minuteur Flex est installé : sur Android 11 et les versions ultérieures, ajoutez d'abord <package android:name="com.gymnext.timer" /> à <queries> dans votre manifeste.

Le lien flextimer://timer?... de l'exemple iOS fonctionne également sur Android, avec Intent.ACTION_VIEW.

Encodage base64url

// JavaScript
const data = btoa(unescape(encodeURIComponent(JSON.stringify(timer))))
  .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
# Python
data = base64.urlsafe_b64encode(json.dumps(timer).encode()).decode().rstrip("=")

Options

Les mêmes options fonctionnent dans les liens, l'intention Android et l'action Raccourcis, sauf que les rappels sont disponibles uniquement dans les liens et l'intention.

Option Description
data Le JSON du minuteur, encodé en base64url. Le rembourrage est facultatif. Jusqu'à 64 Ko de JSON.
json Le JSON du minuteur en texte brut. Intention Android et Raccourcis uniquement ; les liens utilisent data.
url Un lien https qui renvoie le JSON du minuteur. Jusqu'à 1 Mo, téléchargé en 10 secondes.
start 1 ou true lance le minuteur et l'affiche en cours. Sans cela, le Minuteur Flex ouvre les paramètres du minuteur afin que l'utilisateur puisse l'ajuster et le lancer.
source Le nom de votre application. Le Minuteur Flex l'affiche lorsqu'il demande à l'utilisateur d'autoriser votre application. Utilisez le même nom à chaque fois.
replace 1 ou true ferme les minuteurs que votre source a créés précédemment, avant de créer celui-ci.
x-success Un lien que le Minuteur Flex ouvre après avoir créé le minuteur, avec timerId ajouté à sa requête.
x-error Un lien que le Minuteur Flex ouvre s'il ne peut pas créer le minuteur, avec errorMessage ajouté à sa requête.

Fournissez exactement l'un de data, json ou url. Les minuteurs sont petits, quelques Ko même pour un entraînement long en plusieurs segments, donc data convient à presque tous les cas. Utilisez url lorsque le JSON est très volumineux ou que votre serveur l'héberge déjà.

Le format du minuteur (version 1)

Champ Type Description
version entier 1. Facultatif, mais recommandé.
name chaîne de caractères Facultatif. Le nom de l'entraînement. Un minuteur à segment unique sans name de segment utilise celui-ci.
description chaîne de caractères Facultatif. Une courte description de l'entraînement.
segments tableau Requis. De 1 à 50 segments, exécutés dans l'ordre. Deux ou plus forment un minuteur multi-segments.

Segments

Chaque segment possède un timerMode et les champs de ce mode.

  • Unités : toutes les durées sont en secondes entières.
  • Valeurs par défaut : un champ que vous omettez prend la valeur par défaut indiquée.
  • Les champs inconnus sont ignorés.
timerMode Utilisation Champs : valeur par défaut, puis plage autorisée
CountUp Pour le temps timeCap : 0 (sans limite), de 0 à 86400
CountDown AMRAP, ou toute durée fixe duration : 600, de 1 à 86400
Rounds Séries égales, avec repos égal facultatif roundDuration : 60, de 1 à 86400. numberOfRounds : 5, de 1 à 1000. restBetweenRounds : 0, de 0 à 86400
Tabata Travail et repos répétés, éventuellement par séries workDuration : 20. restDuration : 10 (0 autorisé). : 8. numberOfTabatas : 1. restBetweenTabatas : 0
ContinuousCue EMOM : un signal à chaque intervalle cueInterval : 60. totalDuration : 600
MixedInterval Toute séquence de périodes de travail et de repos intervals (requis, voir ci-dessous). numberOfRounds : 1, nombre de répétitions de la séquence. restBetweenRounds : 0
RestDriven Séries de toute durée, chacune suivie d'un repos (par exemple pour la musculation) numberOfSets : 5, de 1 à 1000. restType : fixed (par défaut) ou ratio. Avec fixed : fixedRestDuration, 120. Avec ratio : workRatio et restRatio, 1 chacun, de 1 à 100
Warmup Échauffement timeCap : 600 (0 pour aucune limite)
Cooldown Retour au calme timeCap : 600 (0 pour aucune limite)

Sauf indication contraire, les durées acceptent de 1 à 86400 et les nombres de 1 à 1000.

Chaque intervalle MixedInterval est un objet :

  • duration : requis.
  • type : work (par défaut) ou rest.
  • name : facultatif.

Un segment peut contenir de 1 à 200 intervalles.

Champs pour chaque segment

Champ Description
name Affiché sur le minuteur. Par défaut, le nom du mode, tel que « Tabata » ou « AMRAP ».
description Une courte description.
details Le texte complet de l'entraînement pour l'athlète. Les sauts de ligne sont conservés.
direction true compte à l'endroit, false compte à rebours. CountUp, ContinuousCue, RestDriven, Warmup et Cooldown comptent à l'endroit par défaut ; CountDown, Rounds, Tabata et MixedInterval comptent à rebours.
roundNames, intervalNames Un nom par série ou intervalle, tel que l'exercice. Utilisez null pour ceux sans nom.
roundNamesUseSame, intervalNamesUseSame true utilise le premier nom pour chaque série ou intervalle.
roundIntervalNamePresentation Présentation des noms : none (affichés comme titres), cue (à l'écran), speech (oralement), ou cueAndSpeech.

Les avertissements, les sons et les préférences similaires proviennent des propres paramètres du Minuteur Flex de l'utilisateur.

Exemples

Un AMRAP de 20 minutes :

{ "version": 1, "segments": [{ "timerMode": "CountDown", "name": "AMRAP 20", "duration": 1200 }] }

Un circuit, trois fois :

{
  "version": 1,
  "segments": [{
    "timerMode": "MixedInterval",
    "name": "Circuit",
    "intervals": [
      { "type": "work", "duration": 30, "name": "Pompes" },
      { "type": "rest", "duration": 10 },
      { "type": "work", "duration": 45, "name": "Squats" },
      { "type": "rest", "duration": 15 }
    ],
    "numberOfRounds": 3,
    "restBetweenRounds": 60
  }]
}

Une séance complète comme un seul minuteur multi-segments :

{
  "version": 1,
  "name": "WOD du samedi",
  "segments": [
    { "timerMode": "Warmup", "timeCap": 600 },
    { "timerMode": "Tabata", "name": "Burpees Tabata" },
    { "timerMode": "Cooldown", "timeCap": 300 }
  ]
}

Ce que voit l'utilisateur

  • Sans start : le Minuteur Flex ouvre les paramètres du nouveau minuteur, prêt à être ajusté et lancé par l'utilisateur.
  • Avec start, la première fois que votre application envoie un minuteur : le Minuteur Flex demande à l'utilisateur si votre application peut lancer des minuteurs.
  • Autoriser : ce minuteur et les suivants provenant de votre source se lanceront immédiatement.
  • Une seule fois : ce minuteur se lance, et le Minuteur Flex demandera à nouveau la prochaine fois.
  • Ne pas autoriser : le minuteur s'ouvre dans ses paramètres sans se lancer.
  • Avec start mais sans source : le Minuteur Flex demande à chaque fois.
  • Changer d'avis : les utilisateurs peuvent supprimer votre application sous Paramètres > Applications connectées. Le Minuteur Flex demandera alors à nouveau la prochaine fois que votre application lancera un minuteur.
  • Lorsque le Minuteur Flex n'est pas en cours d'exécution : votre minuteur l'ouvre.

Erreurs

Si Flex Timer ne parvient pas à créer le minuteur, il en informe l’utilisateur et ouvre votre lien x-error avec un errorMessage qui nomme le problème. Par exemple :

  • Le minuteur n’est pas un JSON valide.
  • segments est requis : une liste d’un ou plusieurs segments du minuteur.
  • segments[0].timerMode « Sprint » n’est pas pris en charge. Utilisez l’un des modes suivants : CountUp, CountDown, Rounds, Tabata, ContinuousCue, MixedInterval, RestDriven, Warmup, Cooldown.
  • segments[1].workDuration doit être un nombre entier compris entre 1 et 86400.
  • segments[0].intervals[2].type doit être « work » ou « rest ».
  • Ce minuteur utilise la version 2 du format, mais cette version de Flex Timer ne lit que la version 1. Mettez à jour Flex Timer pour l’ouvrir.
  • Le minuteur est plus lourd que 64 Ko. Hébergez le JSON et transmettez l’URL à la place.
  • url doit être un lien https.
  • L’application n’a pas réussi à télécharger le minuteur depuis l’URL (code d’état HTTP 404).

Pour détecter ces erreurs avant l’envoi, validez votre JSON par rapport à flextimer-timer.schema.json.

Utilisation depuis un agent IA

  1. Fournissez au modèle le schéma JSON ou les tableaux de format ci-dessus, puis demandez-lui de générer un objet JSON unique qui y corresponde. Demandez également name et details afin que l’athlète puisse voir l’entraînement sur le minuteur.
  2. Validez le résultat par rapport au schéma.
  3. Envoyez-le avec l’action Raccourcis (iOS), l’intention (Android) ou un lien flextimer://timer.

Versionnage

Il s’agit de la version 1 du format.

  • Ajouts : de nouveaux champs facultatifs peuvent être ajoutés à la version 1. Les versions de Flex Timer qui ne les connaissent pas les ignorent.
  • Modifications majeures : toute modification qui empêcherait les versions antérieures de lire correctement le format entraîne l’attribution d’un nouveau numéro de version.

Schéma JSON

Validez le JSON de votre minuteur par rapport à ce schéma (JSON Schema draft 2020-12) avant de l’envoyer, ou transmettez-le à un modèle d’IA afin qu’il génère des minuteurs valides.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gymnext.com/flextimer/flextimer-timer.schema.json",
  "title": "Flex Timer timer",
  "description": "Un minuteur envoyé par une autre application ou un agent IA à Flex Timer (version 1 du format). Voir timer-integration.md. Toutes les durées sont exprimées en secondes entières.",
  "type": "object",
  "required": ["segments"],
  "properties": {
    "version": {
      "description": "Version du format. Facultatif ; par défaut, elle est égale à 1. Flex Timer rejette les versions plus récentes que celles qu’il prend en charge.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1
    },
    "name": {
      "description": "Nom de l’entraînement. Pour un minuteur à un seul segment sans nom propre, celui-ci devient le nom du minuteur.",
      "type": "string"
    },
    "description": {
      "description": "Brève description de l’entraînement.",
      "type": "string"
    },
    "segments": {
      "description": "Un ou plusieurs segments du minuteur, exécutés dans l’ordre. S’il y en a plus d’un, le minuteur est dit multi-segments.",
      "type": "array",
      "minItems": 1,
      "maxItems": 50,
      "items": { "$ref": "#/$defs/segment" }
    }
  },
  "$defs": {
    "seconds": { "type": "integer", "minimum": 1, "maximum": 86400 },
    "secondsOrZero": { "type": "integer", "minimum": 0, "maximum": 86400 },
    "count": { "type": "integer", "minimum": 1, "maximum": 1000 },
    "names": {
      "description": "Un nom par série, intervalle ou set ; null si sans nom.",
      "type": "array",
      "items": { "type": ["string", "null"] }
    },
    "common": {
      "type": "object",
      "properties": {
        "name": { "description": "Nom du segment, affiché sur le minuteur. Par défaut, il dépend du mode (par exemple « Tabata »).", "type": "string" },
        "description": { "description": "Brève description du segment.", "type": "string" },
        "details": { "description": "Texte intégral de l’entraînement destiné à l’athlète ; les sauts de ligne sont conservés.", "type": "string" },
        "direction": {
          "description": "true pour un compte à rebours croissant, false pour un compte à rebours décroissant. Par défaut, selon le mode : CountUp, ContinuousCue, RestDriven, Warmup et Cooldown comptent à rebours croissant ; CountDown, Rounds, Tabata et MixedInterval comptent à rebours décroissant.",
          "type": "boolean"
        },
        "roundNames": { "$ref": "#/$defs/names" },
        "intervalNames": { "$ref": "#/$defs/names" },
        "roundNamesUseSame": { "description": "Utiliser le nom de la première série pour toutes les séries.", "type": "boolean" },
        "intervalNamesUseSame": { "description": "Utiliser le nom du premier intervalle pour tous les intervalles.", "type": "boolean" },
        "roundIntervalNamePresentation": {
          "description": "Présentation des noms : none (titres uniquement), cue (à l’écran), speech (audio), ou cueAndSpeech.",
          "enum": ["none", "cue", "speech", "cueAndSpeech"]
        }
      }
    },
    "segment": {
      "type": "object",
      "required": ["timerMode"],
      "allOf": [{ "$ref": "#/$defs/common" }],
      "oneOf": [
        {
          "title": "CountUp (pour le temps écoulé)",
          "properties": {
            "timerMode": { "const": "CountUp" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "Limite de temps ; 0 pour aucune limite. Par défaut, 0." }
          }
        },
        {
          "title": "CountDown (AMRAP)",
          "properties": {
            "timerMode": { "const": "CountDown" },
            "duration": { "$ref": "#/$defs/seconds", "description": "Durée. Par défaut, 600." }
          }
        },
        {
          "title": "Rounds (séries de durée égale, repos facultatif de durée égale)",
          "properties": {
            "timerMode": { "const": "Rounds" },
            "roundDuration": { "$ref": "#/$defs/seconds", "description": "Par défaut, 60." },
            "numberOfRounds": { "$ref": "#/$defs/count", "description": "Par défaut, 5." },
            "restBetweenRounds": { "$ref": "#/$defs/secondsOrZero", "description": "Par défaut, 0." }
          }
        },
        {
          "title": "Tabata (alternance de travail et de repos, éventuellement par séries)",
          "properties": {
            "timerMode": { "const": "Tabata" },
            "workDuration": { "$ref": "#/$defs/seconds", "description": "Par défaut, 20." },
            "restDuration": { "$ref": "#/$defs/secondsOrZero", "description": "Par défaut, 10." },
            "roundsPerTabata": { "$ref": "#/$defs/count", "description": "Par défaut, 8." },
            "numberOfTabatas": { "$ref": "#/$defs/count", "description": "Par défaut, 1." },
            "restBetweenTabatas": { "$ref": "#/$defs/secondsOrZero", "description": "Par défaut, 0." }
          }
        },
        {
          "title": "ContinuousCue (EMOM : un signal à chaque intervalle)",
          "properties": {
            "timerMode": { "const": "ContinuousCue" },
            "cueInterval": { "$ref": "#/$defs/seconds", "description": "Nombre de secondes entre les signaux. Par défaut, 60." },
            "totalDuration": { "$ref": "#/$defs/seconds", "description": "Durée totale. Par défaut, 600." }
          }
        },
        {
          "title": "MixedInterval (toute séquence d’alternance entre travail et repos)",
          "required": ["intervals"],
          "properties": {
            "timerMode": { "const": "MixedInterval" },
            "intervals": {
              "type": "array",
              "minItems": 1,
              "maxItems": 200,
              "items": {
                "type": "object",
                "required": ["duration"],
                "properties": {
                  "type": { "enum": ["work", "rest"], "description": "Par défaut, work." },
                  "duration": { "$ref": "#/$defs/seconds" },
                  "name": { "type": ["string", "null"], "description": "Par exemple, le nom de l’exercice." }
                }
              }
            },
            "numberOfRounds": { "$ref": "#/$defs/count", "description": "Nombre de répétitions de la séquence. Par défaut, 1." },
            "restBetweenRounds": { "$ref": "#/$defs/secondsOrZero", "description": "Par défaut, 0." }
          }
        },
        {
          "title": "RestDriven (séries de durée variable, chacune suivie d’un repos)",
          "properties": {
            "timerMode": { "const": "RestDriven" },
            "numberOfSets": { "$ref": "#/$defs/count", "description": "Par défaut, 5." },
            "restType": { "enum": ["fixed", "ratio"], "description": "Par défaut, fixed." },
            "fixedRestDuration": { "$ref": "#/$defs/secondsOrZero", "description": "Durée du repos après chaque série lorsque restType est fixed. Par défaut, 120." },
            "workRatio": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Lorsque restType est ratio, le repos est calculé comme une proportion de la durée de la série selon restRatio. Par défaut, 1." },
            "restRatio": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Par défaut, 1." }
          }
        },
        {
          "title": "Warmup",
          "properties": {
            "timerMode": { "const": "Warmup" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "0 pour aucune limite. Par défaut, 600." }
          }
        },
        {
          "title": "Cooldown",
          "properties": {
            "timerMode": { "const": "Cooldown" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "0 pour aucune limite. Par défaut, 600." }
          }
        }
      ]
    }
  }
}