GymNext Flex Timer — Entwicklerleitfaden
Entwicklerleitfaden

Flex-Timer-Integration: Timer aus Ihrer App erstellen

Verfügbar ab Flex Timer 6.3.0.

Ihre App oder Ihr KI-Agent kann einen Timer an Flex Timer auf iPhone, iPad und Android senden. Flex Timer öffnet ihn entweder einsatzbereit zum Anpassen und Starten oder startet ihn sofort. In beiden Fällen wird er auf den verbundenen Flex-Timer-Displays des Benutzers angezeigt.

Beispielsweise kann eine Trainings-App, die die aktuelle Übung bereits kennt, den Countdown auf dem Flex Timer an der Fitnessstudio-Wand starten, ohne dass der Benutzer den Timer in Flex Timer einrichten muss.

  • Ein Format für alle Plattformen: Ein Timer ist ein kleines JSON-Objekt, das unten und im JSON-Schema flextimer-timer.schema.json beschrieben wird.
  • Drei Möglichkeiten zum Senden: Ein flextimer://timer-Link (iOS und Android), ein Android-Intent oder die Aktion Timer erstellen aus JSON in der iOS-App Kurzbefehle.
  • Der Benutzer behält die Kontrolle: Bevor Ihre App Timer starten kann, fragt Flex Timer den Benutzer einmal, ob dies erlaubt werden soll.

Anforderungen

  • Flex Timer 6.3.0 oder neuer auf iOS 15+ oder Android. Die Kurzbefehle-Aktion erfordert iOS 16+.
  • Für jeden Flex-Timer-Benutzer verfügbar. Auf Ihrer Seite werden weder ein Konto noch ein API-Schlüssel benötigt.
  • Der Benutzer muss bei Flex Timer angemeldet sein (oder die App als Gast nutzen).

Schnellstart

Eine Krafttrainings-App startet einen Timer für Kniebeugen mit Langhantel: 5 Sätze mit 2 Minuten Pause dazwischen.

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

Kodieren Sie das JSON als base64url und öffnen Sie diesen Link:

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

Beim ersten Mal fragt Flex Timer den Benutzer, ob My Gym App Timer starten darf. Sobald der Benutzer dies erlaubt, starten Ihre Timer sofort. replace=1 schließt den Timer, den Ihre App zuvor gestartet hat, sodass beim Wechsel zur nächsten Übung der alte Timer nicht offen bleibt.

Timer senden

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

Um zu prüfen, ob Flex Timer mit canOpenURL(_:) installiert ist, fügen Sie flextimer in Ihrem Info.plist zu LSApplicationQueriesSchemes hinzu.

iOS: Kurzbefehle

Die App Kurzbefehle enthält die Aktion Timer aus JSON erstellen mit folgenden Feldern:

  • Timer-JSON: der Timer.
  • Sofort starten: entspricht start.
  • App-Name: entspricht source.
  • Frühere Timer dieser App ersetzen: entspricht replace.

Verwenden Sie sie in Automatisierungen oder mit Siri, Apple Intelligence und KI-Agenten, die Kurzbefehle ausführen. Die Aktion wird abgeschlossen nachdem der Timer erstellt wurde, sodass danach die nächste Aktion in einem Kurzbefehl ausgeführt wird.

Android: Intent senden

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 oder url sowie source, x-success und x-error. start und replace können Booleans oder die Zeichenfolgen "1" / "true" sein.
  • Prüfen, ob Flex Timer installiert ist: Auf Android 11 und neuer fügen Sie zuerst <package android:name="com.gymnext.timer" /> zu <queries> in Ihrer Manifestdatei hinzu.

Der flextimer://timer?...-Link aus dem iOS-Beispiel funktioniert auch auf Android mit Intent.ACTION_VIEW.

base64url-Kodierung

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

Optionen

Die gleichen Optionen funktionieren in Links, im Android-Intent und in der Kurzbefehle-Aktion, außer dass die Callbacks nur in Links und im Intent verfügbar sind.

Option Beschreibung
data Das Timer-JSON, base64url-kodiert. Padding ist optional. Bis zu 64 KB JSON.
json Das Timer-JSON als reiner Text. Nur für Android-Intents und Kurzbefehle; Links verwenden data.
url Ein https-Link, der das Timer-JSON zurückgibt. Bis zu 1 MB, heruntergeladen innerhalb von 10 Sekunden.
start 1 oder true startet den Timer und zeigt ihn im laufenden Zustand an. Ohne diesen Wert öffnet Flex Timer die Timer-Einstellungen, damit der Benutzer ihn anpassen und starten kann.
source Der Name Ihrer App. Flex Timer zeigt ihn an, wenn der Benutzer gefragt wird, ob Ihre App erlaubt werden soll. Verwenden Sie jedes Mal den gleichen Namen.
replace 1 oder true schließt Timer, die Ihre source zuvor erstellt hat, bevor dieser Timer erstellt wird.
x-success Ein Link, den Flex Timer nach dem Erstellen des Timers öffnet, wobei timerId an dessen Query angehängt wird.
x-error Ein Link, den Flex Timer öffnet, wenn er den Timer nicht erstellen kann, wobei errorMessage an dessen Query angehängt wird.

Geben Sie genau eines von data, json oder url an. Timer sind klein, selbst für ein langes Multi-Segment-Workout nur wenige KB, daher data eignet sich für fast jeden Fall. Verwenden Sie url, wenn das JSON sehr groß ist oder Ihr Server es bereits bereitstellt.

Das Timerformat (Version 1)

Feld Typ Beschreibung
version Ganzzahl 1. Optional, aber empfohlen.
name Zeichenfolge Optional. Der Name des Workouts. Ein Ein-Segment-Timer ohne Segment-name verwendet diesen.
description Zeichenfolge Optional. Eine kurze Beschreibung des Workouts.
segments Array Erforderlich. 1 bis 50 Segmente, die nacheinander ausgeführt werden. Zwei oder mehr Segmente bilden einen Multi-Segment-Timer.

Segmente

Jedes Segment hat einen timerMode und die Felder dieses Modus.

  • Einheiten: Alle Zeiten sind ganze Sekunden.
  • Standardwerte: Ein Feld, das Sie weglassen, nimmt den angezeigten Standardwert an.
  • Unbekannte Felder werden ignoriert.
timerMode Verwendung für Felder: Standard, dann erlaubter Bereich
CountUp Für die Zeit timeCap: 0 (keine Begrenzung), 0 bis 86400
CountDown AMRAP oder jede beliebige feste Länge duration: 600, 1 bis 86400
Rounds Gleiche Runden, mit optionaler gleicher Pause roundDuration: 60, 1 bis 86400. numberOfRounds: 5, 1 bis 1000. restBetweenRounds: 0, 0 bis 86400
Tabata Arbeit und Pause wiederholt, optional in Sätzen workDuration: 20. restDuration: 10 (0 erlaubt). roundsPerTabata: 8. numberOfTabatas: 1. restBetweenTabatas: 0
ContinuousCue EMOM: ein Hinweis in jedem Intervall cueInterval: 60. totalDuration: 600
MixedInterval Beliebige Abfolge von Arbeits- und Pausenzeiten intervals (erforderlich, siehe unten). numberOfRounds: 1, Anzahl der Wiederholungen der Abfolge. restBetweenRounds: 0
RestDriven Sätze beliebiger Länge, jeweils gefolgt von einer Pause (zum Beispiel beim Gewichtheben) numberOfSets: 5, 1 bis 1000. restType: fixed (Standard) oder ratio. Bei fixed: fixedRestDuration, 120. Bei ratio: workRatio und restRatio, jeweils 1, 1 bis 100
Warmup Aufwärmen timeCap: 600 (0 für keine Begrenzung)
Cooldown Cool-down timeCap: 600 (0 für keine Begrenzung)

Sofern kein Bereich angezeigt wird, erlauben Dauern 1 bis 86400 und Zählungen 1 bis 1000.

Jedes MixedInterval-Intervall ist ein Objekt:

  • duration: erforderlich.
  • type: work (Standard) oder rest.
  • name: optional.

Ein Segment kann 1 bis 200 Intervalle haben.

Felder für jedes Segment

Feld Beschreibung
name Auf dem Timer angezeigt. Standardmäßig ein Name für den Modus, wie „Tabata“ oder „AMRAP“.
description Eine kurze Beschreibung.
details Der vollständige Workout-Text für den Athleten. Zeilenumbrüche werden beibehalten.
direction true zählt auf, false zählt ab. CountUp, ContinuousCue, RestDriven, Warmup und Cooldown zählen standardmäßig auf; CountDown, Rounds, Tabata und zählen ab.
roundNames, intervalNames Ein Name pro Runde oder Intervall, wie die Übung. Verwenden Sie null für unbenannte.
roundNamesUseSame, intervalNamesUseSame true verwendet den ersten Namen für jede Runde oder jedes Intervall.
roundIntervalNamePresentation Wie Namen angezeigt werden: none (als Titel angezeigt), cue (auf dem Bildschirm), speech (gesprochen) oder cueAndSpeech.

Warnungen, Töne und ähnliche Einstellungen stammen aus den eigenen Flex-Timer-Einstellungen des Benutzers.

Beispiele

Ein 20-minütiges AMRAP:

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

Ein Zirkeltraining, dreimal durch:

{
  "version": 1,
  "segments": [{
    "timerMode": "MixedInterval",
    "name": "Zirkeltraining",
    "intervals": [
      { "type": "work", "duration": 30, "name": "Liegestütze" },
      { "type": "rest", "duration": 10 },
      { "type": "work", "duration": 45, "name": "Kniebeugen" },
      { "type": "rest", "duration": 15 }
    ],
    "numberOfRounds": 3,
    "restBetweenRounds": 60
  }]
}

Eine ganze Trainingseinheit als ein Multi-Segment-Timer:

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

Was der Benutzer sieht

  • Ohne start: Flex Timer öffnet die Einstellungen des neuen Timers, bereit für den Benutzer zum Anpassen und Starten.
  • Mit start, beim ersten Mal, wenn Ihre App einen Timer sendet: Flex Timer fragt den Benutzer, ob Ihre App Timer starten darf.
  • Erlauben: dieser Timer und spätere Timer von Ihrer source starten sofort.
  • Nur einmal: dieser Timer startet, und Flex Timer fragt beim nächsten Mal erneut.
  • Nicht erlauben: der Timer öffnet sich in seinen Einstellungen ohne zu starten.
  • Mit start, aber ohne source: Flex Timer fragt jedes Mal.
  • Meinungsänderung: Benutzer können Ihre App unter Einstellungen > Verbundene Apps entfernen. Flex Timer fragt dann erneut das nächste Mal, wenn Ihre App einen Timer startet.
  • Wenn Flex Timer nicht läuft: Ihr Timer öffnet ihn.

Fehler

Wenn Flex Timer den Timer nicht erstellen kann, informiert er den Benutzer und öffnet Ihren x-error-Link mit einer errorMessage, die das Problem benennt. Zum Beispiel:

  • Der Timer ist kein gültiges JSON.
  • segments ist erforderlich: eine Liste mit einem oder mehreren Timer-Segmenten.
  • segments[0].timerMode "Sprint" wird nicht unterstützt. Verwenden Sie eines der folgenden: CountUp, CountDown, Rounds, Tabata, ContinuousCue, MixedInterval, RestDriven, Warmup, Cooldown.
  • segments[1].workDuration muss eine ganze Zahl von 1 bis 86400 sein.
  • segments[0].intervals[2].type muss "work" oder "rest" sein.
  • Dieser Timer verwendet Formatversion 2, aber diese Version von Flex Timer kann nur Version 1 lesen. Aktualisieren Sie Flex Timer, um ihn zu öffnen.
  • Der Timer ist größer als 64 KB. Hosten Sie das JSON und übergeben Sie stattdessen die URL.
  • url muss ein https-Link sein.
  • Das Herunterladen des Timers von der URL ist mit HTTP-Status 404 fehlgeschlagen.

Um diese Fehler vor dem Senden zu erkennen, validieren Sie Ihr JSON gegen flextimer-timer.schema.json.

Verwendung über einen KI-Agenten

  1. Geben Sie dem Modell das JSON-Schema oder die oben stehenden Format-Tabellen und bitten Sie um ein einzelnes JSON-Objekt, das darauf abgestimmt ist. Bitten Sie auch um name und details, damit der Athlet das Training auf dem Timer sieht.
  2. Validieren Sie das Ergebnis gegen das Schema.
  3. Senden Sie es mit der Shortcuts-Aktion (iOS), dem Intent (Android) oder einem flextimer://timer-Link.

Versionierung

Dies ist Version 1 des Formats.

  • Erweiterungen: Zu Version 1 können neue optionale Felder hinzugefügt werden. Flex-Timer-Versionen, die diese nicht kennen, ignorieren sie.
  • Breaking Changes: Eine Änderung, die von älteren Versionen nicht korrekt gelesen werden kann, erhält eine neue version-Nummer.

JSON-Schema

Validieren Sie Ihr Timer-JSON gegen dieses Schema (JSON Schema Draft 2020-12), bevor Sie es senden, oder übergeben Sie es einem KI-Modell, damit es gültige Timer erstellt.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gymnext.com/flextimer/flextimer-timer.schema.json",
  "title": "Flex Timer timer",
  "description": "Ein Timer, den eine andere App oder ein KI-Agent an Flex Timer sendet (Formatversion 1). Siehe timer-integration.md. Alle Dauern sind ganze Sekunden.",
  "type": "object",
  "required": ["segments"],
  "properties": {
    "version": {
      "description": "Formatversion. Optional; Standard ist 1. Flex Timer lehnt Versionen ab, die neuer sind als die, die es versteht.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1
    },
    "name": {
      "description": "Name des Trainings. Bei einem Timer mit nur einem Segment ohne eigenen Namen wird dies zum Namen des Timers.",
      "type": "string"
    },
    "description": {
      "description": "Kurze Beschreibung des Trainings.",
      "type": "string"
    },
    "segments": {
      "description": "Ein oder mehrere Timer-Segmente, die nacheinander ausgeführt werden. Mehr als eines ergibt einen Multi-Segment-Timer.",
      "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": "Ein Name pro Runde, Intervall oder Satz; null für unbenannte.",
      "type": "array",
      "items": { "type": ["string", "null"] }
    },
    "common": {
      "type": "object",
      "properties": {
        "name": { "description": "Segmentname, auf dem Timer angezeigt. Standardmäßig nach dem Modus (z. B. \"Tabata\").", "type": "string" },
        "description": { "description": "Kurze Beschreibung des Segments.", "type": "string" },
        "details": { "description": "Vollständiger Trainingstext für den Athleten; Zeilenumbrüche werden beibehalten.", "type": "string" },
        "direction": {
          "description": "true zählt auf, false zählt ab. Standardmäßig nach dem Modus: CountUp, ContinuousCue, RestDriven, Warmup und Cooldown zählen auf; CountDown, Rounds, Tabata und MixedInterval zählen ab.",
          "type": "boolean"
        },
        "roundNames": { "$ref": "#/$defs/names" },
        "intervalNames": { "$ref": "#/$defs/names" },
        "roundNamesUseSame": { "description": "Verwenden Sie den Namen der ersten Runde für jede Runde.", "type": "boolean" },
        "intervalNamesUseSame": { "description": "Verwenden Sie den Namen des ersten Intervalls für jedes Intervall.", "type": "boolean" },
        "roundIntervalNamePresentation": {
          "description": "Wie die Namen angezeigt werden: none (nur Titel), cue (auf dem Bildschirm), speech (gesprochen) oder cueAndSpeech.",
          "enum": ["none", "cue", "speech", "cueAndSpeech"]
        }
      }
    },
    "segment": {
      "type": "object",
      "required": ["timerMode"],
      "allOf": [{ "$ref": "#/$defs/common" }],
      "oneOf": [
        {
          "title": "CountUp (For Time)",
          "properties": {
            "timerMode": { "const": "CountUp" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "Zeitlimit; 0 für keines. Standard 0." }
          }
        },
        {
          "title": "CountDown (AMRAP)",
          "properties": {
            "timerMode": { "const": "CountDown" },
            "duration": { "$ref": "#/$defs/seconds", "description": "Dauer. Standard 600." }
          }
        },
        {
          "title": "Rounds (gleiche Runden, optional gleiche Pausen)",
          "properties": {
            "timerMode": { "const": "Rounds" },
            "roundDuration": { "$ref": "#/$defs/seconds", "description": "Standard 60." },
            "numberOfRounds": { "$ref": "#/$defs/count", "description": "Standard 5." },
            "restBetweenRounds": { "$ref": "#/$defs/secondsOrZero", "description": "Standard 0." }
          }
        },
        {
          "title": "Tabata (Belastung / Pause wiederholt, optional in Sätzen)",
          "properties": {
            "timerMode": { "const": "Tabata" },
            "workDuration": { "$ref": "#/$defs/seconds", "description": "Standard 20." },
            "restDuration": { "$ref": "#/$defs/secondsOrZero", "description": "Standard 10." },
            "roundsPerTabata": { "$ref": "#/$defs/count", "description": "Standard 8." },
            "numberOfTabatas": { "$ref": "#/$defs/count", "description": "Standard 1." },
            "restBetweenTabatas": { "$ref": "#/$defs/secondsOrZero", "description": "Standard 0." }
          }
        },
        {
          "title": "ContinuousCue (EMOM: ein Hinweis in jedem Intervall)",
          "properties": {
            "timerMode": { "const": "ContinuousCue" },
            "cueInterval": { "$ref": "#/$defs/seconds", "description": "Sekunden zwischen den Hinweisen. Standard 60." },
            "totalDuration": { "$ref": "#/$defs/seconds", "description": "Gesamtdauer. Standard 600." }
          }
        },
        {
          "title": "MixedInterval (beliebige Abfolge von Belastung und Pause)",
          "required": ["intervals"],
          "properties": {
            "timerMode": { "const": "MixedInterval" },
            "intervals": {
              "type": "array",
              "minItems": 1,
              "maxItems": 200,
              "items": {
                "type": "object",
                "required": ["duration"],
                "properties": {
                  "type": { "enum": ["work", "rest"], "description": "Standard Belastung." },
                  "duration": { "$ref": "#/$defs/seconds" },
                  "name": { "type": ["string", "null"], "description": "Zum Beispiel die Übung." }
                }
              }
            },
            "numberOfRounds": { "$ref": "#/$defs/count", "description": "Anzahl der Wiederholungen der Abfolge. Standard 1." },
            "restBetweenRounds": { "$ref": "#/$defs/secondsOrZero", "description": "Standard 0." }
          }
        },
        {
          "title": "RestDriven (Sätze beliebiger Länge, jeweils gefolgt von einer Pause)",
          "properties": {
            "timerMode": { "const": "RestDriven" },
            "numberOfSets": { "$ref": "#/$defs/count", "description": "Standard 5." },
            "restType": { "enum": ["fixed", "ratio"], "description": "Standard fest." },
            "fixedRestDuration": { "$ref": "#/$defs/secondsOrZero", "description": "Pause nach jedem Satz, wenn restType fest ist. Standard 120." },
            "workRatio": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Mit restRatio die Pause als Verhältnis der Satzzeit, wenn restType Verhältnis ist. Standard 1." },
            "restRatio": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Standard 1." }
          }
        },
        {
          "title": "Warmup",
          "properties": {
            "timerMode": { "const": "Warmup" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "0 für keines. Standard 600." }
          }
        },
        {
          "title": "Cooldown",
          "properties": {
            "timerMode": { "const": "Cooldown" },
            "timeCap": { "$ref": "#/$defs/secondsOrZero", "description": "0 für keines. Standard 600." }
          }
        }
      ]
    }
  }
}