Deep link-automatisering

Deep link-automatiseringar låter dig skapa REST API-automatiseringar programmatiskt med URL-scheman. Det passar för automationsskript, konfigurationshantering eller integration med externa system som behöver konfigurera export av hälsodata.

Översikt

Deep link-automatiseringar använder ett anpassat URL-schema för att skapa och konfigurera REST API-automatiseringar utan att manuellt ange inställningar i appen. När du öppnar en deep link-URL skapar appen automatiskt en ny automatisering med den angivna konfigurationen.

Användningsfall:

• Programmatisk uppsättning av automatiseringar från skript eller verktyg
• Masskonfiguration av automatiseringar
• Integration med konfigurationssystem
• Snabb uppsättning från externa appar eller webbplatser
• Test- och utvecklingsflöden

Huvudfunktioner:

• Skapa automatiseringar via URL-schema
• Konfigurera alla inställningar för REST API-automatisering
• Typsäker parametervalidering
• Utförliga felmeddelanden

Begränsningar

• Deep links stöder endast REST API-automatiseringar (inte Dropbox, Google Drive med mera)
• URL-längdbegränsningar kan begränsa mycket långa parameterlistor
• Alla begränsningar från REST API-automatiseringar gäller (bakgrundsbehandling, åtkomst till hälsodata med mera)

URL-format

Deep link-URL:en följer denna struktur:

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

Bas-URL: com.HealthExport://automation

Parametrar: Alla parametrar är valfria utom name och url. Parameternamn skiljer inte mellan versaler och gemener.

Parameterreferens

Obligatoriska parametrar

url (obligatorisk)

• Typ: Sträng (giltig URL)
• Beskrivning: Slutpunkts-URL dit hälsodata skickas
• Exempel: https://api.example.com/health-data
• Anmärkning: Måste vara en giltig HTTP/HTTPS-URL

name (obligatorisk)

• Typ: Sträng
• Beskrivning: Ett beskrivande namn på automatiseringen
• Exempel: My%20Backend%20API (URL-kodat: «My Backend API»)
• Anmärkning: Måste URL-kodas om namnet innehåller mellanslag eller specialtecken

Grundläggande konfiguration

format

• Typ: Enum (json, csv)
• Standard: json
• Beskrivning: Exportformat för data
• Exempel: format=json eller format=csv
• Anmärkning: CSV-format aktiverar automatiskt dataaggregering

enabled

• Typ: Boolesk (true, false, 1, 0, yes, no)
• Standard: false
• Beskrivning: Om automatiseringen ska aktiveras direkt efter skapande
• Exempel: enabled=true

datatype

• Typ: Enum (se datatyper nedan)
• Standard: healthMetrics
• Beskrivning: Typ av hälsodata att exportera
• Exempel: datatype=workouts
• Anmärkning: Endast en datatyp kan väljas. Detta konfigurerar automatiskt rätt inkluderingsflaggor.

Giltiga datatyper:

• healthMetrics – Hälsomätningar (steg, puls, sömn med mera)
• workouts – Träning och aktiviteter
• symptoms – Symptom och hälsotillstånd
• ecg – EKG-mätningar
• heartRateNotification – Hög/låg puls-händelser
• stateOfMind – Humör och mental status (iOS 18.0+)
• cycleTracking – Menstruationscykel och reproduktiv hälsa
• medications – Medicinloggar och efterlevnad (iOS 26.0+)

Exportinställningar

period

• Typ: Enum
• Standard: none
• Beskrivning: Datumintervall för dataexport
• Exempel: period=today

Giltiga värden:

• none – Standard (hela föregående dag plus innevarande dag)
• lastsync – Sedan senaste synkronisering
• today – Idag
• yesterday – Igår
• previous7days – Senaste 7 dagarna
• realtime – Realtidsuppdateringar (kräver synkroniseringsintervall i sekunder)

interval

• Typ: Enum
• Standard: none
• Beskrivning: Tidsgrupperings-/aggregeringsintervall (endast giltigt för datatypen healthMetrics)
• Exempel: interval=hours

Giltiga värden:

• none – Standard (ingen aggregering)
• minutes – Gruppera per minut
• hours – Gruppera per timme
• days – Gruppera per dag
• weeks – Gruppera per vecka
• months – Gruppera per månad
• years – Gruppera per år

Anmärkning: Denna parameter är endast giltig när datatype=healthMetrics. CSV-format aggregerar alltid data.

aggregatedata

• Typ: Boolesk
• Standard: true (för CSV), false (för JSON)
• Beskrivning: Om data ska aggregeras/sammanfattas (endast giltigt för healthMetrics med JSON-format)
• Exempel: aggregatedata=true
• Anmärkning: Sätts automatiskt till true när format=csv

aggregatesleep

• Typ: Boolesk
• Standard: true
• Beskrivning: Om sömn ska aggregeras
• Exempel: aggregatesleep=true

exportversion

• Typ: Enum (v1, v2, 1, 2)
• Standard: v2
• Beskrivning: Version av exportformatet
• Exempel: exportversion=v2
• Anmärkning: Version 2 inkluderar utökad träningsdata och mer detaljerad metadata

batchrequests

• Typ: Boolesk
• Standard: false
• Beskrivning: Skicka data i batcher över flera förfrågningar (endast giltigt för REST API med JSON-format)
• Exempel: batchrequests=true
• Anmärkning: Endast giltigt när format=json och exportDestination=restApi

Synkroniseringsfrekvens

syncinterval

• Typ: Enum
• Standard: minutes
• Beskrivning: Intervall för synkroniseringsfrekvens
• Exempel: syncinterval=hours

Giltiga värden:

• minutes – Synkronisera var N:e minut
• hours – Synkronisera var N:e timme
• days – Synkronisera var N:e dag
• weeks – Synkronisera var N:e vecka
• seconds – Endast giltigt när period=realtime

Anmärkning: För REST API-automatiseringar är endast minutes, hours, days och weeks giltiga om du inte använder realexport.

syncquantity

• Typ: Heltal (positivt)
• Standard: 5
• Beskrivning: Antal intervall mellan synkroniseringar
• Exempel: syncquantity=10 (synkronisera var 10:e minut om syncinterval=minutes)
• Anmärkning: Måste vara större än 0

HTTP-konfiguration

headers

• Typ: Sträng (kommaseparerade nyckel-värde-par)
• Standard: Ingen
• Beskrivning: HTTP-rubriker för autentisering eller metadata
• Exempel: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Format: key1,value1,key2,value2,...
• Anmärkning: Värden bör URL-kodas. Varje rubrik kräver både nyckel och värde.

Exempel på rubriker:

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

requesttimeout

• Typ: Heltal (60–86400)
• Standard: 60
• Beskrivning: Timeout för förfrågan i sekunder
• Exempel: requesttimeout=300
• Anmärkning: Måste vara mellan 60 och 86400 sekunder (1 minut till 24 timmar)

Inställningar per datatyp

Inställningar för hälsomätningar

metrics

• Typ: Sträng (kommaseparerade MetricName rawValues)
• Standard: Alla tillgängliga mätningar
• Beskrivning: Specifika hälsomätningar att inkludera (endast giltigt för healthMetrics)
• Exempel: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Anmärkning: Använd exakta MetricName rawValues. Om utelämnat inkluderas alla tillgängliga mätningar.

Vanliga mätningar:

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

Se appens skärm för val av mätningar för fullständig lista.

Inställningar för träning

includeroutes

• Typ: Boolesk
• Standard: true
• Beskrivning: Inkludera ruttdata för pass (endast giltigt för workouts)
• Exempel: includeroutes=true

includeworkoutmetadata

• Typ: Boolesk
• Standard: true
• Beskrivning: Inkludera träningsmätningar (puls, kalorier med mera.) under passen (endast giltigt för workouts)
• Exempel: includeworkoutmetadata=true

workoutsmetadatainterval

• Typ: Enum (minutes, seconds)
• Standard: minutes
• Beskrivning: Tidsgruppering för träningsmätningar (endast giltigt för workouts med exportversion v2)
• Exempel: workoutsmetadatainterval=seconds
• Anmärkning: Endast giltigt när datatype=workouts och exportversion=v2

workouttypes

• Typ: Sträng (kommaseparerade UInt-värden)
• Standard: Tom (alla träningstyper)
• Beskrivning: Specifika träningstyper att inkludera (endast giltigt för workouts)
• Exempel: workouttypes=1,2,3
• Anmärkning: Använder HealthKit-identifierare för träningstyp

Aviseringar

notifyonupdate

• Typ: Boolesk
• Standard: true
• Beskrivning: Ta emot aviseringar när cachad data uppdateras
• Exempel: notifyonupdate=true

notifywhenrun

• Typ: Boolesk
• Standard: true
• Beskrivning: Ta emot aviseringar varje gång automatiseringen körs
• Exempel: notifywhenrun=false

Exempel

Grundläggande REST API-automatisering

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

Skapar en enkel automatisering som skickar JSON-data till den angivna slutpunkten.

Med autentiseringsrubriker

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

Skapar en automatisering med anpassade autentiseringsrubriker.

Hälsomätningar med specifika mätningar

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

Skapar en automatisering som endast exporterar steg och puls, aggregerat per timme.

Träning med ruttdata

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

Skapar en automatisering för träning med ruttdata och träningsmätningar, med exportversion 2.

Komplett konfigurationsexempel

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

Ett omfattande exempel med alla huvudparametrar konfigurerade.

CSV-formatexempel

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

Skapar en CSV-exportautomatisering. CSV-format aktiverar automatiskt dataaggregering.

URL-kodning

Specialtecken i parametervärden måste URL-kodas. Vanliga kodningar:

• Mellanslag: %20
• Komma: %2C
• Kolon: %3A
• Semikolon: %3B
• Likhetstecken: %3D
• Et-tecken: %26
• Plus: %2B

Exempel:

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

Exempel med rubriker:

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

De flesta programmeringsspråk och verktyg har funktioner för URL-kodning:

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

Testa deep links

Från Safari (iOS)

1. Öppna Safari på din iOS-enhet
2. Ange deep link-URL:en i adressfältet
3. Tryck på Gå
4. Appen ska öppnas och skapa automatiseringen

Från Terminal (macOS/iOS Simulator)

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

Från Xcode

Lägg till en brytpunkt eller använd debuggerkonsolen:

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

Från appen Genvägar

1. Skapa en ny genväg
2. Lägg till åtgärden «Öppna URL:er»
3. Ange din deep link-URL
4. Kör genvägen

Felsökning

Vanliga problem

"Could not parse the URL"

• Kontrollera att URL-schemat är korrekt: com.HealthExport://automation
• Kontrollera att alla parametervärden är korrekt URL-kodade
• Kontrollera stavningen av parameternamn (skiljer inte mellan versaler och gemener)

"Invalid URL parameter value"

• Kontrollera att URL:en är en giltig HTTP/HTTPS-URL
• Kontrollera URL-kodning
• Se till att URL:en inte innehåller ogiltiga tecken

"Invalid data type"

• Använd exakta datatypvärden: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Kontrollera stavning (matchning skiljer inte mellan versaler och gemener)

"Invalid sync cadence interval"

• För REST API, använd endast: minutes, hours, days, weeks
• Använd seconds endast när period=realtime

"Aggregation settings are only valid for healthMetrics data type"

• Parametrarna aggregatedata och interval gäller endast med datatype=healthMetrics
• Ta bort dessa parametrar eller ändra datatyp

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

• batchrequests fungerar endast när format=json
• Ändra format till JSON eller ta bort batchrequests

"Workout settings are only valid for workouts data type"

• includeroutes, includeworkoutmetadata och workoutsmetadatainterval gäller endast med datatype=workouts
• Ändra datatyp till workouts eller ta bort dessa parametrar

"Metrics parameter is only valid for healthMetrics data type"

• metrics gäller endast med datatype=healthMetrics
• Ändra datatyp eller ta bort metrics

"Invalid metric name"

• Använd exakta MetricName rawValues (t.ex. «Step Count», «Heart Rate»)
• Kontrollera stavning och versaler/gemener
• Se appens mätvals-skärm för giltiga namn

"Invalid request timeout"

• Måste vara mellan 60 och 86400 sekunder
• Använd ett värde inom detta intervall

"A name is required for the automation"

• Se till att parametern name ingår
• Kontrollera att värdet inte är tomt efter URL-avkodning

Begränsningar för URL-längd

Mycket långa URL:er (särskilt med många mätningar eller rubriker) kan överskrida systemgränser. Överväg:

• Färre mätningar i parametern metrics
• Färre rubriker
• Kortare parametervärden där det är möjligt
• Att dela upp komplexa konfigurationer i flera enklare automatiseringar

Prioritet mellan parametrar

När flera parametrar krockar:

1. Val av datatyp (datatype) återställer automatiskt inkluderingsflaggor
2. CSV-format (format=csv) sätter automatiskt aggregatedata=true
3. Realtidsperiod (period=realtime) kräver syncinterval=seconds
4. Valideringsfel kastas för inkompatibla kombinationer

Bästa praxis

1. Automatisk synkronisering (när automatiseringar utlöses via deep links):

   • Ladda enheten och använd iPhone-spegling
     • När enheten laddas sätter iOS färre begränsningar på prestanda, så data kan synkroniseras oftare
     • Med iPhone-spegling beter sig enheten som om den var upplåst, så Health Auto Export kan komma åt hälsodata för automatiska åtgärder

2. URL-koda alltid parametervärden som innehåller specialtecken

3. Testa med enkla URL:er först, lägg sedan till komplexitet

4. Använd beskrivande namn för enklare identifiering

5. Validera URL:er innan du skapar deep links programmatiskt

6. Hantera fel på ett robust sätt vid parsning av deep links

7. Dokumentera dina deep link-format om du bygger verktyg som genererar dem

8. Tänk på URL-längd när du inkluderar många mätningar eller rubriker

9. Testa på riktiga enheter såväl som simulatorer

Relaterad dokumentation

• Guide för REST API-automatisering – Detaljer om REST API-automatiseringar
• Översikt över automatiseringar – Allmänna begrepp om automatisering
• Guide för manuell export – Så exporterar du data manuellt

Support

Om du stöter på problem som inte täcks i denna guide:

1. Läs felmeddelandet för specifika parameterproblem
2. Kontrollera att URL-kodningen är korrekt
3. Testa först med en minimal URL
4. Använd knappen Chattsupport i appen för hjälp