Deep-Link-Automatisierung

Deep-Link-Automatisierungen ermöglichen es Ihnen, REST-API-Automatisierungen programmatisch mit URL-Schemas zu erstellen. Dies ist ideal für Automatisierungsskripte, Konfigurationsverwaltung oder die Integration mit externen Systemen, die Gesundheitsdatenexporte konfigurieren müssen.

Übersicht

Deep-Link-Automatisierungen verwenden ein benutzerdefiniertes URL-Schema, um REST-API-Automatisierungen zu erstellen und zu konfigurieren, ohne Einstellungen manuell in der App einzugeben. Wenn Sie eine Deep-Link-URL öffnen, erstellt die App automatisch eine neue Automatisierung mit der angegebenen Konfiguration.

Anwendungsfälle:

• Programmatische Automatisierungseinrichtung aus Skripten oder Tools
• Massenkonfiguration von Automatisierungen
• Integration mit Konfigurationsverwaltungssystemen
• Schnelle Einrichtung von externen Anwendungen oder Websites
• Test- und Entwicklungs-Workflows

Hauptfunktionen:

• Automatisierungen über URL-Schema erstellen
• Alle REST-API-Automatisierungseinstellungen konfigurieren
• Typsichere Parametervalidierung
• Umfassende Fehlermeldungen

Einschränkungen

• Deep Links unterstützen nur REST-API-Automatisierungen (nicht Dropbox, Google Drive usw.)
• URL-Längenlimits können sehr lange Parameterlisten einschränken
• Alle Einschränkungen von REST-API-Automatisierungen gelten (Hintergrundverarbeitung, Zugriff auf Gesundheitsdaten usw.)

URL-Format

Die Deep-Link-URL folgt dieser Struktur:

com.HealthExport://automation?parameter1=value1&parameter2=value2&...

Basis-URL: com.HealthExport://automation

Parameter: Alle Parameter sind optional außer name und url. Parameter sind nicht case-sensitiv.

Parameterreferenz

Erforderliche Parameter

url (erforderlich)

• Typ: String (gültige URL)
• Beschreibung: Die Endpunkt-URL, an die Gesundheitsdaten gesendet werden
• Beispiel: https://api.example.com/health-data
• Hinweis: Muss eine gültige HTTP/HTTPS-URL sein

name (erforderlich)

• Typ: String
• Beschreibung: Ein beschreibender Name für die Automatisierung
• Beispiel: My%20Backend%20API (URL-codiert: "My Backend API")
• Hinweis: Muss URL-codiert sein, wenn es Leerzeichen oder Sonderzeichen enthält

Grundkonfiguration

format

• Typ: Enum (json, csv)
• Standard: json
• Beschreibung: Exportformat für die Daten
• Beispiel: format=json oder format=csv
• Hinweis: CSV-Format aktiviert automatisch die Datenaggregation

enabled

• Typ: Boolean (true, false, 1, 0, yes, no)
• Standard: false
• Beschreibung: Ob die Automatisierung sofort nach der Erstellung aktiviert ist
• Beispiel: enabled=true

datatype

• Typ: Enum (siehe Datentypen unten)
• Standard: healthMetrics
• Beschreibung: Art der zu exportierenden Gesundheitsdaten
• Beispiel: datatype=workouts
• Hinweis: Es kann nur ein Datentyp ausgewählt werden. Das Setzen konfiguriert automatisch die entsprechenden Include-Flags.

Gültige Datentypen:

• healthMetrics - Gesundheitsmetriken (Schritte, Herzfrequenz, Schlaf usw.)
• workouts - Trainings- und Fitnessaktivitäten
• symptoms - Gesundheitssymptome und -zustände
• ecg - Elektrokardiogramm-Messwerte
• heartRateNotification - Hohe/niedrige Herzfrequenzereignisse
• stateOfMind - Stimmungs- und Geisteszustandseinträge (iOS 18.0+)
• cycleTracking - Menstruationszyklus- und Reproduktionsgesundheitsdaten
• medications - Medikamentenprotokolle und -adhärenz (iOS 26.0+)

Exporteinstellungen

period

• Typ: Enum
• Standard: none
• Beschreibung: Datumsbereich für den Datenexport
• Beispiel: period=today

Gültige Werte:

• none - Standard (vollständiger vorheriger Tag plus aktueller Tag)
• lastsync - Seit letzter Synchronisierung
• today - Aktueller Tag
• yesterday - Vorheriger Tag
• previous7days - Letzte 7 Tage
• realtime - Echtzeit-Updates (erfordert Sekunden-Synchronisierungsintervall)

interval

• Typ: Enum
• Standard: none
• Beschreibung: Zeitgruppierungs-/Aggregationsintervall (nur gültig für healthMetrics-Datentyp)
• Beispiel: interval=hours

Gültige Werte:

• none - Standard (keine Aggregation)
• minutes - Nach Minute gruppieren
• hours - Nach Stunde gruppieren
• days - Nach Tag gruppieren
• weeks - Nach Woche gruppieren
• months - Nach Monat gruppieren
• years - Nach Jahr gruppieren

Hinweis: Dieser Parameter ist nur gültig, wenn datatype=healthMetrics. CSV-Format aggregiert immer Daten.

aggregatedata

• Typ: Boolean
• Standard: true (für CSV), false (für JSON)
• Beschreibung: Ob Daten aggregiert/zusammengefasst werden sollen (nur gültig für healthMetrics mit JSON-Format)
• Beispiel: aggregatedata=true
• Hinweis: Wird automatisch auf true gesetzt, wenn format=csv

aggregatesleep

• Typ: Boolean
• Standard: true
• Beschreibung: Ob Schlafdaten aggregiert werden sollen
• Beispiel: aggregatesleep=true

exportversion

• Typ: Enum (v1, v2, 1, 2)
• Standard: v2
• Beschreibung: Exportformatversion
• Beispiel: exportversion=v2
• Hinweis: Version 2 enthält erweiterte Trainingsdaten und detailliertere Metadaten

batchrequests

• Typ: Boolean
• Standard: false
• Beschreibung: Daten in Batches über mehrere Anfragen senden (nur gültig für REST-API mit JSON-Format)
• Beispiel: batchrequests=true
• Hinweis: Nur gültig, wenn format=json und exportDestination=restApi

Synchronisierungsrhythmus

syncinterval

• Typ: Enum
• Standard: minutes
• Beschreibung: Intervall für den Synchronisierungsrhythmus
• Beispiel: syncinterval=hours

Gültige Werte:

• minutes - Alle N Minuten synchronisieren
• hours - Alle N Stunden synchronisieren
• days - Alle N Tage synchronisieren
• weeks - Alle N Wochen synchronisieren
• seconds - Nur gültig, wenn period=realtime

Hinweis: Für REST-API-Automatisierungen sind nur minutes, hours, days und weeks gültig, es sei denn, es wird Echtzeitexport verwendet.

syncquantity

• Typ: Integer (positiv)
• Standard: 5
• Beschreibung: Anzahl der Intervalle zwischen Synchronisierungen
• Beispiel: syncquantity=10 (alle 10 Minuten synchronisieren, wenn syncinterval=minutes)
• Hinweis: Muss größer als 0 sein

HTTP-Konfiguration

headers

• Typ: String (kommagetrennte Schlüssel-Wert-Paare)
• Standard: Keine
• Beschreibung: HTTP-Header für Authentifizierung oder Metadaten
• Beispiel: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Format: key1,value1,key2,value2,...
• Hinweis: Werte sollten URL-codiert sein. Jeder Header erfordert sowohl einen Schlüssel als auch einen Wert.

Beispiel-Header:

• Authorization, Bearer your-token
• X-API-Key, your-api-key
• Content-Type, application/json

requesttimeout

• Typ: Integer (60-86400)
• Standard: 60
• Beschreibung: Anfrage-Timeout in Sekunden
• Beispiel: requesttimeout=300
• Hinweis: Muss zwischen 60 und 86400 Sekunden liegen (1 Minute bis 24 Stunden)

Datentypspezifische Einstellungen

Gesundheitsmetriken-Einstellungen

metrics

• Typ: String (kommagetrennte MetricName rawValues)
• Standard: Alle verfügbaren Metriken
• Beschreibung: Spezifische Gesundheitsmetriken, die einbezogen werden sollen (nur gültig für healthMetrics-Datentyp)
• Beispiel: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Hinweis: Muss exakte MetricName rawValues verwenden. Wenn nicht angegeben, werden alle verfügbaren Metriken einbezogen.

Häufige Metriknamen:

• Step Count
• Heart Rate
• Active Energy
• Apple Exercise Time
• Sleep Analysis
• Walking + Running Distance

Siehe den Metrikauswahlbildschirm der App für die vollständige Liste der verfügbaren Metriken.

Trainings-Einstellungen

includeroutes

• Typ: Boolean
• Standard: true
• Beschreibung: Routendaten für Trainings einbeziehen (nur gültig für workouts-Datentyp)
• Beispiel: includeroutes=true

includeworkoutmetadata

• Typ: Boolean
• Standard: true
• Beschreibung: Trainingsmetriken (Herzfrequenz, Kalorien usw.) einbeziehen, die während der Trainings gesammelt wurden (nur gültig für workouts-Datentyp)
• Beispiel: includeworkoutmetadata=true

workoutsmetadatainterval

• Typ: Enum (minutes, seconds)
• Standard: minutes
• Beschreibung: Zeitgruppierung für Trainingsmetriken (nur gültig für workouts-Datentyp mit exportVersion v2)
• Beispiel: workoutsmetadatainterval=seconds
• Hinweis: Nur gültig, wenn datatype=workouts und exportversion=v2

workouttypes

• Typ: String (kommagetrennte UInt-Werte)
• Standard: Leer (alle Trainingsarten)
• Beschreibung: Spezifische Trainingsarten, die einbezogen werden sollen (nur gültig für workouts-Datentyp)
• Beispiel: workouttypes=1,2,3
• Hinweis: Verwendet HealthKit-Trainingsart-Identifikatoren

Benachrichtigungen

notifyonupdate

• Typ: Boolean
• Standard: true
• Beschreibung: Benachrichtigungen erhalten, wenn zwischengespeicherte Daten aktualisiert werden
• Beispiel: notifyonupdate=true

notifywhenrun

• Typ: Boolean
• Standard: true
• Beschreibung: Benachrichtigungen erhalten, wenn die Automatisierung ausgeführt wird
• Beispiel: notifywhenrun=false

Beispiele

Grundlegende REST-API-Automatisierung

com.HealthExport://automation?url=https://api.example.com/health&name=My%20Automation&format=json&enabled=true

Erstellt eine grundlegende Automatisierung, die JSON-Daten an den angegebenen Endpunkt sendet.

Mit Authentifizierungs-Headern

com.HealthExport://automation?url=https://api.example.com/health&name=Authenticated%20API&format=json&headers=Authorization,Bearer%20your-token-here,X-API-Key,abc123&enabled=true

Erstellt eine Automatisierung mit benutzerdefinierten Authentifizierungs-Headern.

Gesundheitsmetriken mit spezifischen Metriken

com.HealthExport://automation?url=https://api.example.com/metrics&name=Steps%20and%20Heart%20Rate&format=json&datatype=healthMetrics&metrics=Step%20Count,Heart%20Rate&aggregatedata=true&interval=hours&enabled=true

Erstellt eine Automatisierung, die nur Schritte und Herzfrequenz exportiert, nach Stunde aggregiert.

Trainings mit Routendaten

com.HealthExport://automation?url=https://api.example.com/workouts&name=Workout%20Export&format=json&datatype=workouts&includeroutes=true&includeworkoutmetadata=true&exportversion=v2&workoutsmetadatainterval=minutes&enabled=true

Erstellt eine Automatisierung für Trainings mit Routendaten und Trainingsmetriken unter Verwendung der Exportversion 2.

Vollständiges Konfigurationsbeispiel

com.HealthExport://automation?url=https://api.example.com/health-data&name=Complete%20Configuration&format=json&datatype=healthMetrics&period=today&interval=hours&aggregatedata=true&aggregatesleep=true&exportversion=v2&syncinterval=hours&syncquantity=2&headers=Authorization,Bearer%20token123&requesttimeout=300&batchrequests=true&notifyonupdate=true&notifywhenrun=false&enabled=true

Ein umfassendes Beispiel mit allen wichtigen konfigurierten Parametern.

CSV-Format-Beispiel

com.HealthExport://automation?url=https://api.example.com/csv&name=CSV%20Export&format=csv&datatype=healthMetrics&period=yesterday&enabled=true

Erstellt eine CSV-Export-Automatisierung. Beachten Sie, dass das CSV-Format automatisch die Datenaggregation aktiviert.

URL-Codierung

Sonderzeichen in Parameterwerten müssen URL-codiert sein. Häufige Codierungen:

• Leerzeichen: %20
• Komma: %2C
• Doppelpunkt: %3A
• Semikolon: %3B
• Gleich: %3D
• Und-Zeichen: %26
• Plus: %2B

Beispiel:

• Original: My Automation Name
• Codiert: My%20Automation%20Name

Header-Beispiel:

• Original: Authorization, Bearer token123
• Codiert: Authorization,Bearer%20token123

Die meisten Programmiersprachen und Tools bieten URL-Codierungsfunktionen:

• Swift: addingPercentEncoding(withAllowedCharacters:)
• JavaScript: encodeURIComponent()
• Python: urllib.parse.quote()

Deep Links testen

Von Safari (iOS)

1. Öffnen Sie Safari auf Ihrem iOS-Gerät
2. Geben Sie die Deep-Link-URL in die Adressleiste ein
3. Tippen Sie auf Weiter
4. Die App sollte sich öffnen und die Automatisierung erstellen

Von Terminal (macOS/iOS-Simulator)

xcrun simctl openurl booted "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true"

Von Xcode

Fügen Sie einen Breakpoint hinzu oder verwenden Sie die Debugger-Konsole:

let url = URL(string: "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true")!
try DataModel.shared.handleAPIDeepLink(url)

Von der Shortcuts-App

1. Erstellen Sie eine neue Verknüpfung
2. Fügen Sie die Aktion "URLs öffnen" hinzu
3. Geben Sie Ihre Deep-Link-URL ein
4. Führen Sie die Verknüpfung aus

Fehlerbehebung

Häufige Probleme

"URL konnte nicht analysiert werden"

• Überprüfen Sie, ob das URL-Schema korrekt ist: com.HealthExport://automation
• Überprüfen Sie, ob alle Parameterwerte ordnungsgemäß URL-codiert sind
• Stellen Sie sicher, dass die Parameternamen richtig geschrieben sind (nicht case-sensitiv)

"Ungültiger URL-Parameterwert"

• Überprüfen Sie, ob die URL eine gültige HTTP/HTTPS-URL ist
• Überprüfen Sie die ordnungsgemäße URL-Codierung
• Stellen Sie sicher, dass die URL keine ungültigen Zeichen enthält

"Ungültiger Datentyp"

• Verwenden Sie exakte Datentypwerte: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Überprüfen Sie Rechtschreibung und Groß-/Kleinschreibung (obwohl case-insensitive Matching unterstützt wird)

"Ungültiges Synchronisierungsrhythmus-Intervall"

• Für REST-API verwenden Sie nur: minutes, hours, days, weeks
• Verwenden Sie seconds nur, wenn period=realtime

"Aggregationseinstellungen sind nur für healthMetrics-Datentyp gültig"

• Die Parameter aggregatedata und interval funktionieren nur mit datatype=healthMetrics
• Entfernen Sie diese Parameter oder ändern Sie den Datentyp

"Batch-Anfragen sind nur für REST-API mit JSON-Format gültig"

• batchrequests funktioniert nur, wenn format=json
• Ändern Sie das Format zu JSON oder entfernen Sie den batchrequests-Parameter

"Trainings-Einstellungen sind nur für workouts-Datentyp gültig"

• includeroutes, includeworkoutmetadata und workoutsmetadatainterval funktionieren nur mit datatype=workouts
• Ändern Sie den Datentyp zu workouts oder entfernen Sie diese Parameter

"Metrics-Parameter ist nur für healthMetrics-Datentyp gültig"

• Der Parameter metrics funktioniert nur mit datatype=healthMetrics
• Ändern Sie den Datentyp oder entfernen Sie den metrics-Parameter

"Ungültiger Metrikname"

• Verwenden Sie exakte MetricName rawValues (z. B. "Step Count", "Heart Rate")
• Überprüfen Sie Rechtschreibung und Groß-/Kleinschreibung
• Siehe den Metrikauswahlbildschirm der App für gültige Namen

"Ungültiges Anfrage-Timeout"

• Muss zwischen 60 und 86400 Sekunden liegen
• Verwenden Sie einen Wert innerhalb dieses Bereichs

"Ein Name ist für die Automatisierung erforderlich"

• Stellen Sie sicher, dass der Parameter name enthalten ist
• Überprüfen Sie, ob der Wert nach der URL-Decodierung nicht leer ist

URL-Längenlimits

Sehr lange URLs (besonders mit vielen Metriken oder Headern) können Systemlimits überschreiten. Erwägen Sie:

• Weniger Metriken im Parameter metrics verwenden
• Reduzierung der Anzahl der Header
• Verwendung kürzerer Parameterwerte, wenn möglich
• Aufteilen komplexer Konfigurationen in mehrere einfachere Automatisierungen

Parameterpriorität

Wenn mehrere Parameter in Konflikt stehen:

1. Die Datentypauswahl (datatype) setzt automatisch Include-Flags zurück
2. Das CSV-Format (format=csv) setzt automatisch aggregatedata=true
3. Die Echtzeitperiode (period=realtime) erfordert syncinterval=seconds
4. Validierungsfehler werden für inkompatible Kombinationen ausgelöst

Best Practices

1. URL-codieren Sie immer Parameterwerte, die Sonderzeichen enthalten
2. Testen Sie zuerst mit einfachen URLs, dann fügen Sie Komplexität hinzu
3. Verwenden Sie beschreibende Namen zur einfacheren Identifikation
4. Validiere URLs, bevor Sie Deep Links programmatisch erstellen
5. Behandeln Sie Fehler elegant, wenn Sie Deep Links analysieren
6. Dokumentieren Sie Ihre Deep-Link-Formate, wenn Sie Tools erstellen, die sie generieren
7. Berücksichtigen Sie die URL-Länge, wenn Sie viele Metriken oder Header einbeziehen
8. Testen Sie auf echten Geräten sowie auf Simulatoren

Verwandte Dokumentation

• REST-API-Automatisierungsanleitung - Detaillierte Informationen zu REST-API-Automatisierungen
• Automatisierungsübersicht - Allgemeine Automatisierungskonzepte
• Handbuch zur manuellen Export - So exportieren Sie Daten manuell

Support

Wenn Sie auf Probleme stoßen, die in diesem Handbuch nicht behandelt werden:

1. Überprüfen Sie die Fehlermeldung auf spezifische Parameterprobleme
2. Überprüfen Sie, ob Ihre URL-Codierung korrekt ist
3. Testen Sie zuerst mit einer minimalen URL
4. Verwenden Sie die Chat-Support-Schaltfläche in der App für Hilfe