Flex Timer di GymNext — Guida per sviluppatori
Guida per sviluppatori

Integrazione di Flex Timer: creare timer dalla propria app

Disponibile da Flex Timer 6.3.0 in poi.

La tua app o il tuo agente IA può inviare un timer a Flex Timer su iPhone, iPad e Android. Flex Timer lo apre pronto a essere modificato e avviato, oppure lo avvia immediatamente. In entrambi i casi, viene visualizzato sui display Flex Timer collegati dell'utente.

Ad esempio, un'app di allenamento che conosce già l'esercizio in corso può avviare il conto alla rovescia su Flex Timer su un display montato a parete in palestra, senza che l'utente debba configurare il timer in Flex Timer.

  • Un formato per ogni piattaforma: un timer è un piccolo oggetto JSON, descritto di seguito e nello schema JSON flextimer-timer.schema.json.
  • Tre modi per inviarlo: un link flextimer://timer (iOS e Android), un intent Android o l'azione Crea timer da JSON dell'app Scorciatoie di iOS.
  • L'utente mantiene il controllo: prima che la tua app possa avviare timer, Flex Timer chiede all'utente una sola volta il permesso.

Requisiti

  • Flex Timer 6.3.0 o successivo su iOS 15+ o Android. L'azione di Scorciatoie richiede iOS 16+.
  • Disponibile a tutti gli utenti di Flex Timer. Non è necessario alcun account o chiave API da parte tua.
  • L'utente deve aver effettuato l'accesso a Flex Timer (o utilizzarlo come ospite).

Guida rapida

Un'app di allenamento della forza avvia un timer per lo squat con bilanciere: 5 serie, con 2 minuti di riposo dopo ciascuna.

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

Codifica il JSON in base64url e apri questo link:

flextimer://timer?data=<JSON in base64url>&start=1&source=La%20mia%20app%20di%20palestra&replace=1

La prima volta, Flex Timer chiede all'utente se La mia app di palestra può avviare timer. Una volta concesso il permesso, i tuoi timer si avviano immediatamente. replace=1 chiude il timer avviato in precedenza dalla tua app, in modo che passare all'esercizio successivo non lasci il vecchio timer aperto.

Inviare un timer

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: "La mia app di palestra"),
    URLQueryItem(name: "replace", value: "1"),
    URLQueryItem(name: "x-success", value: "mygymapp://flextimer-done"),
]
UIApplication.shared.open(link.url!)

Per verificare che Flex Timer sia installato con canOpenURL(_:), aggiungi flextimer a LSApplicationQueriesSchemes nel tuo Info.plist.

iOS: Scorciatoie

L'app Scorciatoie include un'azione Crea timer da JSON con questi campi:

  • JSON del timer: il timer.
  • Avvia immediatamente: come start.
  • Nome app: come source.
  • Sostituisci i timer precedenti di questa app: come replace.

Utilizzala nelle automazioni o da Siri, Apple Intelligence e dagli agenti IA che eseguono scorciatoie. L'azione termina dopo che il timer è stato creato, quindi l'azione successiva in una scorciatoia viene eseguita in seguito.

Android: inviare un intent

val intent = Intent("com.gymnext.timer.action.CREATE_TIMER").apply {
    setPackage("com.gymnext.timer")
    putExtra("json", timerJson)
    putExtra("start", true)
    putExtra("source", "La mia app di palestra")
    putExtra("replace", true)
}
startActivity(intent)
  • Extra: json, data o url, più source, x-success e x-error. start e replace possono essere booleani o le stringhe "1" / "true".
  • Verificare che Flex Timer sia installato: su Android 11 e versioni successive, aggiungi prima <package android:name="com.gymnext.timer" /> a <queries> nel tuo manifest.

Il link flextimer://timer?... dell'esempio iOS funziona anche su Android con Intent.ACTION_VIEW.

Codifica 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("=")

Opzioni

Le stesse opzioni funzionano nei link, nell'intent Android e nell'azione di Scorciatoie, tranne che i callback sono disponibili solo nei link e nell'intent.

Opzione Descrizione
data Il JSON del timer, codificato in base64url. Il padding è facoltativo. Fino a 64 KB di JSON.
json Il JSON del timer in testo semplice. Solo per intent Android e Scorciatoie; i link utilizzano data.
url Un link https che restituisce il JSON del timer. Fino a 1 MB, scaricato entro 10 secondi.
start 1 o true avvia il timer e lo mostra in esecuzione. Senza questo, Flex Timer apre le impostazioni del timer in modo che l'utente possa modificarlo e avviarlo.
source Il nome della tua app. Flex Timer lo mostra quando chiede all'utente il permesso per la tua app. Usa sempre lo stesso nome.
replace 1 o true chiude i timer creati in precedenza dalla tua source prima di crearne uno nuovo.
x-success Un link che Flex Timer apre dopo aver creato il timer, con timerId aggiunto alla query.
x-error Un link che Flex Timer apre se non riesce a creare il timer, con errorMessage aggiunto alla query.

Fornisci esattamente uno di data, json o url. I timer sono piccoli, pochi KB anche per un allenamento lungo e multi-segmento, quindi data è adatto a quasi tutti i casi. Usa url quando il JSON è molto grande o il tuo server lo ospita già.

Il formato del timer (versione 1)

Campo Tipo Descrizione
version intero 1. Facoltativo, ma consigliato.
name stringa Facoltativo. Il nome dell'allenamento. Un timer a segmento singolo senza name del segmento utilizza questo.
description stringa Facoltativo. Una breve descrizione dell'allenamento.
segments array Obbligatorio. Da 1 a 50 segmenti, eseguiti in ordine. Due o più segmenti formano un timer multi-segmento.

Segmenti

Ogni segmento ha un timerMode e i campi di quella modalità.

  • Unità: tutti i tempi sono in secondi interi.
  • Valori predefiniti: un campo omesso assume il valore predefinito mostrato.
  • I campi sconosciuti vengono ignorati.
timerMode Utilizzo Campi: predefinito, poi intervallo consentito
CountUp Per il tempo timeCap: 0 (senza limite), da 0 a 86400
CountDown AMRAP o qualsiasi durata fissa duration: 600, da 1 a 86400
Rounds Serie uguali, con riposo uguale facoltativo roundDuration: 60, da 1 a 86400. numberOfRounds: 5, da 1 a 1000. restBetweenRounds: 0, da 0 a 86400
Tabata Lavoro e riposo ripetuti, facoltativamente in serie workDuration: 20. restDuration: 10 (0 consentito). roundsPerTabata: 8. numberOfTabatas: 1. restBetweenTabatas: 0
ContinuousCue EMOM: un segnale a ogni intervallo cueInterval: 60. totalDuration: 600
MixedInterval Qualsiasi sequenza di periodi di lavoro e riposo intervals (obbligatorio, vedi sotto). numberOfRounds: 1, numero di volte in cui si ripete la sequenza. restBetweenRounds: 0
RestDriven Serie di qualsiasi durata, ciascuna seguita da un riposo (ad esempio per il sollevamento pesi) numberOfSets: 5, da 1 a 1000. restType: fixed (predefinito) o ratio. Con fixed: fixedRestDuration, 120. Con ratio: workRatio e restRatio, ciascuno da 1 a 100
Warmup Riscaldamento timeCap: 600 (0 per nessun limite)
Cooldown Defaticamento timeCap: 600 (0 per nessun limite)

A meno che non venga mostrato un intervallo, le durate consentono da 1 a 86400 e i conteggi da 1 a 1000.

Ogni intervallo MixedInterval è un oggetto:

  • duration: obbligatorio.
  • type: work (predefinito) o rest.
  • name: facoltativo.

Un segmento può avere da 1 a 200 intervalli.

Campi per ogni segmento

Campo Descrizione
name Mostrato sul timer. Predefinito è un nome per la modalità, come "Tabata" o "AMRAP".
description Una breve descrizione.
details Il testo completo dell'allenamento per l'atleta. Gli a capo vengono mantenuti.
direction true conta in avanti, false conta a ritroso. CountUp, ContinuousCue, RestDriven, Warmup e Cooldown contano in avanti per impostazione predefinita; CountDown, Rounds, Tabata e MixedInterval contano a ritroso.
roundNames, intervalNames Un nome per ogni serie o intervallo, come l'esercizio. Usa null per quelli senza nome.
roundNamesUseSame, intervalNamesUseSame true utilizza il primo nome per ogni serie o intervallo.
roundIntervalNamePresentation Come vengono presentati i nomi: none (mostrati come titoli), cue (a schermo), speech (parlato), o cueAndSpeech.

Gli avvisi, i suoni e le preferenze simili provengono dalle impostazioni Flex Timer dell'utente.

Esempi

Un AMRAP di 20 minuti:

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

Un circuito, tre volte:

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

Un'intera sessione come un unico timer multi-segmento:

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

Cosa vede l'utente

  • Senza start: Flex Timer apre le impostazioni del nuovo timer, pronto per essere modificato e avviato dall'utente.
  • Con start, la prima volta che la tua app invia un timer: Flex Timer chiede all'utente se la tua app può avviare timer.
  • Consenti: questo timer e quelli successivi dalla tua source si avviano immediatamente.
  • Solo questa volta: questo timer si avvia, e Flex Timer chiederà di nuovo la prossima volta.
  • Non consentere: il timer si apre nelle impostazioni senza avviarsi.
  • Con start ma senza source: Flex Timer chiede ogni volta.
  • Cambiare idea: gli utenti possono rimuovere la tua app in Impostazioni > App collegate. Flex Timer chiederà di nuovo la prossima volta che la tua app avvia un timer.
  • Quando Flex Timer non è in esecuzione: il tuo timer lo apre.

Errori

Se Flex Timer non riesce a creare il timer, avvisa l'utente e apre il tuo link x-error con un errorMessage che indica il problema. Ad esempio:

  • Il timer non è un JSON valido.
  • segments è obbligatorio: un elenco di uno o più segmenti del timer.
  • segments[0].timerMode "Sprint" non è supportato. Usa uno di CountUp, CountDown, Rounds, Tabata, ContinuousCue, MixedInterval, RestDriven, Warmup, Cooldown.
  • segments[1].workDuration deve essere un numero intero da 1 a 86400.
  • segments[0].intervals[2].type deve essere "work" o "rest".
  • Questo timer utilizza la versione 2 del formato, ma questa versione di Flex Timer legge la versione 1. Aggiorna Flex Timer per aprirlo.
  • Il timer è più grande di 64 KB. Ospita il JSON e passa l'url invece.
  • url deve essere un link https.
  • Il download del timer dall'url è fallito con stato HTTP 404.

Per intercettare questi errori prima dell'invio, convalida il tuo JSON rispetto a flextimer-timer.schema.json.

Utilizzarlo da un agente AI

  1. Fornisci al modello lo schema JSON o le tabelle del formato sopra e chiedi un singolo oggetto JSON che lo rispetti. Chiedi anche name e details, in modo che l'atleta veda l'allenamento sul timer.
  2. Convalida il risultato rispetto allo schema.
  3. Inviarlo con l'azione Scorciatoie (iOS), l'intent (Android) o un link flextimer://timer.

Versionamento

Questa è la versione 1 del formato.

  • Aggiunte: alla versione 1 possono essere aggiunti nuovi campi opzionali. Le versioni di Flex Timer che non li conoscono li ignorano .
  • Modifiche bloccanti: una modifica che le versioni precedenti non riuscivano a leggere correttamente riceve un nuovo numero di version.

Schema JSON

Convalida il JSON del tuo timer rispetto a questo schema (JSON Schema draft 2020-12) prima di inviarlo, oppure forniscilo a un modello AI in modo che produca timer validi.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gymnext.com/flextimer/flextimer-timer.schema.json",
  "title": "Timer di Flex Timer",
  "description": "Un timer che un'altra app o un agente AI invia a Flex Timer (versione del formato 1). Vedi timer-integration.md. Tutte le durate sono in secondi interi.",
  "type": "object",
  "required": ["segments"],
  "properties": {
    "version": {
      "description": "Versione del formato. Opzionale; predefinito 1. Flex Timer rifiuta le versioni più recenti di quelle che comprende.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1
    },
    "name": {
      "description": "Nome dell'allenamento. Per un timer a segmento singolo senza nome proprio, questo diventa il nome del timer.",
      "type": "string"
    },
    "description": {
      "description": "Breve descrizione dell'allenamento.",
      "type": "string"
    },
    "segments": {
      "description": "Uno o più segmenti del timer, eseguiti in ordine. Più di uno crea un timer multi-segmento.",
      "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 nome per round, intervallo o serie; null per quelli senza nome.",
      "type": "array",
      "items": { "type": ["string", "null"] }
    },
    "common": {
      "type": "object",
      "properties": {
        "name": { "description": "Nome del segmento, mostrato sul timer. Predefinito in base alla modalità (ad esempio \"Tabata\").", "type": "string" },
        "description": { "description": "Breve descrizione del segmento.", "type": "string" },
        "details": { "description": "Testo completo dell'allenamento per l'atleta; gli a capo vengono mantenuti.", "type": "string" },
        "direction": {
          "description": "true conta in avanti, false conta all'indietro. Predefinito in base alla modalità: CountUp, ContinuousCue, RestDriven, Warmup e Cooldown contano in avanti; CountDown, Rounds, Tabata e MixedInterval contano all'indietro.",
          "type": "boolean"
        },
        "roundNames": { "$ref": "#/$defs/names" },
        "intervalNames": { "$ref": "#/$defs/names" },
        "roundNamesUseSame": { "description": "Usa il nome del primo round per ogni round.", "type": "boolean" },
        "intervalNamesUseSame": { "description": "Usa il nome del primo intervallo per ogni intervallo.", "type": "boolean" },
        "roundIntervalNamePresentation": {
          "description": "Come vengono presentati i nomi: none (solo titoli), cue (a schermo), speech (vocale), o cueAndSpeech.",
          "enum": ["none", "cue", "speech", "cueAndSpeech"]
        }
      }
    },
    "segment": {
      "type": "object",
      "required": ["timerMode"],
      "allOf": [{ "$ref": "#/$defs/common" }],
      "oneOf": [
        {
          "title": "CountUp (Per tempo)",
          "properties": {
            "timerMode": { "const": "CountUp" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "Limite di tempo; 0 per nessuno. Predefinito 0." }
          }
        },
        {
          "title": "CountDown (AMRAP)",
          "properties": {
            "timerMode": { "const": "CountDown" },
            "duration": { "$ref": "#/$defs/seconds", "description": "Durata. Predefinito 600." }
          }
        },
        {
          "title": "Rounds (round uguali, riposo uguale opzionale)",
          "properties": {
            "timerMode": { "const": "Rounds" },
            "roundDuration": { "$ref": "#/$defs/seconds", "description": "Predefinito 60." },
            "numberOfRounds": { "$ref": "#/$defs/count", "description": "Predefinito 5." },
            "restBetweenRounds": { "$ref": "#/$defs/secondsOrZero", "description": "Predefinito 0." }
          }
        },
        {
          "title": "Tabata (lavoro / riposo ripetuto, opzionalmente in serie)",
          "properties": {
            "timerMode": { "const": "Tabata" },
            "workDuration": { "$ref": "#/$defs/seconds", "description": "Predefinito 20." },
            "restDuration": { "$ref": "#/$defs/secondsOrZero", "description": "Predefinito 10." },
            "roundsPerTabata": { "$ref": "#/$defs/count", "description": "Predefinito 8." },
            "numberOfTabatas": { "$ref": "#/$defs/count", "description": "Predefinito 1." },
            "restBetweenTabatas": { "$ref": "#/$defs/secondsOrZero", "description": "Predefinito 0." }
          }
        },
        {
          "title": "ContinuousCue (EMOM: un segnale ogni intervallo)",
          "properties": {
            "timerMode": { "const": "ContinuousCue" },
            "cueInterval": { "$ref": "#/$defs/seconds", "description": "Secondi tra un segnale e l'altro. Predefinito 60." },
            "totalDuration": { "$ref": "#/$defs/seconds", "description": "Durata totale. Predefinito 600." }
          }
        },
        {
          "title": "MixedInterval (qualsiasi sequenza di lavoro e riposo)",
          "required": ["intervals"],
          "properties": {
            "timerMode": { "const": "MixedInterval" },
            "intervals": {
              "type": "array",
              "minItems": 1,
              "maxItems": 200,
              "items": {
                "type": "object",
                "required": ["duration"],
                "properties": {
                  "type": { "enum": ["work", "rest"], "description": "Predefinito lavoro." },
                  "duration": { "$ref": "#/$defs/seconds" },
                  "name": { "type": ["string", "null"], "description": "Ad esempio l'esercizio." }
                }
              }
            },
            "numberOfRounds": { "$ref": "#/$defs/count", "description": "Numero di volte che si ripete la sequenza. Predefinito 1." },
            "restBetweenRounds": { "$ref": "#/$defs/secondsOrZero", "description": "Predefinito 0." }
          }
        },
        {
          "title": "RestDriven (serie di qualsiasi durata, ciascuna seguita da riposo)",
          "properties": {
            "timerMode": { "const": "RestDriven" },
            "numberOfSets": { "$ref": "#/$defs/count", "description": "Predefinito 5." },
            "restType": { "enum": ["fixed", "ratio"], "description": "Predefinito fixed." },
            "fixedRestDuration": { "$ref": "#/$defs/secondsOrZero", "description": "Riposo dopo ogni serie quando restType è fixed. Predefinito 120." },
            "workRatio": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Con restRatio, il riposo come rapporto del tempo della serie quando restType è ratio. Predefinito 1." },
            "restRatio": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Predefinito 1." }
          }
        },
        {
          "title": "Warmup",
          "properties": {
            "timerMode": { "const": "Warmup" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "0 per nessuno. Predefinito 600." }
          }
        },
        {
          "title": "Cooldown",
          "properties": {
            "timerMode": { "const": "Cooldown" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "0 per nessuno. Predefinito 600." }
          }
        }
      ]
    }
  }
}