Deep Link automatizacija

Deep link automatizacije omogućuju stvaranje REST API automatizacija programski putem URL shema. Pogodno za skripte, upravljanje konfiguracijom ili vanjske sustave koji moraju postaviti izvoz zdravstvenih podataka.

Pregled

Prilagođena URL shema stvara i konfigurira REST API automatizacije bez ručnog unosa u aplikaciji. Otvaranje deep link URL-a stvara novu automatizaciju s navedenim parametrima.

Primjene:

• Programsko postavljanje iz skripti i alata
• Skupno konfiguriranje
• Integracija s sustavima za upravljanje konfiguracijom
• Brzo postavljanje iz drugih aplikacija ili web stranica
• Testiranje i razvoj

Značajke:

• Stvaranje automatizacija putem URL sheme
• Sve postavke REST API automatizacije
• Provjera parametara s provjerom tipova
• Jasne i detaljne poruke o greškama

Ograničenja

• Samo REST API automatizacije (ne Dropbox, Google Drive itd.)
• Ograničena duljina URL-a može ograničiti jako dugačke popise parametara
• Vrijede ista ograničenja kao za REST API (pozadina, pristup Zdravlju itd.)

Format URL-a

Deep link slijedi ovu strukturu:

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

Osnovni URL: com.HealthExport://automation

Parametri: Svi su opcionalni osim name i url. Veliko/malo slovo nije bitno.

Referenca parametara

Obavezni parametri

url (obavezno)

• Tip: String (valjani URL)
• Opis: Krajnja točka na koju se šalju podaci
• Primjer: https://api.example.com/health-data
• Napomena: Mora biti valjani HTTP/HTTPS URL

name (obavezno)

• Tip: String
• Opis: Naziv automatizacije
• Primjer: My%20Backend%20API (URL kodiranje za razmake)
• Napomena: URL kodirajte ako ima razmake ili posebne znakove

Osnovna konfiguracija

format

• Tip: Enum (json, csv)
• Zadano: json
• Opis: Format izvoza
• Primjer: format=json ili format=csv
• Napomena: CSV automatski uključuje agregaciju podataka

enabled

• Tip: Boolean (true, false, 1, 0, yes, no)
• Zadano: false
• Opis: Je li automatizacija odmah uključena nakon stvaranja
• Primjer: enabled=true

datatype

• Tip: Enum (vidi Dopuštene vrste podataka ispod)
• Zadano: healthMetrics
• Opis: Vrsta zdravstvenih podataka za izvoz
• Primjer: datatype=workouts
• Napomena: Može se odabrati samo jedna vrsta podataka. Postavljanje automatski konfigurira odgovarajuće zastavice uključivanja.

Dopuštene vrste podataka:

• healthMetrics — zdravstvene metrike (koraci, puls, san itd.)
• workouts — vježbanje i aktivnosti
• symptoms — simptomi i zdravstvena stanja
• ecg — EKG očitanja
• heartRateNotification — događaji visokih/niskih otkucaja
• stateOfMind — stanje uma (iOS 18.0+)
• cycleTracking — menstrualni ciklus i reprodukcija
• medications — evidencija lijekova i pridržavanje (iOS 26.0+)

Postavke izvoza

period

• Tip: Enum
• Zadano: none
• Opis: Raspon datuma za izvoz
• Primjer: period=today

Dopuštene vrijednosti:

• none — zadano (cijeli prethodni dan plus tekući)
• lastsync — od zadnje sinkronizacije
• today — danas
• yesterday — jučer
• previous7days — prethodnih 7 dana
• realtime — ažuriranja u stvarnom vremenu (zahtijeva syncinterval u sekundama)

interval

• Tip: Enum
• Zadano: none
• Opis: Vremensko grupiranje/agregacijski interval (vrijedi samo za tip podataka healthMetrics)
• Primjer: interval=hours

Dopuštene vrijednosti:

• none — zadano (bez agregacije)
• minutes — grupiranje po minuti
• hours — grupiranje po satu
• days — grupiranje po danu
• weeks — grupiranje po tjednu
• months — grupiranje po mjesecu
• years — grupiranje po godini

Napomena: Ovaj parametar vrijedi samo kad je datatype=healthMetrics. CSV format uvijek agregira podatke.

aggregatedata

• Tip: Boolean
• Zadano: true (za CSV), false (za JSON)
• Opis: Treba li agregirati/sažeti podatke (vrijedi samo za healthMetrics uz JSON format)
• Primjer: aggregatedata=true
• Napomena: Automatski se postavlja na true kad je format=csv

aggregatesleep

• Tip: Boolean
• Zadano: true
• Opis: Treba li agregirati podatke o snu
• Primjer: aggregatesleep=true

exportversion

• Tip: Enum (v1, v2, 1, 2)
• Zadano: v2
• Opis: Verzija formata izvoza
• Primjer: exportversion=v2
• Napomena: Verzija 2 uključuje proširene podatke o treningu i detaljnije metapodatke

batchrequests

• Tip: Boolean
• Zadano: false
• Opis: Slanje podataka u serijama kroz više zahtjeva (vrijedi samo za REST API uz JSON format)
• Primjer: batchrequests=true
• Napomena: Vrijedi samo kad je format=json i exportDestination=restApi

Učestalost sinkronizacije

syncinterval

• Tip: Enum
• Zadano: minutes
• Opis: Jedinica intervala sinkronizacije (učestalost)
• Primjer: syncinterval=hours

Dopuštene vrijednosti:

• minutes — sinkronizacija svakih N minuta
• hours — sinkronizacija svakih N sati
• days — sinkronizacija svakih N dana
• weeks — sinkronizacija svakih N tjedana
• seconds — vrijedi samo kad je period=realtime

Napomena: Za REST API automatizacije dopušteni su samo minutes, hours, days i weeks, osim ako ne koristite izvoz u stvarnom vremenu.

syncquantity

• Tip: Cijeli broj (pozitivan)
• Zadano: 5
• Opis: Broj intervala između sinkronizacija
• Primjer: syncquantity=10 (sinkronizacija svakih 10 minuta ako je syncinterval=minutes)
• Napomena: Mora biti veći od 0

HTTP konfiguracija

headers

• Tip: String (parovi ključ–vrijednost odvojeni zarezom)
• Zadano: nema
• Opis: HTTP zaglavlja za autentikaciju ili metapodatke
• Primjer: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Format: key1,value1,key2,value2,...
• Napomena: Vrijednosti treba URL kodirati. Svako zaglavlje zahtijeva i ključ i vrijednost.

Primjeri zaglavlja:

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

requesttimeout

• Tip: Cijeli broj (60–86400)
• Zadano: 60
• Opis: Timeout zahtjeva u sekundama
• Primjer: requesttimeout=300
• Napomena: Mora biti između 60 i 86400 sekundi (1 minute do 24 sata)

Postavke po vrsti podataka

Zdravstvene metrike

metrics

• Tip: String (MetricName rawValues odvojeni zarezom)
• Zadano: sve dostupne metrike
• Opis: Koje zdravstvene metrike uključiti (vrijedi samo za tip podataka healthMetrics)
• Primjer: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Napomena: Moraju se koristiti točni MetricName rawValues. Ako parametar nije naveden, uključuju se sve dostupne metrike.

Uobičajeni nazivi metrika:

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

Za cijeli popis dostupnih metrika pogledajte zaslon za odabir metrika u aplikaciji.

Trening

includeroutes

• Tip: Boolean
• Zadano: true
• Opis: Uključuje podatke o ruti za treninge (vrijedi samo za tip podataka workouts)
• Primjer: includeroutes=true

includeworkoutmetadata

• Tip: Boolean
• Zadano: true
• Opis: Uključuje metrike treninga (puls, kalorije itd.) prikupljene tijekom treninga (vrijedi samo za tip podataka workouts)
• Primjer: includeworkoutmetadata=true

workoutsmetadatainterval

• Tip: Enum (minutes, seconds)
• Zadano: minutes
• Opis: Vremensko grupiranje metrika treninga (vrijedi samo za tip podataka workouts uz verziju izvoza v2)
• Primjer: workoutsmetadatainterval=seconds
• Napomena: Vrijedi samo kad je datatype=workouts i exportversion=v2

workouttypes

• Tip: String (UInt vrijednosti odvojene zarezom)
• Zadano: prazno (sve vrste treninga)
• Opis: Koje vrste treninga uključiti (vrijedi samo za tip podataka workouts)
• Primjer: workouttypes=1,2,3
• Napomena: Koriste se identifikatori vrste treninga iz HealthKita

Obavijesti

notifyonupdate

• Tip: Boolean
• Zadano: true
• Opis: Primajte obavijesti kad se predmemorirani podaci ažuriraju
• Primjer: notifyonupdate=true

notifywhenrun

• Tip: Boolean
• Zadano: true
• Opis: Primajte obavijesti pri svakom izvršavanju automatizacije
• Primjer: notifywhenrun=false

Primjeri

Osnovna REST API automatizacija

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

Stvara osnovnu automatizaciju koja šalje JSON na navedenu krajnju točku.

S zaglavljima autentikacije

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

Stvara automatizaciju s prilagođenim HTTP zaglavljima.

Zdravstvene metrike s odabranim metrikama

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

Stvara automatizaciju koja izvozi samo korake i puls, agregirano po satu.

Treningi s podacima o ruti

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

Stvara automatizaciju za treninge s rutom i metrikama treninga, uz verziju izvoza 2.

Potpuni primjer konfiguracije

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

Opsežan primjer s većinom glavnih parametara odjednom.

Primjer CSV formata

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

Stvara automatizaciju CSV izvoza. CSV format automatski uključuje agregaciju podataka.

URL kodiranje

Posebni znakovi u vrijednostima moraju biti URL kodirani. Uobičajeno:

• Space: %20
• Comma: %2C
• Colon: %3A
• Semicolon: %3B
• Equals: %3D
• Ampersand: %26
• Plus: %2B

Primjer:

• Izvorno: My Automation Name
• Kodirano: My%20Automation%20Name

Primjer zaglavlja:

• Izvorno: Authorization, Bearer token123
• Kodirano: Authorization,Bearer%20token123

Većina programskih jezika i alata nudi funkcije za URL kodiranje:

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

Testiranje deep linkova

Iz Safarija (iOS)

1. Otvorite Safari na iOS uređaju
2. Unesite deep link URL u adresnu traku
3. Dodirnite Idi
4. Aplikacija bi se trebala otvoriti i stvoriti automatizaciju

Iz Terminala (macOS / iOS Simulator)

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

Iz Xcodea

Dodajte prekidnu točku ili koristite konzolu debuggera:

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

Iz aplikacije Prečaci (Shortcuts)

1. Stvorite novi prečac
2. Dodajte radnju „Open URLs”
3. Unesite deep link URL
4. Pokrenite prečac

Rješavanje problema

Uobičajeni problemi

"Could not parse the URL"

• Provjerite je li shema URL-a ispravna: com.HealthExport://automation
• Provjerite jesu li sve vrijednosti parametara ispravno URL kodirane
• Provjerite jesu li imena parametara točno napisana (veličina slova nije bitna)

"Invalid URL parameter value"

• Provjerite je li URL valjani HTTP/HTTPS URL
• Provjerite ispravno URL kodiranje
• Provjerite ne sadrži li URL nedopuštene znakove

"Invalid data type"

• Koristite točne vrijednosti tipova podataka: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Provjerite pravopis i velika/mala slova (iako se podudaranje ne razlikuje po veličini slova)

"Invalid sync cadence interval"

• Za REST API koristite samo: minutes, hours, days, weeks
• seconds samo kad je period=realtime

"Aggregation settings are only valid for healthMetrics data type"

• Parametri aggregatedata i interval rade samo uz datatype=healthMetrics
• Uklonite te parametre ili promijenite vrstu podataka

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

• batchrequests radi samo kad je format=json
• Promijenite format u JSON ili uklonite parametar batchrequests

"Workout settings are only valid for workouts data type"

• includeroutes, includeworkoutmetadata i workoutsmetadatainterval rade samo uz datatype=workouts
• Promijenite vrstu podataka u workouts ili uklonite te parametre

"Metrics parameter is only valid for healthMetrics data type"

• Parametar metrics radi samo uz datatype=healthMetrics
• Promijenite vrstu podataka ili uklonite parametar metrics

"Invalid metric name"

• Koristite točne MetricName rawValues (npr. „Step Count”, „Heart Rate”)
• Provjerite pravopis i velika/mala slova
• Pogledajte zaslon za odabir metrika u aplikaciji za valjane nazive

"Invalid request timeout"

• Mora biti između 60 i 86400 sekundi
• Koristite vrijednost u tom rasponu

"A name is required for the automation"

• Obavezno uključite parametar name
• Provjerite da vrijednost nije prazna nakon dekodiranja URL-a

Ograničenje duljine URL-a

Jako dugi URL-ovi (posebno s mnogo metrika ili zaglavlja) mogu prijeći sustavna ograničenja. Razmotrite:

• manji broj metrika u parametru metrics
• manji broj zaglavlja
• kraće vrijednosti parametara gdje je moguće
• podjelu složenih konfiguracija na više jednostavnijih automatizacija

Prednost parametara

Kad se parametri međusobno isključuju:

1. Odabir vrste podataka (datatype) automatski resetira zastavice uključivanja
2. CSV format (format=csv) automatski postavlja aggregatedata=true
3. Razdoblje u stvarnom vremenu (period=realtime) zahtijeva syncinterval=seconds
4. Za nekompatibilne kombinacije bacit će se greške validacije

Najbolje prakse

1. Automatska sinkronizacija (kad se automatizacije pokreću deep linkovima):

   • Punite uređaj i koristite iPhone Mirroring
     • Dok se uređaj puni, iOS manje ograničava performanse, pa se podaci mogu sinkronizirati češće
     • iPhone Mirroring ponaša se kao da je uređaj otključan, pa Health Auto Export može pristupiti zdravstvenim podacima radi automatiziranih radnji

2. Uvijek URL kodirajte vrijednosti parametara koje sadrže posebne znakove

3. Prvo testirajte s jednostavnim URL-ovima, zatim dodajte složenost

4. Koristite opisne nazive radi lakšeg prepoznavanja

5. Provjerite URL-ove prije programskog stvaranja deep linkova

6. Rukujte greškama pri parsiranju deep linkova

7. Dokumentirajte formate deep linkova ako gradite alate koji ih generiraju

8. Razmotrite duljinu URL-a kad uključujete mnogo metrika ili zaglavlja

9. Testirajte na stvarnim uređajima kao i na simulatorima

Povezana dokumentacija

• REST API automatizacija — detalji o REST API automatizacijama
• Pregled automatizacija — opći koncepti automatizacija
• Ručni izvoz — ručni izvoz podataka

Podrška

Ako naiđete na probleme koje ovaj vodič ne pokriva:

1. Provjerite poruku greške radi specifičnih problema s parametrima
2. Provjerite je li URL kodiranje ispravno
3. Prvo testirajte s minimalnim URL-om
4. Koristite gumb Chat Support u aplikaciji za pomoć