Automatizace pomocí deep linku

Automatizace přes deep link umožňují vytvářet automatizace REST API programově pomocí URL schémat. Hodí se pro automatizační skripty, správu konfigurací nebo napojení externích systémů, které musejí nastavovat export zdravotních dat.

Přehled

Automatizace přes deep link používají vlastní URL schéma k vytvoření a nastavení automatizací REST API bez ručního zadávání v aplikaci. Po otevření URL deep linku aplikace automaticky vytvoří novou automatizaci s uvedenou konfigurací.

Typické použití:

• programové vytváření automatizací ze skriptů nebo nástrojů
• hromadná konfigurace automatizací
• napojení na systémy pro správu konfigurace
• rychlé nastavení z externích aplikací nebo webů
• testování a vývojové postupy

Hlavní vlastnosti:

• vytváření automatizací přes URL schéma
• nastavení všech parametrů automatizace REST API
• typově bezpečná kontrola parametrů
• podrobné chybové zprávy

Omezení

• deep linky podporují pouze automatizace REST API (ne Dropbox, Google Drive atd.)
• omezení délky URL může omezit velmi dlouhé seznamy parametrů
• platí všechna omezení automatizací REST API (zpracování na pozadí, přístup ke zdravotním datům atd.)

Formát URL

URL deep linku má tuto podobu:

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

Základní URL: com.HealthExport://automation

Parametry: Všechny parametry kromě name a url jsou volitelné. U parametrů se nerozlišují malá a velká písmena.

Reference parametrů

Povinné parametry

url (povinný)

• Typ: řetězec (platná URL)
• Popis: Koncová URL, na kterou se budou odesílat zdravotní data
• Příklad: https://api.example.com/health-data
• Poznámka: Musí jít o platnou HTTP/HTTPS adresu

name (povinný)

• Typ: řetězec
• Popis: Popisný název automatizace
• Příklad: My%20Backend%20API (URL kódováno: „My Backend API“)
• Poznámka: Hodnotu URL‑enkódujte, pokud obsahuje mezery nebo speciální znaky

Základní nastavení

format

• Typ: výčet (json, csv)
• Výchozí: json
• Popis: Formát exportu dat
• Příklad: format=json nebo format=csv
• Poznámka: Formát CSV automaticky zapne agregaci dat

enabled

• Typ: boolean (true, false, 1, 0, yes, no)
• Výchozí: false
• Popis: Zda má být automatizace hned po vytvoření aktivní
• Příklad: enabled=true

datatype

• Typ: výčet (viz typy dat níže)
• Výchozí: healthMetrics
• Popis: Druh exportovaných zdravotních dat
• Příklad: datatype=workouts
• Poznámka: Lze vybrat jen jeden typ dat. Jeho nastavení automaticky nastaví příslušné příznaky zahrnutí.

Platné typy dat:

• healthMetrics – zdravotní metriky (kroky, tep, spánek atd.)
• workouts – pohybové a kondiční aktivity
• symptoms – zdravotní příznaky a stavy
• ecg – záznamy EKG
• heartRateNotification – události vysokého/nízkého tepu
• stateOfMind – záznamy nálady a duševního stavu (iOS 18.0+)
• cycleTracking – menstruační cyklus a reprodukční zdraví
• medications – záznamy léků a adherence (iOS 26.0+)

Nastavení exportu

period

• Typ: výčet
• Výchozí: none
• Popis: Časové okno dat pro export
• Příklad: period=today

Platné hodnoty:

• none – výchozí (celý předchozí den plus aktuální den)
• lastsync – od poslední synchronizace
• today – aktuální den
• yesterday – předchozí den
• previous7days – posledních 7 dní
• realtime – aktualizace téměř v reálném čase (vyžaduje synchronizační interval v sekundách)

interval

• Typ: výčet
• Výchozí: none
• Popis: Časové seskupování/agregace (platí jen pro typ dat healthMetrics)
• Příklad: interval=hours

Platné hodnoty:

• none – výchozí (bez agregace)
• minutes – po minutách
• hours – po hodinách
• days – po dnech
• weeks – po týdnech
• months – po měsících
• years – po letech

Poznámka: Platí jen při datatype=healthMetrics. Formát CSV vždy data agreguje.

aggregatedata

• Typ: boolean
• Výchozí: true (CSV), false (JSON)
• Popis: Zda agregovat/sumarizovat data (platí jen pro healthMetrics ve formátu JSON)
• Příklad: aggregatedata=true
• Poznámka: Při format=csv se automaticky nastaví true

aggregatesleep

• Typ: boolean
• Výchozí: true
• Popis: Zda agregovat data spánku
• Příklad: aggregatesleep=true

exportversion

• Typ: výčet (v1, v2, 1, 2)
• Výchozí: v2
• Popis: Verze formátu exportu
• Příklad: exportversion=v2
• Poznámka: Verze 2 obsahuje rozšířená data o tréninzích a podrobnější metadata

batchrequests

• Typ: boolean
• Výchozí: false
• Popis: Odesílání dat po dávkách v několika požadavcích (platí jen pro REST API ve formátu JSON)
• Příklad: batchrequests=true
• Poznámka: Platí jen při format=json a exportDestination=restApi

Frekvence synchronizace

syncinterval

• Typ: výčet
• Výchozí: minutes
• Popis: Jednotka intervalu synchronizace
• Příklad: syncinterval=hours

Platné hodnoty:

• minutes – každých N minut
• hours – každých N hodin
• days – každých N dní
• weeks – každých N týdnů
• seconds – jen při period=realtime

Poznámka: U automatizací REST API jsou platné jen minutes, hours, days a weeks, pokud nepoužíváte export v reálném čase.

syncquantity

• Typ: celé číslo (kladné)
• Výchozí: 5
• Popis: Kolik intervalů uplyne mezi synchronizacemi
• Příklad: syncquantity=10 (synchronizace každých 10 minut při syncinterval=minutes)
• Poznámka: Musí být větší než 0

HTTP konfigurace

headers

• Typ: řetězec (dvojice klíč–hodnota oddělené čárkami)
• Výchozí: žádné
• Popis: HTTP hlavičky pro autentizaci nebo metadata
• Příklad: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Formát: key1,value1,key2,value2,...
• Poznámka: Hodnoty URL‑enkódujte. Každá hlavička potřebuje klíč i hodnotu.

Příklady hlaviček:

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

requesttimeout

• Typ: celé číslo (60–86400)
• Výchozí: 60
• Popis: Časový limit požadavku v sekundách
• Příklad: requesttimeout=300
• Poznámka: Musí být mezi 60 a 86400 sekundami (1 minuta až 24 hodin)

Nastavení podle typu dat

Zdravotní metriky

metrics

• Typ: řetězec (čárkou oddělené přesné hodnoty MetricName)
• Výchozí: všechny dostupné metriky
• Popis: Konkrétní zdravotní metriky k zahrnutí (jen pro healthMetrics)
• Příklad: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Poznámka: Použijte přesné interní názvy metrik. Pokud parametr chybí, zahrnou se všechny dostupné metriky.

Časté názvy metrik:

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

Úplný seznam najdete na obrazovce výběru metrik v aplikaci.

Tréninky

includeroutes

• Typ: boolean
• Výchozí: true
• Popis: Zahrnout trasu k tréninkům (jen pro typ workouts)
• Příklad: includeroutes=true

includeworkoutmetadata

• Typ: boolean
• Výchozí: true
• Popis: Zahrnout metriky z tréninku (tep, kalorie atd.) (jen pro typ workouts)
• Příklad: includeworkoutmetadata=true

workoutsmetadatainterval

• Typ: výčet (minutes, seconds)
• Výchozí: minutes
• Popis: Časové seskupení metrik tréninku (jen pro workouts a exportversion v2)
• Příklad: workoutsmetadatainterval=seconds
• Poznámka: Platí jen při datatype=workouts a exportversion=v2

workouttypes

• Typ: řetězec (čárkou oddělené hodnoty UInt)
• Výchozí: prázdné (všechny typy tréninků)
• Popis: Konkrétní typy tréninků k zahrnutí (jen pro workouts)
• Příklad: workouttypes=1,2,3
• Poznámka: Používá identifikátory typů tréninku z HealthKitu

Oznámení

notifyonupdate

• Typ: boolean
• Výchozí: true
• Popis: Oznámení při aktualizaci data v mezipaměti
• Příklad: notifyonupdate=true

notifywhenrun

• Typ: boolean
• Výchozí: true
• Popis: Oznámení při každém spuštění automatizace
• Příklad: notifywhenrun=false

Příklady

Základní automatizace REST API

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

Vytvoří jednoduchou automatizaci, která na uvedený endpoint odešle data ve formátu JSON.

S autentizačními hlavičkami

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

Vytvoří automatizaci s vlastními autentizačními hlavičkami.

Zdravotní metriky s výběrem polí

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

Vytvoří automatizaci, která exportuje jen kroky a tep, agregované po hodinách.

Tréninky s trasou

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

Vytvoří automatizaci pro tréninky s trasou a metrikami tréninku při exportní verzi 2.

Kompletní konfigurace

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

Rozsáhlý příklad se všemi hlavními parametry.

Příklad formátu CSV

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

Vytvoří automatizaci exportu CSV. Formát CSV automaticky zapíná agregaci dat.

URL kódování

Speciální znaky v hodnotách parametrů je třeba URL‑enkódovat. Časté náhrady:

• Mezera: %20
• Čárka: %2C
• Dvojtečka: %3A
• Středník: %3B
• Rovnítko: %3D
• Et: %26
• Plus: %2B

Příklad:

• Původní text: My Automation Name
• Zakódováno: My%20Automation%20Name

Hlavičky:

• Původní: Authorization, Bearer token123
• Zakódováno: Authorization,Bearer%20token123

Většina jazyků a nástrojů má funkce pro URL kódování:

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

Testování deep linků

V Safari (iOS)

1. Na zařízení s iOS otevřete Safari.
2. Do adresního řádku zadejte URL deep linku.
3. Klepněte na Přejít.
4. Měla by se otevřít aplikace a vytvořit automatizaci.

Z Terminálu (macOS / simulátor iOS)

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

Z Xcode

Přidejte breakpoint nebo použijte konzoli ladicího programu:

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

Z aplikace Zkratky

1. Vytvořte novou zkratku.
2. Přidejte akci „Otevřít URL“.
3. Zadejte URL deep linku.
4. Zkratku spusťte.

Řešení problémů

Časté potíže

„Nelze analyzovat URL“

• Ověřte správnost schématu: com.HealthExport://automation
• Zkontrolujte URL kódování všech hodnot parametrů
• Ověřte přepisy názvů parametrů (velikost písmen nehraje roli)

„Neplatná hodnota parametru URL“

• URL musí být platná HTTP/HTTPS adresa
• Zkontrolujte URL kódování
• Ujistěte se, že adresa neobsahuje nepovolené znaky

„Neplatný typ dat“

• Použijte přesné hodnoty: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Zkontrolujte přepis (porovnání je i tak bez ohledu na velikost písmen)

„Neplatný interval synchronizace“

• U REST API používejte jen: minutes, hours, days, weeks
• seconds jen při period=realtime

„Nastavení agregace platí jen pro typ healthMetrics“

• aggregatedata a interval fungují jen s datatype=healthMetrics
• Parametry odeberte nebo změňte typ dat

„Dávkové požadavky platí jen pro REST API ve formátu JSON“

• batchrequests funguje jen při format=json
• Přepněte na JSON nebo parametr batchrequests odeberte

„Nastavení tréninků platí jen pro typ workouts“

• includeroutes, includeworkoutmetadata a workoutsmetadatainterval platí jen pro datatype=workouts
• Změňte typ dat nebo tyto parametry odeberte

„Parametr metrics platí jen pro typ healthMetrics“

• metrics funguje jen s datatype=healthMetrics
• Změňte typ dat nebo parametr odeberte

„Neplatný název metriky“

• Použijte přesné interní názvy (např. „Step Count“, „Heart Rate“)
• Zkontrolujte přepis a velikost písmen
• Platné názvy jsou na obrazovce výběru metrik v aplikaci

„Neplatný časový limit požadavku“

• Musí být v rozmezí 60 až 86400 sekund

„Automatizace vyžaduje název“

• Ujistěte se, že je uveden parametr name
• Po dekódování URL nesmí být hodnota prázdná

Omezení délky URL

Velmi dlouhé URL (hlavně s mnoha metrikami nebo hlavičkami) mohou překročit systémové limity. Zvažte:

• méně metrik v parametru metrics
• méně hlaviček
• kratší hodnoty parametrů kde to jde
• rozdělení složité konfigurace do více jednoduchých automatizací

Priorita parametrů

Při konfliktu parametrů platí:

1. Výběr typu dat (datatype) resetuje příznaky zahrnutí.
2. Formát CSV (format=csv) nastaví aggregatedata=true.
3. Režim period=realtime vyžaduje syncinterval=seconds.
4. Neplatné kombinace skončí chybou validace.

Doporučené postupy

1. Automatická synchronizace (když automatizace běží přes deep link):

   • Nabíjejte zařízení a používejte Zrcadlení iPhonu.
     • Při nabíjení iOS méně omezuje výkon, synchronizace může probíhat častěji.
     • Se zrcadlením se chová iPhone jako odemčený; Health Auto Export pak může číst zdravotní data a spouštět automatizace.

2. Vždy URL‑enkódujte hodnoty se speciálními znaky.

3. Nejdřív zkoušejte jednoduché URL, složitost přidávejte později.

4. Používejte výstižné názvy automatizací.

5. Ověřte adresy, než deep linky generujete programově.

6. Ošetřujte chybové stavy při zpracování deep linků.

7. Dokumentujte formáty deep linků, pokud pro ně píšete nástroje.

8. Mějte na paměti délku URL, pokud posíláte mnoho metrik nebo hlaviček.

9. Testujte na reálných zařízeních i ve simulátoru.

Související dokumentace

• Průvodce automatizací REST API – podrobnosti o automatizacích REST API
• Přehled automatizací – obecné pojmy
• Průvodce ručním exportem – ruční export dat

Podpora

Narazíte-li na problém, který tento průvodce neřeší:

1. Přečtěte text chyby – často ukáže na konkrétní parametr.
2. Ověřte správnost URL kódování.
3. Nejdřív vyzkoušejte minimální URL.
4. V aplikaci použijte tlačítko chatové podpory.