Integrazione di Flex Timer: creare timer dalla propria app
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
iOS: aprire un link
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,dataourl, piùsource,x-successex-error.startereplacepossono 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.
Android: aprire un link
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) orest. -
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
sourcesi 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
startma senzasource: 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
- Fornisci al modello lo schema JSON o le tabelle del formato sopra e chiedi un singolo oggetto JSON che lo rispetti.
Chiedi anche
nameedetails, in modo che l'atleta veda l'allenamento sul timer. - Convalida il risultato rispetto allo schema.
- 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." }
}
}
]
}
}
}