Deep link-automatisering

Deep link-automatiseringen stellen je in staat REST API-automatiseringen programmatisch aan te maken met URL-schema's. Dit is handig voor automatiseringsscripts, configuratiebeheer of integratie met externe systemen die gezondheidsdata-export moeten configureren.

Overzicht

Deep link-automatiseringen gebruiken een aangepast URL-schema om REST API-automatiseringen aan te maken en te configureren zonder handmatig instellingen in de app in te voeren. Wanneer je een deep link-URL opent, maakt de app automatisch een nieuwe automatisering met de opgegeven configuratie.

Gebruiksscenario's:

• Programmatische automatisering vanuit scripts of tools
• Bulkconfiguratie van automatiseringen
• Integratie met configuratiebeheersystemen
• Snelle setup vanuit externe apps of websites
• Test- en ontwikkelworkflows

Belangrijkste functies:

• Automatiseringen aanmaken via een URL-schema
• Alle instellingen voor REST API-automatisering configureren
• Typeveilige parameter­validatie
• Uitgebreide foutmeldingen

Beperkingen

• Deep links ondersteunen alleen REST API-automatiseringen (niet Dropbox, Google Drive, enz.)
• URL-lengtebeperkingen kunnen zeer lange parameterlijsten beperken
• Alle beperkingen van REST API-automatiseringen gelden (achtergrondverwerking, toegang tot gezondheidsdata, enz.)

URL-indeling

De deep link-URL volgt deze structuur:

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

Basis-URL: com.HealthExport://automation

Parameters: Alle parameters zijn optioneel behalve name en url. Parameternamen zijn niet hoofdlettergevoelig.

Parameterreferentie

Verplichte parameters

url (verplicht)

• Type: String (geldige URL)
• Beschrijving: De eindpunt-URL waar gezondheidsdata naartoe wordt gestuurd
• Voorbeeld: https://api.example.com/health-data
• Opmerking: Moet een geldige HTTP/HTTPS-URL zijn

name (verplicht)

• Type: String
• Beschrijving: Een beschrijvende naam voor de automatisering
• Voorbeeld: My%20Backend%20API (URL-gecodeerd: «My Backend API»)
• Opmerking: Moet URL-gecodeerd worden als de naam spaties of speciale tekens bevat

Basisconfiguratie

format

• Type: Enum (json, csv)
• Standaard: json
• Beschrijving: Exportformaat voor de data
• Voorbeeld: format=json of format=csv
• Opmerking: CSV-formaat schakelt automatisch gegevensaggregatie in

enabled

• Type: Booleaans (true, false, 1, 0, yes, no)
• Standaard: false
• Beschrijving: Of de automatisering direct na aanmaak ingeschakeld is
• Voorbeeld: enabled=true

datatype

• Type: Enum (zie datatypen hieronder)
• Standaard: healthMetrics
• Beschrijving: Type gezondheidsdata om te exporteren
• Voorbeeld: datatype=workouts
• Opmerking: Slechts één datatype kan worden geselecteerd. Dit configureert automatisch de juiste include-vlaggen.

Geldige datatypen:

• healthMetrics – Gezondheids­metriek (stappen, hartslag, slaap, enz.)
• workouts – Beweging en fitnessactiviteiten
• symptoms – Symptomen en gezondheidstoestanden
• ecg – Elektrocardiogram­metingen
• heartRateNotification – Gebeurtenissen met hoge/lage hartslag
• stateOfMind – Stemming en mentale toestand (iOS 18.0+)
• cycleTracking – Menstruatiecyclus en reproductieve gezondheid
• medications – Medicijn­logboeken en therapietrouw (iOS 26.0+)

Exportinstellingen

period

• Type: Enum
• Standaard: none
• Beschrijving: Datumbereik voor data-export
• Voorbeeld: period=today

Geldige waarden:

• none – Standaard (volledige vorige dag plus huidige dag)
• lastsync – Sinds laatste synchronisatie
• today – Vandaag
• yesterday – Gisteren
• previous7days – Afgelopen 7 dagen
• realtime – Realtime-updates (vereist synchronisatie­interval in seconden)

interval

• Type: Enum
• Standaard: none
• Beschrijving: Tijds­groeperings-/aggregatie­interval (alleen geldig voor datatype healthMetrics)
• Voorbeeld: interval=hours

Geldige waarden:

• none – Standaard (geen aggregatie)
• minutes – Groepeer per minuut
• hours – Groepeer per uur
• days – Groepeer per dag
• weeks – Groepeer per week
• months – Groepeer per maand
• years – Groepeer per jaar

Opmerking: Deze parameter is alleen geldig bij datatype=healthMetrics. CSV-formaat aggregeert altijd data.

aggregatedata

• Type: Booleaans
• Standaard: true (voor CSV), false (voor JSON)
• Beschrijving: Of data geaggregeerd/samengevat wordt (alleen geldig voor healthMetrics met JSON-formaat)
• Voorbeeld: aggregatedata=true
• Opmerking: Wordt automatisch true bij format=csv

aggregatesleep

• Type: Booleaans
• Standaard: true
• Beschrijving: Of slaapdata geaggregeerd wordt
• Voorbeeld: aggregatesleep=true

exportversion

• Type: Enum (v1, v2, 1, 2)
• Standaard: v2
• Beschrijving: Versie van het exportformaat
• Voorbeeld: exportversion=v2
• Opmerking: Versie 2 bevat uitgebreidere workout­data en gedetailleerdere metadata

batchrequests

• Type: Booleaans
• Standaard: false
• Beschrijving: Data in batches over meerdere verzoeken versturen (alleen geldig voor REST API met JSON-formaat)
• Voorbeeld: batchrequests=true
• Opmerking: Alleen geldig bij format=json en exportDestination=restApi

Synchronisatie­cadans

syncinterval

• Type: Enum
• Standaard: minutes
• Beschrijving: Interval voor synchronisatie­cadans
• Voorbeeld: syncinterval=hours

Geldige waarden:

• minutes – Elke N minuten synchroniseren
• hours – Elke N uur synchroniseren
• days – Elke N dagen synchroniseren
• weeks – Elke N weken synchroniseren
• seconds – Alleen geldig bij period=realtime

Opmerking: Voor REST API-automatiseringen zijn alleen minutes, hours, days en weeks geldig, tenzij je realtime-export gebruikt.

syncquantity

• Type: Geheel getal (positief)
• Standaard: 5
• Beschrijving: Aantal intervallen tussen synchronisaties
• Voorbeeld: syncquantity=10 (elke 10 minuten synchroniseren als syncinterval=minutes)
• Opmerking: Moet groter zijn dan 0

HTTP-configuratie

headers

• Type: String (komma-gescheiden sleutel-waardeparen)
• Standaard: Geen
• Beschrijving: HTTP-headers voor authenticatie of metadata
• Voorbeeld: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Indeling: key1,value1,key2,value2,...
• Opmerking: Waarden moeten URL-gecodeerd worden. Elke header vereist zowel een sleutel als een waarde.

Voorbeeldheaders:

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

requesttimeout

• Type: Geheel getal (60–86400)
• Standaard: 60
• Beschrijving: Time-out voor verzoek in seconden
• Voorbeeld: requesttimeout=300
• Opmerking: Moet tussen 60 en 86400 seconden liggen (1 minuut tot 24 uur)

Instellingen per datatype

Instellingen voor gezondheids­metriek

metrics

• Type: String (komma-gescheiden MetricName rawValues)
• Standaard: Alle beschikbare metriek
• Beschrijving: Specifieke gezondheids­metriek om op te nemen (alleen geldig voor healthMetrics)
• Voorbeeld: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Opmerking: Gebruik exacte MetricName rawValues. Indien niet opgegeven, worden alle beschikbare metriek opgenomen.

Veelvoorkomende metriek­namen:

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

Zie het metriek­selectiescherm in de app voor de volledige lijst.

Workout-instellingen

includeroutes

• Type: Booleaans
• Standaard: true
• Beschrijving: Routedata voor workouts opnemen (alleen geldig voor workouts)
• Voorbeeld: includeroutes=true

includeworkoutmetadata

• Type: Booleaans
• Standaard: true
• Beschrijving: Workout­metriek (hartslag, calorieën, enz.) tijdens workouts opnemen (alleen geldig voor workouts)
• Voorbeeld: includeworkoutmetadata=true

workoutsmetadatainterval

• Type: Enum (minutes, seconds)
• Standaard: minutes
• Beschrijving: Tijds­groepering voor workout­metriek (alleen geldig voor workouts met exportversie v2)
• Voorbeeld: workoutsmetadatainterval=seconds
• Opmerking: Alleen geldig bij datatype=workouts en exportversion=v2

workouttypes

• Type: String (komma-gescheiden UInt-waarden)
• Standaard: Leeg (alle workout­typen)
• Beschrijving: Specifieke workout­typen om op te nemen (alleen geldig voor workouts)
• Voorbeeld: workouttypes=1,2,3
• Opmerking: Gebruikt HealthKit-workout­type­identifiers

Meldingen

notifyonupdate

• Type: Booleaans
• Standaard: true
• Beschrijving: Meldingen ontvangen wanneer gecachte data wordt bijgewerkt
• Voorbeeld: notifyonupdate=true

notifywhenrun

• Type: Booleaans
• Standaard: true
• Beschrijving: Meldingen ontvangen telkens wanneer de automatisering wordt uitgevoerd
• Voorbeeld: notifywhenrun=false

Voorbeelden

Basis REST API-automatisering

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

Maakt een eenvoudige automatisering die JSON-data naar het opgegeven eindpunt stuurt.

Met authenticatie­headers

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

Maakt een automatisering met aangepaste authenticatie­headers.

Gezondheids­metriek met specifieke metriek

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

Maakt een automatisering die alleen stappen en hartslag exporteert, geaggregeerd per uur.

Workouts met routedata

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

Maakt een automatisering voor workouts met routedata en workout­metriek, met exportversie 2.

Volledig configuratievoorbeeld

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

Een uitgebreid voorbeeld met alle belangrijkste parameters ingesteld.

CSV-formaat­voorbeeld

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

Maakt een CSV-export­automatisering. CSV-formaat schakelt automatisch gegevensaggregatie in.

URL-codering

Speciale tekens in parameter­waarden moeten URL-gecodeerd worden. Veelvoorkomende coderingen:

• Spatie: %20
• Komma: %2C
• Dubbele punt: %3A
• Puntkomma: %3B
• Is-gelijk: %3D
• Ampersand: %26
• Plus: %2B

Voorbeeld:

• Origineel: My Automation Name
• Gecodeerd: My%20Automation%20Name

Headers-voorbeeld:

• Origineel: Authorization, Bearer token123
• Gecodeerd: Authorization,Bearer%20token123

De meeste programmeertalen en tools bieden URL-coderings­functies:

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

Deep links testen

Vanuit Safari (iOS)

1. Open Safari op je iOS-apparaat
2. Voer de deep link-URL in de adresbalk in
3. Tik op Ga
4. De app zou moeten openen en de automatisering aanmaken

Vanuit Terminal (macOS/iOS Simulator)

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

Vanuit Xcode

Voeg een breekpunt toe of gebruik de debugger­console:

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

Vanuit de Opdrachten-app

1. Maak een nieuwe opdracht
2. Voeg de actie «URL's openen» toe
3. Voer je deep link-URL in
4. Voer de opdracht uit

Probleemoplossing

Veelvoorkomende problemen

"Could not parse the URL"

• Controleer of het URL-schema klopt: com.HealthExport://automation
• Controleer of alle parameter­waarden correct URL-gecodeerd zijn
• Controleer de spelling van parameternamen (niet hoofdlettergevoelig)

"Invalid URL parameter value"

• Controleer of de URL een geldige HTTP/HTTPS-URL is
• Controleer URL-codering
• Zorg dat de URL geen ongeldige tekens bevat

"Invalid data type"

• Gebruik exacte datatype­waarden: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Controleer spelling (hoofdletter­ongevoelige matching wordt ondersteund)

"Invalid sync cadence interval"

• Gebruik voor REST API alleen: minutes, hours, days, weeks
• Gebruik seconds alleen bij period=realtime

"Aggregation settings are only valid for healthMetrics data type"

• De parameters aggregatedata en interval werken alleen met datatype=healthMetrics
• Verwijder deze parameters of wijzig het datatype

"Batch requests are only valid for REST API with JSON format"

• batchrequests werkt alleen bij format=json
• Wijzig het formaat naar JSON of verwijder de parameter batchrequests

"Workout settings are only valid for workouts data type"

• includeroutes, includeworkoutmetadata en workoutsmetadatainterval werken alleen met datatype=workouts
• Wijzig het datatype naar workouts of verwijder deze parameters

"Metrics parameter is only valid for healthMetrics data type"

• De parameter metrics werkt alleen met datatype=healthMetrics
• Wijzig het datatype of verwijder metrics

"Invalid metric name"

• Gebruik exacte MetricName rawValues (bijv. «Step Count», «Heart Rate»)
• Controleer spelling en hoofdletters
• Zie het metriek­selectiescherm in de app voor geldige namen

"Invalid request timeout"

• Moet tussen 60 en 86400 seconden liggen
• Gebruik een waarde binnen dit bereik

"A name is required for the automation"

• Zorg dat de parameter name is opgenomen
• Controleer dat de waarde na URL-decodering niet leeg is

URL-lengte­beperkingen

Zeer lange URL's (vooral met veel metriek of headers) kunnen systeem­grenzen overschrijden. Overweeg:

• Minder metriek in de parameter metrics
• Minder headers
• Kortere parameter­waarden waar mogelijk
• Complexe configuraties splitsen in meerdere eenvoudigere automatiseringen

Parameter­voorrang

Bij conflicterende parameters:

1. Datatype­selectie (datatype) zet include-vlaggen automatisch terug
2. CSV-formaat (format=csv) zet automatisch aggregatedata=true
3. Realtime-periode (period=realtime) vereist syncinterval=seconds
4. Validatiefouten worden gegooid bij incompatibele combinaties

Best practices

1. Automatische synchronisatie (wanneer automatiseringen via deep links worden getriggerd):

   • Laad je apparaat en gebruik iPhone-spiegeling
     • Tijdens het opladen stelt iOS minder prestatie­beperkingen, zodat data vaker kan synchroniseren
     • Met iPhone-spiegeling gedraagt het apparaat zich alsof het ontgrendeld is, zodat Health Auto Export toegang heeft tot gezondheidsdata voor geautomatiseerde acties

2. URL-codeer altijd parameter­waarden met speciale tekens

3. Test eerst met eenvoudige URL's, voeg daarna complexiteit toe

4. Gebruik beschrijvende namen voor eenvoudigere identificatie

5. Valideer URL's voordat je deep links programmatisch aanmaakt

6. Behandel fouten netjes bij het parseren van deep links

7. Documenteer je deep link-formaten als je tools bouwt die ze genereren

8. Houd rekening met URL-lengte bij veel metriek of headers

9. Test op echte apparaten én op simulators

Gerelateerde documentatie

• Handleiding REST API-automatisering – Gedetailleerde informatie over REST API-automatiseringen
• Overzicht automatiseringen – Algemene concepten over automatisering
• Handleiding handmatige export – Gegevens handmatig exporteren

Ondersteuning

Als je problemen hebt die niet in deze handleiding staan:

1. Lees de foutmelding voor specifieke parameter­problemen
2. Controleer of URL-codering correct is
3. Test eerst met een minimale URL
4. Gebruik de knop Chathondersteuning in de app voor hulp