Temporizador Flex — Guía para desarrolladores
Guía para desarrolladores

Integración con Temporizador Flex: crear temporizadores desde tu aplicación

Disponible en Temporizador Flex 6.3.0 y versiones posteriores.

Tu aplicación o agente de IA puede enviar un temporizador a Temporizador Flex en iPhone, iPad y Android. Temporizador Flex lo abre listo para ajustarlo e iniciarlo, o lo inicia de inmediato. En cualquier caso, se muestra en las pantallas de Temporizador Flex conectadas del usuario.

Por ejemplo, una aplicación de entrenamiento que ya conozca el ejercicio actual puede iniciar su cuenta regresiva en el Temporizador Flex de la pared del gimnasio, sin que el usuario tenga que configurar el temporizador en Temporizador Flex.

  • Un formato para todas las plataformas: un temporizador es un pequeño objeto JSON, descrito a continuación y en el esquema JSON flextimer-timer.schema.json.
  • Tres formas de enviarlo: un enlace flextimer://timer (iOS y Android), una intención de Android o la acción Crear temporizador a partir de JSON en la aplicación Atajos de iOS.
  • El usuario mantiene el control: antes de que tu aplicación pueda iniciar temporizadores, Temporizador Flex le pregunta al usuario una vez si desea permitirlo.

Requisitos

  • Temporizador Flex 6.3.0 o posterior en iOS 15+ o Android. La acción de Atajos requiere iOS 16+.
  • Disponible para todos los usuarios de Temporizador Flex. No se necesita ninguna cuenta ni clave de API por tu parte.
  • El usuario debe haber iniciado sesión en Temporizador Flex (o usarlo como invitado).

Guía rápida

Una aplicación de entrenamiento de fuerza inicia un temporizador para sentadillas con barra: 5 series, con 2 minutos de descanso después de cada una.

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

Codifica el JSON como base64url y abre este enlace:

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

La primera vez, Temporizador Flex le pregunta al usuario si My Gym App puede iniciar temporizadores. Una vez que lo permite, tus temporizadores se inician de inmediato. replace=1 cierra el temporizador que tu aplicación inició anteriormente, para que al pasar al siguiente ejercicio no quede abierto el temporizador anterior.

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!)

Para comprobar que Temporizador Flex está instalado con canOpenURL(_:), añade flextimer a LSApplicationQueriesSchemes en tu Info.plist.

iOS: Atajos

La aplicación Atajos incluye una acción Crear temporizador a partir de JSON con estos campos:

  • JSON del temporizador: el temporizador.
  • Iniciar de inmediato: igual que start.
  • Nombre de la aplicación: igual que source.
  • Reemplazar los temporizadores anteriores de esta aplicación: igual que replace.

Úsala en automatizaciones o desde Siri, Apple Intelligence y agentes de IA que ejecuten atajos. La acción finaliza después de que se haya creado el temporizador, por lo que la siguiente acción de un atajo se ejecuta después.

Android: enviar una intención

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 o url, además de source, x-success y x-error. start y replace pueden ser booleanos o las cadenas "1" / "true".
  • Comprobar que Temporizador Flex está instalado: en Android 11 y versiones posteriores, primero añade <package android:name="com.gymnext.timer" /> a <queries> en tu manifiesto.

El enlace flextimer://timer?... del ejemplo de iOS también funciona en Android con Intent.ACTION_VIEW.

Codificación 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("=")

Opciones

Las mismas opciones funcionan en los enlaces, la intención de Android y la acción de Atajos, excepto que las respuestas de llamada solo están disponibles en los enlaces y la intención.

Opción Descripción
data El JSON del temporizador, codificado en base64url. El relleno es opcional. Hasta 64 KB de JSON.
json El JSON del temporizador como texto sin formato. Solo para la intención de Android y Atajos; los enlaces usan data.
url Un enlace https que devuelve el JSON del temporizador. Hasta 1 MB, descargado en un plazo de 10 segundos.
start 1 o true inicia el temporizador y lo muestra en marcha. Sin esto, Temporizador Flex abre la configuración del temporizador para que el usuario pueda ajustarlo e iniciarlo.
source El nombre de tu aplicación. Temporizador Flex lo muestra al pedir al usuario que permita tu aplicación. Usa el mismo nombre cada vez.
replace 1 o true cierra los temporizadores que tu source creó anteriormente antes de crear este.
x-success Un enlace que Temporizador Flex abre después de crear el temporizador, con timerId añadido a su consulta.
x-error Un enlace que Temporizador Flex abre si no puede crear el temporizador, con errorMessage añadido a su consulta.

Proporciona exactamente uno de data, json o url. Los temporizadores son pequeños, incluso unos pocos KB para un entrenamiento largo de varios segmentos, por lo que data sirve para casi todos los casos. Usa url cuando el JSON sea muy grande o tu servidor ya lo aloje.

El formato del temporizador (versión 1)

Campo Tipo Descripción
version entero 1. Opcional, pero recomendado.
name cadena Opcional. El nombre del entrenamiento. Un temporizador de un solo segmento sin name de segmento usa este.
description cadena Opcional. Una breve descripción del entrenamiento.
segments matriz Requerido. De 1 a 50 segmentos, ejecutados en orden. Dos o más forman un temporizador de varios segmentos.

Segmentos

Cada segmento tiene un timerMode y los campos de ese modo.

  • Unidades: todos los tiempos son segundos enteros.
  • Valores predeterminados: un campo que omitas toma el valor predeterminado mostrado.
  • Los campos desconocidos se ignoran.
timerMode Úsalo para Campos: predeterminado, luego rango permitido
CountUp Para el tiempo timeCap: 0 (sin límite), 0 a 86400
CountDown AMRAP o cualquier duración fija duration: 600, 1 a 86400
Rounds Series iguales, con descanso igual opcional roundDuration: 60, 1 a 86400. numberOfRounds: 5, 1 a 1000. restBetweenRounds: 0, 0 a 86400
Tabata Trabajo y descanso repetidos, opcionalmente en series workDuration: 20. restDuration: 10 (se permite 0). roundsPerTabata: 8. numberOfTabatas: 1. restBetweenTabatas: 0
ContinuousCue EMOM: una indicación en cada intervalo cueInterval: 60. totalDuration: 600
MixedInterval Cualquier secuencia de períodos de trabajo y descanso intervals (requerido, ver abajo). numberOfRounds: 1, veces que se repite la secuencia. restBetweenRounds: 0
RestDriven Series de cualquier duración, cada una seguida de descanso (por ejemplo, levantamiento de pesas) numberOfSets: 5, 1 a 1000. restType: fixed (predeterminado) o ratio. Con fixed: fixedRestDuration, 120. Con ratio: workRatio y restRatio, 1 de cada uno, 1 a 100
Warmup Calentamiento timeCap: 600 (0 para sin límite)
Cooldown Enfriamiento timeCap: 600 (0 para sin límite)

A menos que se muestre un rango, las duraciones permiten 1 a 86400 y las cantidades 1 a 1000.

Cada intervalo de MixedInterval es un objeto:

  • duration: requerido.
  • type: work (predeterminado) o rest.
  • name: opcional.

Un segmento puede tener de 1 a 200 intervalos.

Campos para cada segmento

Campo Descripción
name Se muestra en el temporizador. Por defecto usa un nombre para el modo, como "Tabata" o "AMRAP".
description Una breve descripción.
details El texto completo del entrenamiento para el atleta. Se mantienen los saltos de línea.
direction true cuenta hacia arriba, false cuenta hacia abajo. CountUp, ContinuousCue, RestDriven, Warmup y Cooldown cuentan hacia arriba por defecto; CountDown, Rounds, Tabata y MixedInterval cuentan hacia abajo.
roundNames, intervalNames Un nombre por serie o intervalo, como el ejercicio. Usa null para los que no tienen nombre.
roundNamesUseSame, intervalNamesUseSame true usa el primer nombre para cada serie o intervalo.
roundIntervalNamePresentation Cómo se presentan los nombres: none (se muestran como títulos), cue (en pantalla), speech (hablado), o cueAndSpeech.

Las advertencias, sonidos y preferencias similares provienen de la propia configuración de Temporizador Flex del usuario.

Ejemplos

Un AMRAP de 20 minutos:

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

Un circuito, tres veces:

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

Una sesión completa como un solo temporizador de varios segmentos:

{
  "version": 1,
  "name": "WOD del sábado",
  "segments": [
    { "timerMode": "Warmup", "timeCap": 600 },
    { "timerMode": "Tabata", "name": "Burpees Tabata" },
    { "timerMode": "Cooldown", "timeCap": 300 }
  ]
}

Lo que ve el usuario

  • Sin start: Temporizador Flex abre la configuración del nuevo temporizador, listo para que el usuario lo ajuste e inicie.
  • Con start, la primera vez que tu aplicación envía un temporizador: Temporizador Flex le pregunta al usuario si tu aplicación puede iniciar temporizadores.
  • Permitir: este temporizador y los posteriores de tu source se inician de inmediato.
  • Solo esta vez: este temporizador se inicia, y Temporizador Flex preguntará de nuevo la próxima vez.
  • No permitir: el temporizador se abre en su configuración sin iniciarse.
  • Con start pero sin source: Temporizador Flex pregunta cada vez.
  • Cambiar de opinión: los usuarios pueden eliminar tu aplicación en Configuración > Aplicaciones conectadas. Temporizador Flex volverá a preguntar la próxima vez que tu aplicación inicie un temporizador.
  • Cuando Temporizador Flex no se está ejecutando: tu temporizador lo abre.

Errores

Si Flex Timer no puede crear el temporizador, se lo indica al usuario y abre tu enlace x-error con un errorMessage que especifica el problema. Por ejemplo:

  • El temporizador no es un JSON válido.
  • segments es obligatorio: una lista de uno o más segmentos del temporizador.
  • segments[0].timerMode "Sprint" no es compatible. Usa uno de CountUp, CountDown, Rounds, Tabata, ContinuousCue, MixedInterval, RestDriven, Warmup, Cooldown.
  • segments[1].workDuration debe ser un número entero del 1 al 86400.
  • segments[0].intervals[2].type debe ser "work" o "rest".
  • Este temporizador usa la versión 2 del formato, pero esta versión de Flex Timer lee la versión 1. Actualiza Flex Timer para abrirlo.
  • El temporizador es más grande que 64 KB. Aloja el JSON y pasa la url en su lugar.
  • url debe ser un enlace https.
  • Falló la descarga del temporizador desde url con el estado HTTP 404.

Para detectar estos errores antes de enviarlos, valida tu JSON contra flextimer-timer.schema.json.

Usarlo desde un agente de IA

  1. Dale al modelo el JSON Schema, o las tablas de formato de arriba, y pide un único objeto JSON que coincida con él. Pide name y details también, para que el atleta vea el entrenamiento en el temporizador.
  2. Valida el resultado contra el esquema.
  3. Envíalo con la acción de Atajos (iOS), la intención (Android), o un enlace flextimer://timer.

Versionado

Esta es la versión 1 del formato.

  • Adiciones: se pueden agregar nuevos campos opcionales a la versión 1. Las versiones de Flex Timer que no los conocen los ignoran .
  • Cambios disruptivos: un cambio que las versiones anteriores no podían leer correctamente recibe un nuevo número de version.

JSON Schema

Valida tu JSON del temporizador contra este esquema (JSON Schema draft 2020-12) antes de enviarlo, o dáselo a un modelo de IA para que produzca temporizadores válidos.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gymnext.com/flextimer/flextimer-timer.schema.json",
  "title": "Temporizador de Flex Timer",
  "description": "Un temporizador que otra aplicación o un agente de IA envía a Flex Timer (versión 1 del formato). Ver timer-integration.md. Todas las duraciones son segundos enteros.",
  "type": "object",
  "required": ["segments"],
  "properties": {
    "version": {
      "description": "Versión del formato. Opcional; por defecto es 1. Flex Timer rechaza versiones más nuevas de las que entiende.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1
    },
    "name": {
      "description": "Nombre del entrenamiento. Para un temporizador de un solo segmento sin su propio nombre, este se convierte en el nombre del temporizador.",
      "type": "string"
    },
    "description": {
      "description": "Breve descripción del entrenamiento.",
      "type": "string"
    },
    "segments": {
      "description": "Uno o más segmentos del temporizador, ejecutados en orden. Más de uno crea un temporizador multiesegmento.",
      "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 nombre por ronda, intervalo o serie; null para sin nombre.",
      "type": "array",
      "items": { "type": ["string", "null"] }
    },
    "common": {
      "type": "object",
      "properties": {
        "name": { "description": "Nombre del segmento, mostrado en el temporizador. Por defecto según el modo (por ejemplo \"Tabata\").", "type": "string" },
        "description": { "description": "Breve descripción del segmento.", "type": "string" },
        "details": { "description": "Texto completo del entrenamiento para el atleta; se mantienen los saltos de línea.", "type": "string" },
        "direction": {
          "description": "true cuenta hacia arriba, false cuenta hacia abajo. Por defecto según el modo: CountUp, ContinuousCue, RestDriven, Warmup y Cooldown cuentan hacia arriba; CountDown, Rounds, Tabata y MixedInterval cuentan hacia abajo.",
          "type": "boolean"
        },
        "roundNames": { "$ref": "#/$defs/names" },
        "intervalNames": { "$ref": "#/$defs/names" },
        "roundNamesUseSame": { "description": "Usar el primer nombre de ronda para cada ronda.", "type": "boolean" },
        "intervalNamesUseSame": { "description": "Usar el primer nombre de intervalo para cada intervalo.", "type": "boolean" },
        "roundIntervalNamePresentation": {
          "description": "Cómo se presentan los nombres: none (solo títulos), cue (en pantalla), speech (hablado), o cueAndSpeech.",
          "enum": ["none", "cue", "speech", "cueAndSpeech"]
        }
      }
    },
    "segment": {
      "type": "object",
      "required": ["timerMode"],
      "allOf": [{ "$ref": "#/$defs/common" }],
      "oneOf": [
        {
          "title": "CountUp (Por tiempo)",
          "properties": {
            "timerMode": { "const": "CountUp" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "Límite de tiempo; 0 para ninguno. Por defecto 0." }
          }
        },
        {
          "title": "CountDown (AMRAP)",
          "properties": {
            "timerMode": { "const": "CountDown" },
            "duration": { "$ref": "#/$defs/seconds", "description": "Duración. Por defecto 600." }
          }
        },
        {
          "title": "Rounds (rondas iguales, descanso igual opcional)",
          "properties": {
            "timerMode": { "const": "Rounds" },
            "roundDuration": { "$ref": "#/$defs/seconds", "description": "Por defecto 60." },
            "numberOfRounds": { "$ref": "#/$defs/count", "description": "Por defecto 5." },
            "restBetweenRounds": { "$ref": "#/$defs/secondsOrZero", "description": "Por defecto 0." }
          }
        },
        {
          "title": "Tabata (trabajo / descanso repetido, opcionalmente en series)",
          "properties": {
            "timerMode": { "const": "Tabata" },
            "workDuration": { "$ref": "#/$defs/seconds", "description": "Por defecto 20." },
            "restDuration": { "$ref": "#/$defs/secondsOrZero", "description": "Por defecto 10." },
            "roundsPerTabata": { "$ref": "#/$defs/count", "description": "Por defecto 8." },
            "numberOfTabatas": { "$ref": "#/$defs/count", "description": "Por defecto 1." },
            "restBetweenTabatas": { "$ref": "#/$defs/secondsOrZero", "description": "Por defecto 0." }
          }
        },
        {
          "title": "ContinuousCue (EMOM: una señal cada intervalo)",
          "properties": {
            "timerMode": { "const": "ContinuousCue" },
            "cueInterval": { "$ref": "#/$defs/seconds", "description": "Segundos entre señales. Por defecto 60." },
            "totalDuration": { "$ref": "#/$defs/seconds", "description": "Duración total. Por defecto 600." }
          }
        },
        {
          "title": "MixedInterval (cualquier secuencia de trabajo y descanso)",
          "required": ["intervals"],
          "properties": {
            "timerMode": { "const": "MixedInterval" },
            "intervals": {
              "type": "array",
              "minItems": 1,
              "maxItems": 200,
              "items": {
                "type": "object",
                "required": ["duration"],
                "properties": {
                  "type": { "enum": ["work", "rest"], "description": "Por defecto trabajo." },
                  "duration": { "$ref": "#/$defs/seconds" },
                  "name": { "type": ["string", "null"], "description": "Por ejemplo, el ejercicio." }
                }
              }
            },
            "numberOfRounds": { "$ref": "#/$defs/count", "description": "Veces que se repite la secuencia. Por defecto 1." },
            "restBetweenRounds": { "$ref": "#/$defs/secondsOrZero", "description": "Por defecto 0." }
          }
        },
        {
          "title": "RestDriven (series de cualquier duración, cada una seguida de descanso)",
          "properties": {
            "timerMode": { "const": "RestDriven" },
            "numberOfSets": { "$ref": "#/$defs/count", "description": "Por defecto 5." },
            "restType": { "enum": ["fixed", "ratio"], "description": "Por defecto fijo." },
            "fixedRestDuration": { "$ref": "#/$defs/secondsOrZero", "description": "Descanso después de cada serie cuando restType es fijo. Por defecto 120." },
            "workRatio": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Con restRatio, el descanso como una proporción del tiempo de la serie cuando restType es ratio. Por defecto 1." },
            "restRatio": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Por defecto 1." }
          }
        },
        {
          "title": "Warmup",
          "properties": {
            "timerMode": { "const": "Warmup" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "0 para ninguno. Por defecto 600." }
          }
        },
        {
          "title": "Cooldown",
          "properties": {
            "timerMode": { "const": "Cooldown" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "0 para ninguno. Por defecto 600." }
          }
        }
      ]
    }
  }
}