HealthyApps Help Center

Automatizare deep link

Creați automatizări programatic folosind scheme URL.

Last updated: April 5, 2026

Pe această pagină

Automatizările deep link permit crearea de automatizări REST API prin scheme URL. Este util pentru scripturi, gestionarea configurației sau integrarea cu sisteme externe care trebuie să configureze exporturi de date de sănătate.

Prezentare generală

Deep link-urile folosesc o schemă URL personalizată pentru a crea și configura automatizări REST API fără a introduce manual setările în aplicație. La deschiderea URL-ului, aplicația creează o automatizare nouă cu configurația specificată.

Cazuri de utilizare:

  • Configurare programatică din scripturi sau unelte
  • Configurare în masă a automatizărilor
  • Integrare cu sisteme de gestionare a configurației
  • Configurare rapidă din aplicații sau site-uri externe
  • Fluxuri de testare și dezvoltare

Caracteristici:

  • Creare prin schemă URL
  • Toate setările unei automatizări REST API
  • Validare tipată a parametrilor
  • Mesaje de eroare detaliate

Limitări

  • Deep link-urile suportă doar automatizări REST API (nu Dropbox, Google Drive etc.)
  • Limitele de lungime URL pot restrânge liste foarte lungi de parametri
  • Se aplică toate limitările automatizărilor REST API (procesare în fundal, acces la date de sănătate etc.)

Format URL

Structura deep link-ului:

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

URL de bază: com.HealthExport://automation

Parametri: Toți sunt opționali cu excepția lui name și url. Numele parametrilor nu țin cont de majuscule/minuscule.

Referință parametri

Parametri obligatorii

url (obligatoriu)

  • Tip: String (URL valid)
  • Descriere: Endpointul unde se trimit datele de sănătate
  • Exemplu: https://api.example.com/health-data
  • Notă: Trebuie să fie HTTP/HTTPS valid

name (obligatoriu)

  • Tip: String
  • Descriere: Nume descriptiv al automatizării
  • Exemplu: My%20Backend%20API (codare URL: „My Backend API”)
  • Notă: Codare URL dacă există spații sau caractere speciale

Configurare de bază

format

  • Tip: Enum (json, csv)
  • Implicit: json
  • Descriere: Formatul exportului
  • Exemplu: format=json sau format=csv
  • Notă: CSV activează automat agregarea datelor

enabled

  • Tip: Boolean (true, false, 1, 0, yes, no)
  • Implicit: false
  • Descriere: Dacă automatizarea este activată imediat după creare
  • Exemplu: enabled=true

datatype

  • Tip: Enum (vezi tipurile de mai jos)
  • Implicit: healthMetrics
  • Descriere: Tipul de date exportate
  • Exemplu: datatype=workouts
  • Notă: Un singur tip; setarea configurează steagurile include corespunzătoare

Tipuri valide:

  • healthMetrics — metrici (pași, puls, somn etc.)
  • workouts — antrenamente
  • symptoms — simptome
  • ecg — ECG
  • heartRateNotification — evenimente puls ridicat/scăzut
  • stateOfMind — stare de spirit (iOS 18.0+)
  • cycleTracking — ciclu și sănătate reproductivă
  • medications — medicamente (iOS 26.0+)

Setări export

period

  • Tip: Enum
  • Implicit: none
  • Descriere: Interval de date
  • Exemplu: period=today

Valori:

  • none — implicit (ziua anterioară completă plus ziua curentă)
  • lastsync — de la ultima sincronizare
  • today — ziua curentă
  • yesterday — ziua anterioară
  • previous7days — ultimele 7 zile
  • realtime — actualizări în timp real (necesită interval de sincronizare în secunde)

interval

  • Tip: Enum
  • Implicit: none
  • Descriere: Grupare/agregare temporală (doar pentru datatype=healthMetrics)
  • Exemplu: interval=hours

Valori:

  • none — fără agregare implicită
  • minutes — pe minut
  • hours — pe oră
  • days — pe zi
  • weeks — pe săptămână
  • months — pe lună
  • years — pe an

Notă: Doar cu datatype=healthMetrics. Formatul CSV agregă întotdeauna.

aggregatedata

  • Tip: Boolean
  • Implicit: true (CSV), false (JSON)
  • Descriere: Agregare/rezumat (doar metrici + JSON)
  • Exemplu: aggregatedata=true
  • Notă: Devine true automat dacă format=csv

aggregatesleep

  • Tip: Boolean
  • Implicit: true
  • Descriere: Agregare date somn
  • Exemplu: aggregatesleep=true

exportversion

  • Tip: Enum (v1, v2, 1, 2)
  • Implicit: v2
  • Descriere: Versiune format export
  • Exemplu: exportversion=v2
  • Notă: Versiunea 2 include antrenamente îmbunătățite și metadate mai detaliate

batchrequests

  • Tip: Boolean
  • Implicit: false
  • Descriere: Trimite date în loturi pe mai multe cereri (REST API + JSON)
  • Exemplu: batchrequests=true
  • Notă: Doar cu format=json și destinație REST API

Ritm sincronizare

syncinterval

  • Tip: Enum
  • Implicit: minutes
  • Descriere: Unitatea pentru ritmul de sincronizare
  • Exemplu: syncinterval=hours

Valori:

  • minutes — la fiecare N minute
  • hours — la fiecare N ore
  • days — la fiecare N zile
  • weeks — la fiecare N săptămâni
  • seconds — doar cu period=realtime

Notă: Pentru REST API, în general minutes, hours, days, weeks, exceptând exportul în timp real.

syncquantity

  • Tip: Integer pozitiv
  • Implicit: 5
  • Descriere: Multiplicatorul intervalului
  • Exemplu: syncquantity=10 cu syncinterval=minutes = la 10 minute
  • Notă: Trebuie să fie > 0

Configurare HTTP

headers

  • Tip: String (perechi cheie-valoare separate prin virgulă)
  • Implicit: niciunul
  • Descriere: Antete HTTP
  • Exemplu: headers=Authorization,Bearer%20token123,X-API-Key,abc123
  • Format: key1,value1,key2,value2,...
  • Notă: Valorile trebuie codate URL; fiecare antet are cheie și valoare

Exemple de antete:

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

requesttimeout

  • Tip: Integer (60–86400)
  • Implicit: 60
  • Descriere: Timeout în secunde
  • Exemplu: requesttimeout=300
  • Notă: Între 60 și 86400 (1 minut–24 ore)

Setări specifice tipului de date

Metrici de sănătate

metrics
  • Tip: String (MetricName separate prin virgulă, rawValues)
  • Implicit: toate metricile disponibile
  • Descriere: Metrici incluse (doar healthMetrics)
  • Exemplu: metrics=Step%20Count,Heart%20Rate,Active%20Energy
  • Notă: Valori exacte MetricName. Dacă lipsește, se includ toate.

Numele uzuale (exemple):

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

Lista completă apare în ecranul de selecție a metricilor din aplicație.

Antrenamente

includeroutes
  • Tip: Boolean
  • Implicit: true
  • Descriere: Include trasee (doar workouts)
  • Exemplu: includeroutes=true
includeworkoutmetadata
  • Tip: Boolean
  • Implicit: true
  • Descriere: Include metrici din antrenament (puls, calorii etc.) — doar workouts
  • Exemplu: includeworkoutmetadata=true
workoutsmetadatainterval
  • Tip: Enum (minutes, seconds)
  • Implicit: minutes
  • Descriere: Grupare metrici antrenament (workouts + exportversion=v2)
  • Exemplu: workoutsmetadatainterval=seconds
  • Notă: Doar cu datatype=workouts și exportversion=v2
workouttypes
  • Tip: String (UInt separate prin virgulă)
  • Implicit: gol (toate tipurile)
  • Descriere: Tipuri de antrenament incluse (workouts)
  • Exemplu: workouttypes=1,2,3
  • Notă: Identificatori HealthKit pentru tipul de antrenament

Notificări

notifyonupdate

  • Tip: Boolean
  • Implicit: true
  • Descriere: Notificare la actualizarea cache-ului
  • Exemplu: notifyonupdate=true

notifywhenrun

  • Tip: Boolean
  • Implicit: true
  • Descriere: Notificare la fiecare execuție
  • Exemplu: notifywhenrun=false

Exemple

Automatizare REST API de bază

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

Creează o automatizare care trimite JSON la endpoint.

Cu antete de autentificare

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

Automatizare cu antete personalizate.

Metrici specifice

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

Doar pași și puls, agregat pe ore.

Antrenamente cu traseu

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

Antrenamente cu traseu și metrici, versiune export 2.

Exemplu complet

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

Exemplu cu majoritatea parametrilor importanți.

CSV

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

CSV — agregarea este activată automat.

Codare URL

Caracterele speciale trebuie codate. Exemple:

  • Spațiu: %20
  • Virgulă: %2C
  • Două puncte: %3A
  • Punct și virgulă: %3B
  • Egal: %3D
  • Ampersand: %26
  • Plus: %2B

Exemplu:

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

Antete:

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

Multe limbaje oferă funcții de codare:

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

Din Safari (iOS)

  1. Deschideți Safari
  2. Introduceți URL-ul deep link în bara de adresă
  3. Atingeți Go
  4. Aplicația ar trebui să se deschidă și să creeze automatizarea

Depanare

Probleme frecvente

„Nu s-a putut analiza URL-ul”

  • Schema: com.HealthExport://automation
  • Valori codate corect
  • Numele parametrilor corecte (nu țin cont de majuscule)

„Valoare parametru URL invalidă”

  • URL HTTP/HTTPS valid pentru url
  • Codare corectă
  • Fără caractere interzise

„Tip de date invalid”

  • Valori exacte: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications

„Interval sincronizare invalid”

  • REST API: minutes, hours, days, weeks
  • seconds doar cu period=realtime

„Setările de agregare sunt valide doar pentru healthMetrics”

  • aggregatedata și interval doar cu datatype=healthMetrics

„Batch requests sunt valide doar pentru REST API cu JSON”

  • batchrequests doar cu format=json

„Setările de antrenament sunt valide doar pentru workouts”

  • includeroutes, includeworkoutmetadata, workoutsmetadatainterval doar cu datatype=workouts

„Parametrul metrics este valabil doar pentru healthMetrics”

  • metrics doar cu datatype=healthMetrics

„Nume metrică invalid”

  • MetricName rawValues exacte (ex.: „Step Count”, „Heart Rate”)
  • Consultați ecranul din aplicație

„Timeout cerere invalid”

  • Între 60 și 86400 secunde

„Este necesar un nume pentru automatizare”

  • Parametrul name prezent și nevid după decodare

Limite de lungime URL

URL-uri foarte lungi (multe metrici sau antete) pot depăși limitele sistemului. Soluții:

  • Mai puține metrici în metrics
  • Mai puține antete
  • Valori mai scurte unde se poate
  • Configurații împărțite în mai multe automatizări

Precedență parametri

La conflict:

  1. datatype resetează steagurile include
  2. format=csv impune aggregatedata=true
  3. period=realtime cere syncinterval=seconds
  4. Combinații incompatibile generează erori de validare

Bune practici

  1. Sincronizare (când automatizările sunt create prin deep link): încărcare dispozitiv + iPhone Mirroring pentru acces la date ca la deblocat.

  2. Codificați întotdeauna valorile cu caractere speciale.

  3. Testați cu URL-uri simple, apoi complicați.

  4. Folosiți nume descriptive.

  5. Validați URL-urile înainte de generare programatică.

  6. Tratați erorile la parsarea deep link-urilor.

  7. Documentați formatele dacă construiți unelte generatoare.

  8. Luați în calcul lungimea cu multe metrici sau antete.

  9. Testați pe dispozitive reale, nu doar pe simulatoare.

Documentație conexă

Asistență

Dacă problema nu este acoperită aici:

  1. Citiți mesajul de eroare pentru parametrul indicat
  2. Verificați codarea URL
  3. Testați cu un URL minimal
  4. Folosiți Chat Support din aplicație