Deep link automatizálás

A deep link automatizálásokkal REST API automatizálásokat hozhatsz létre programozottan URL-sémák használatával. Ideális automatizálási szkriptekhez, konfigurációkezeléshez, vagy olyan külső rendszerekhez, amelyeknek konfigurálniuk kell az egészségügyi adatexportot.

Áttekintés

A deep link automatizálások egyedi URL-sémát használnak REST API automatizálások létrehozásához és beállításához anélkül, hogy az alkalmazásban kézzel kellene megadnod a beállításokat. Ha megnyitsz egy deep link URL-t, az alkalmazás automatikusan létrehoz egy új automatizálást a megadott konfigurációval.

Használati esetek:

• Programozott automatizálás-beállítás szkriptekből vagy eszközökből
• Tömeges automatizálás-konfiguráció
• Integráció konfigurációkezelő rendszerekkel
• Gyors beállítás külső alkalmazásokból vagy weboldalakról
• Tesztelési és fejlesztési munkafolyamatok

Fő jellemzők:

• Automatizálások létrehozása URL-sémával
• Minden REST API automatizálás-beállítás konfigurálható
• Típusbiztos paraméter-ellenőrzés
• Részletes hibaüzenetek

Korlátok

• A deep linkek csak REST API automatizálásokat támogatnak (nem Dropbox, Google Drive stb.)
• Az URL hosszkorlátja korlátozhatja a nagyon hosszú paraméterlistákat
• Minden REST API automatizálásra vonatkozó korlát érvényes (háttérfeldolgozás, egészségügyi adatok elérése stb.)

URL-formátum

A deep link URL felépítése:

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

Alap URL: com.HealthExport://automation

Paraméterek: Minden paraméter opcionális, kivéve a name és url paramétereket. A paraméterek kis- és nagybetűre nem érzékenyek.

Paraméterreferencia

Kötelező paraméterek

url (kötelező)

• Típus: Karakterlánc (érvényes URL)
• Leírás: A végpont URL-je, ahová az egészségügyi adatok kerülnek
• Példa: https://api.example.com/health-data
• Megjegyzés: Érvényes HTTP/HTTPS URL kell legyen

name (kötelező)

• Típus: Karakterlánc
• Leírás: Az automatizálás leíró neve
• Példa: My%20Backend%20API (URL-kódolva: „My Backend API”)
• Megjegyzés: URL-kódolni kell, ha szóköz vagy speciális karakter van benne

Alapkonfiguráció

format

• Típus: Enum (json, csv)
• Alapértelmezés: json
• Leírás: Az adat exportformátuma
• Példa: format=json vagy format=csv
• Megjegyzés: CSV formátum automatikusan bekapcsolja az adatösszesítést

enabled

• Típus: Logikai (true, false, 1, 0, yes, no)
• Alapértelmezés: false
• Leírás: Az automatizálás azonnal be legyen-e kapcsolva létrehozás után
• Példa: enabled=true

datatype

• Típus: Enum (lásd az Adattípusok alatt)
• Alapértelmezés: healthMetrics
• Leírás: Exportálandó egészségügyi adat típusa
• Példa: datatype=workouts
• Megjegyzés: Csak egy adattípus választható. Ez automatikusan beállítja a megfelelő include zászlókat.

Érvényes adattípusok:

• healthMetrics – Egészségügyi metrikák (lépések, pulzus, alvás stb.)
• workouts – Mozgásformák és edzések
• symptoms – Tünetek és állapotok
• ecg – Elektrokardiogram felvételek
• heartRateNotification – Magas/alacsony pulzus események
• stateOfMind – Hangulat és mentális állapot bejegyzések (iOS 18.0+)
• cycleTracking – Menstruációs ciklus és reprodukciós adatok
• medications – Gyógyszerbejegyzések és adherencia (iOS 26.0+)

Exportbeállítások

period

• Típus: Enum
• Alapértelmezés: none
• Leírás: Dátumtartomány az adatexporthoz
• Példa: period=today

Érvényes értékek:

• none – Alapértelmezés (teljes előző nap plusz az aktuális nap)
• lastsync – Az utolsó szinkron óta
• today – Aktuális nap
• yesterday – Előző nap
• previous7days – Előző 7 nap
• realtime – Valós idejű frissítések (másodperces szinkronintervallumot igényel)

interval

• Típus: Enum
• Alapértelmezés: none
• Leírás: Időcsoportosítás / összesítési intervallum (csak healthMetrics adattípusnál érvényes)
• Példa: interval=hours

Érvényes értékek:

• none – Alapértelmezés (nincs összesítés)
• minutes – Percenkénti csoportosítás
• hours – Óránkénti csoportosítás
• days – Napi csoportosítás
• weeks – Heti csoportosítás
• months – Havi csoportosítás
• years – Éves csoportosítás

Megjegyzés: Ez a paraméter csak datatype=healthMetrics esetén érvényes. CSV formátum mindig összesíti az adatokat.

aggregatedata

• Típus: Logikai
• Alapértelmezés: true (CSV-nél), false (JSON-nél)
• Leírás: Összesítsük-e az adatokat (csak healthMetrics + JSON formátumnál érvényes)
• Példa: aggregatedata=true
• Megjegyzés: format=csv esetén automatikusan true

aggregatesleep

• Típus: Logikai
• Alapértelmezés: true
• Leírás: Alvásadatok összesítése
• Példa: aggregatesleep=true

exportversion

• Típus: Enum (v1, v2, 1, 2)
• Alapértelmezés: v2
• Leírás: Exportformátum verziója
• Példa: exportversion=v2
• Megjegyzés: A 2-es verzió bővített edzésadatokat és részletesebb metaadatokat tartalmaz

batchrequests

• Típus: Logikai
• Alapértelmezés: false
• Leírás: Adatküldés több kérésben, kötegekben (csak REST API + JSON formátumnál érvényes)
• Példa: batchrequests=true
• Megjegyzés: Csak format=json és exportDestination=restApi esetén érvényes

Szinkrongyakoriság

syncinterval

• Típus: Enum
• Alapértelmezés: minutes
• Leírás: Szinkron intervallum típusa
• Példa: syncinterval=hours

Érvényes értékek:

• minutes – N percenkénti szinkron
• hours – N óránkénti szinkron
• days – N naponta
• weeks – N hetente
• seconds – Csak period=realtime mellett érvényes

Megjegyzés: REST API automatizálásoknál csak a minutes, hours, days és weeks érvényes, kivéve valós idejű exportot.

syncquantity

• Típus: Egész szám (pozitív)
• Alapértelmezés: 5
• Leírás: Hány intervallum teljen el két szinkron között
• Példa: syncquantity=10 (10 percenkénti szinkron, ha syncinterval=minutes)
• Megjegyzés: Nagyobb kell legyen, mint 0

HTTP-konfiguráció

headers

• Típus: Karakterlánc (vesszővel elválasztott kulcs–érték párok)
• Alapértelmezés: Nincs
• Leírás: HTTP fejlécek hitelesítéshez vagy metaadatokhoz
• Példa: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Formátum: key1,value1,key2,value2,...
• Megjegyzés: Az értékeket URL-kódolni kell. Minden fejléchez kulcs és érték is kell.

Példa fejlécek:

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

requesttimeout

• Típus: Egész szám (60–86400)
• Alapértelmezés: 60
• Leírás: Kérés időtúllépése másodpercben
• Példa: requesttimeout=300
• Megjegyzés: 60 és 86400 másodperc között kell legyen (1 perc – 24 óra)

Adattípus-specifikus beállítások

Egészségügyi metrikák beállításai

metrics

• Típus: Karakterlánc (vesszővel elválasztott MetricName rawValues)
• Alapértelmezés: Minden elérhető metrika
• Leírás: Konkrét egészségügyi metrikák (csak healthMetrics adattípusnál)
• Példa: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Megjegyzés: Pontos MetricName rawValues kell. Ha nincs megadva, minden elérhető metrika bekerül.

Gyakori metrikanevek:

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

A teljes listát az alkalmazás metrikaválasztó képernyőjén találod.

Edzésbeállítások

includeroutes

• Típus: Logikai
• Alapértelmezés: true
• Leírás: Útvonaladatok belefoglalása edzésekhez (csak workouts adattípusnál)
• Példa: includeroutes=true

includeworkoutmetadata

• Típus: Logikai
• Alapértelmezés: true
• Leírás: Edzésmetrikák belefoglalása (pulzus, kalória stb.) az edzés alatt (csak workouts)
• Példa: includeworkoutmetadata=true

workoutsmetadatainterval

• Típus: Enum (minutes, seconds)
• Alapértelmezés: minutes
• Leírás: Időcsoportosítás edzésmetrikákhoz (csak workouts + exportv2)
• Példa: workoutsmetadatainterval=seconds
• Megjegyzés: Csak datatype=workouts és exportversion=v2 mellett érvényes

workouttypes

• Típus: Karakterlánc (vesszővel elválasztott UInt értékek)
• Alapértelmezés: Üres (minden edzéstípus)
• Leírás: Konkrét edzéstípusok (csak workouts)
• Példa: workouttypes=1,2,3
• Megjegyzés: HealthKit edzéstípus-azonosítók

Értesítések

notifyonupdate

• Típus: Logikai
• Alapértelmezés: true
• Leírás: Értesítés, ha a gyorsítótárazott adat frissül
• Példa: notifyonupdate=true

notifywhenrun

• Típus: Logikai
• Alapértelmezés: true
• Leírás: Értesítés minden automatizálás-futtatáskor
• Példa: notifywhenrun=false

Példák

Alap REST API automatizálás

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

Egyszerű automatizálást hoz létre, amely JSON adatot küld a megadott végpontra.

Hitelesítési fejlécekkel

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

Egyedi hitelesítési fejlécekkel rendelkező automatizálást hoz létre.

Egészségügyi metrikák konkrét metrikákkal

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

Csak lépésszámot és pulzust exportál, óránként összesítve.

Edzések útvonaladattal

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

Edzésautomatikus export útvonal- és edzésmetrika-adatokkal, 2-es exportverzióval.

Teljes konfigurációs példa

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

Átfogó példa a fő paraméterekkel.

CSV formátum példa

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

CSV export automatizálást hoz létre. A CSV formátum automatikusan bekapcsolja az adatösszesítést.

URL-kódolás

A paraméterértékekben lévő speciális karaktereket URL-kódolni kell. Gyakori kódolások:

• Szóköz: %20
• Vessző: %2C
• Kettőspont: %3A
• Pontosvessző: %3B
• Egyenlőség: %3D
• És jel: %26
• Plusz: %2B

Példa:

• Eredeti: My Automation Name
• Kódolt: My%20Automation%20Name

Fejléc példa:

• Eredeti: Authorization, Bearer token123
• Kódolt: Authorization,Bearer%20token123

A legtöbb programozási nyelv és eszköz biztosít URL-kódoló függvényt:

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

Deep linkek tesztelése

Safariból (iOS)

1. Nyisd meg a Safarit iOS-eszközön
2. Írd be a deep link URL-t a címsorba
3. Koppints a Ugrásra
4. Az alkalmazásnak meg kell nyílnia, és létre kell hoznia az automatizálást

Terminálból (macOS / iOS szimulátor)

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

Xcode-ból

Töréspont vagy a debugger konzol:

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

Parancsok alkalmazásból

1. Hozz létre egy új parancsot
2. Add hozzá az „URL-ek megnyitása” műveletet
3. Add meg a deep link URL-t
4. Futtasd a parancsot

Hibaelhárítás

Gyakori problémák

„Could not parse the URL”

• Ellenőrizd, hogy helyes-e az URL-séma: com.HealthExport://automation
• Minden paraméterérték megfelelően legyen URL-kódolva
• A paraméternevek helyesek legyenek (kis- és nagybetű nem számít)

„Invalid URL parameter value”

• Az URL legyen érvényes HTTP/HTTPS URL
• Ellenőrizd az URL-kódolást
• Ne tartalmazzon érvénytelen karaktereket az URL

„Invalid data type”

• Pontos adattípus-értékek: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Ellenőrizd a helyesírást (a kis- és nagybetű egyeztetése támogatott)

„Invalid sync cadence interval”

• REST API-nál csak: minutes, hours, days, weeks
• seconds csak period=realtime mellett

„Aggregation settings are only valid for healthMetrics data type”

• Az aggregatedata és interval paraméterek csak datatype=healthMetrics mellett működnek
• Távolítsd el ezeket a paramétereket, vagy változtasd meg az adattípust

„Batch requests are only valid for REST API with JSON format”

• A batchrequests csak format=json mellett működik
• Válts JSON-ra, vagy távolítsd el a batchrequests paramétert

„Workout settings are only valid for workouts data type”

• Az includeroutes, includeworkoutmetadata és workoutsmetadatainterval csak datatype=workouts mellett érvényes
• Válts workouts adattípusra, vagy távolítsd el ezeket

„Metrics parameter is only valid for healthMetrics data type”

• A metrics paraméter csak datatype=healthMetrics mellett működik
• Változtasd az adattípust, vagy távolítsd el a metrics paramétert

„Invalid metric name”

• Pontos MetricName rawValues (pl. „Step Count”, „Heart Rate”)
• Ellenőrizd a helyesírást és a nagybetűket
• Az érvényes neveket az alkalmazás metrikaválasztó képernyőjén találod

„Invalid request timeout”

• 60 és 86400 másodperc között kell legyen
• Használj értéket ebben a tartományban

„A name is required for the automation”

• A name paraméternek szerepelnie kell
• Az érték URL-dekódolás után ne legyen üres

URL hosszkorlátok

Nagyon hosszú URL-ek (sok metrika vagy fejléc esetén) túlléphetik a rendszer korlátjait. Fontold meg:

• Kevesebb metrika a metrics paraméterben
• Kevesebb fejléc
• Rövidebb paraméterértékek, ahol lehetséges
• Összetett konfigurációk szétválasztása több egyszerűbb automatizálásra

Paraméterek precedenciája

Ha több paraméter ütközik:

1. Az adattípus (datatype) automatikusan visszaállítja az include zászlókat
2. CSV formátum (format=csv) automatikusan aggregatedata=true-t állít
3. Valós idejű időszak (period=realtime) megköveteli a syncinterval=seconds értéket
4. Nem kompatibilis kombinációkra validációs hibák dobódnak

Ajánlott gyakorlat

1. Automatikus szinkron (deep linkekkel indított automatizálásoknál):

   • Töltsd az eszközt, és használd az iPhone tükrözést
     • Töltés közben az iOS kevésbé korlátozza a teljesítményt
     • Az iPhone tükrözéssel az eszköz úgy viselkedik, mintha fel lenne oldva

2. Mindig URL-kódolj speciális karaktert tartalmazó paraméterértékeket

3. Először egyszerű URL-lel tesztelj, majd bonyolítsd

4. Használj leíró neveket a könnyebb azonosításhoz

5. Ellenőrizd az URL-eket programozott deep link létrehozás előtt

6. Kezeld szépen a hibákat deep link feldolgozáskor

7. Dokumentáld a deep link formátumokat, ha eszközöket építesz, amelyek generálják őket

8. Gondolj az URL hosszára sok metrika vagy fejléc esetén

9. Tesztelj valódi eszközön is, nem csak szimulátoron

Kapcsolódó dokumentáció

• REST API automatizálás – Részletes információ REST API automatizálásokról
• Automatizálások áttekintése – Általános automatizálási fogalmak
• Kézi export – Egészségügyi adatok manuális exportálása

Támogatás

Ha olyan problémád van, amit ez az útmutató nem fed le:

1. Nézd meg a hibaüzenetet a konkrét paraméterproblémákért
2. Ellenőrizd az URL-kódolást
3. Először minimal URL-lel tesztelj
4. Használd az alkalmazás Csevegés az ügyfélszolgálattal gombját segítségért