HealthyApps Help Center

Automazione Deep Link

Crea automazioni mediante programmazione utilizzando schemi URL.

Last updated: February 7, 2026

On this page

Le automazioni deep link ti consentono di creare automazioni API REST mediante programmazione utilizzando schemi URL. Questo è ideale per script di automazione, gestione della configurazione o integrazione con sistemi esterni che devono configurare esportazioni di dati sanitari.

Panoramica

Le automazioni deep link utilizzano uno schema URL personalizzato per creare e configurare automazioni API REST senza inserire manualmente le impostazioni nell'app. Quando apri un URL deep link, l'app crea automaticamente una nuova automazione con la configurazione specificata.

Casi d'uso:

  • Configurazione programmatica di automazioni da script o strumenti
  • Configurazione bulk di automazioni
  • Integrazione con sistemi di gestione della configurazione
  • Configurazione rapida da applicazioni o siti web esterni
  • Flussi di lavoro di test e sviluppo

Funzionalità principali:

  • Crea automazioni tramite schema URL
  • Configura tutte le impostazioni di automazione API REST
  • Validazione dei parametri type-safe
  • Messaggi di errore completi

Limitazioni

  • I deep link supportano solo automazioni API REST (non Dropbox, Google Drive, ecc.)
  • I limiti di lunghezza URL possono limitare elenchi di parametri molto lunghi
  • Si applicano tutte le limitazioni delle automazioni API REST (elaborazione in background, accesso ai dati sanitari, ecc.)

Formato URL

L'URL deep link segue questa struttura:

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

URL base: com.HealthExport://automation

Parametri: Tutti i parametri sono opzionali eccetto name e url. I parametri non distinguono tra maiuscole e minuscole.

Riferimento parametri

Parametri richiesti

url (richiesto)

  • Tipo: String (URL valida)
  • Descrizione: L'URL dell'endpoint dove verranno inviati i dati sanitari
  • Esempio: https://api.example.com/health-data
  • Nota: Deve essere un URL HTTP/HTTPS valido

name (richiesto)

  • Tipo: String
  • Descrizione: Un nome descrittivo per l'automazione
  • Esempio: My%20Backend%20API (codificato in URL: "My Backend API")
  • Nota: Deve essere codificato in URL se contiene spazi o caratteri speciali

Configurazione di base

format

  • Tipo: Enum (json, csv)
  • Predefinito: json
  • Descrizione: Formato di esportazione per i dati
  • Esempio: format=json o format=csv
  • Nota: Il formato CSV abilita automaticamente l'aggregazione dei dati

enabled

  • Tipo: Boolean (true, false, 1, 0, yes, no)
  • Predefinito: false
  • Descrizione: Se l'automazione è abilitata immediatamente dopo la creazione
  • Esempio: enabled=true

datatype

  • Tipo: Enum (vedi Tipi di dati sotto)
  • Predefinito: healthMetrics
  • Descrizione: Tipo di dati sanitari da esportare
  • Esempio: datatype=workouts
  • Nota: Può essere selezionato solo un tipo di dati. L'impostazione configura automaticamente i flag di inclusione appropriati.

Tipi di dati validi:

  • healthMetrics - Metriche sanitarie (passi, frequenza cardiaca, sonno, ecc.)
  • workouts - Attività di esercizio e fitness
  • symptoms - Sintomi e condizioni di salute
  • ecg - Letture elettrocardiogramma
  • heartRateNotification - Eventi di frequenza cardiaca alta/bassa
  • stateOfMind - Voci di umore e stato mentale (iOS 18.0+)
  • cycleTracking - Dati del ciclo mestruale e salute riproduttiva
  • medications - Registri di farmaci e aderenza (iOS 26.0+)

Impostazioni di esportazione

period

  • Tipo: Enum
  • Predefinito: none
  • Descrizione: Intervallo di date per l'esportazione dei dati
  • Esempio: period=today

Valori validi:

  • none - Predefinito (giorno precedente completo più giorno corrente)
  • lastsync - Dall'ultima sincronizzazione
  • today - Giorno corrente
  • yesterday - Giorno precedente
  • previous7days - Ultimi 7 giorni
  • realtime - Aggiornamenti in tempo reale (richiede intervallo di sincronizzazione in secondi)

interval

  • Tipo: Enum
  • Predefinito: none
  • Descrizione: Intervallo di raggruppamento/aggregazione temporale (valido solo per il tipo di dati healthMetrics)
  • Esempio: interval=hours

Valori validi:

  • none - Predefinito (nessuna aggregazione)
  • minutes - Raggruppa per minuto
  • hours - Raggruppa per ora
  • days - Raggruppa per giorno
  • weeks - Raggruppa per settimana
  • months - Raggruppa per mese
  • years - Raggruppa per anno

Nota: Questo parametro è valido solo quando datatype=healthMetrics. Il formato CSV aggrega sempre i dati.

aggregatedata

  • Tipo: Boolean
  • Predefinito: true (per CSV), false (per JSON)
  • Descrizione: Se aggregare/riassumere i dati (valido solo per healthMetrics con formato JSON)
  • Esempio: aggregatedata=true
  • Nota: Impostato automaticamente a true quando format=csv

aggregatesleep

  • Tipo: Boolean
  • Predefinito: true
  • Descrizione: Se aggregare i dati del sonno
  • Esempio: aggregatesleep=true

exportversion

  • Tipo: Enum (v1, v2, 1, 2)
  • Predefinito: v2
  • Descrizione: Versione del formato di esportazione
  • Esempio: exportversion=v2
  • Nota: La versione 2 include dati di allenamento migliorati e metadati più dettagliati

batchrequests

  • Tipo: Boolean
  • Predefinito: false
  • Descrizione: Invia dati in batch su più richieste (valido solo per API REST con formato JSON)
  • Esempio: batchrequests=true
  • Nota: Valido solo quando format=json e exportDestination=restApi

Cadenza di sincronizzazione

syncinterval

  • Tipo: Enum
  • Predefinito: minutes
  • Descrizione: Intervallo per la cadenza di sincronizzazione
  • Esempio: syncinterval=hours

Valori validi:

  • minutes - Sincronizza ogni N minuti
  • hours - Sincronizza ogni N ore
  • days - Sincronizza ogni N giorni
  • weeks - Sincronizza ogni N settimane
  • seconds - Valido solo quando period=realtime

Nota: Per le automazioni API REST, solo minutes, hours, days e weeks sono validi a meno che non si utilizzi l'esportazione in tempo reale.

syncquantity

  • Tipo: Integer (positivo)
  • Predefinito: 5
  • Descrizione: Numero di intervalli tra le sincronizzazioni
  • Esempio: syncquantity=10 (sincronizza ogni 10 minuti se syncinterval=minutes)
  • Nota: Deve essere maggiore di 0

Configurazione HTTP

headers

  • Tipo: String (coppie chiave-valore separate da virgola)
  • Predefinito: Nessuno
  • Descrizione: Intestazioni HTTP per autenticazione o metadati
  • Esempio: headers=Authorization,Bearer%20token123,X-API-Key,abc123
  • Formato: key1,value1,key2,value2,...
  • Nota: I valori devono essere codificati in URL. Ogni intestazione richiede sia una chiave che un valore.

Esempi di intestazioni:

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

requesttimeout

  • Tipo: Integer (60-86400)
  • Predefinito: 60
  • Descrizione: Timeout della richiesta in secondi
  • Esempio: requesttimeout=300
  • Nota: Deve essere tra 60 e 86400 secondi (1 minuto a 24 ore)

Impostazioni specifiche del tipo di dati

Impostazioni metriche sanitarie

metrics
  • Tipo: String (valori rawValues MetricName separati da virgola)
  • Predefinito: Tutte le metriche disponibili
  • Descrizione: Metriche sanitarie specifiche da includere (valido solo per il tipo di dati healthMetrics)
  • Esempio: metrics=Step%20Count,Heart%20Rate,Active%20Energy
  • Nota: Deve utilizzare valori rawValues esatti di MetricName. Se non specificato, vengono incluse tutte le metriche disponibili.

Nomi di metriche comuni:

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

Vedi la schermata di selezione delle metriche dell'app per l'elenco completo delle metriche disponibili.

Impostazioni allenamenti

includeroutes
  • Tipo: Boolean
  • Predefinito: true
  • Descrizione: Includi dati di percorso per gli allenamenti (valido solo per il tipo di dati workouts)
  • Esempio: includeroutes=true
includeworkoutmetadata
  • Tipo: Boolean
  • Predefinito: true
  • Descrizione: Includi metriche di allenamento (frequenza cardiaca, calorie, ecc.) raccolte durante gli allenamenti (valido solo per il tipo di dati workouts)
  • Esempio: includeworkoutmetadata=true
workoutsmetadatainterval
  • Tipo: Enum (minutes, seconds)
  • Predefinito: minutes
  • Descrizione: Raggruppamento temporale per le metriche di allenamento (valido solo per il tipo di dati workouts con exportVersion v2)
  • Esempio: workoutsmetadatainterval=seconds
  • Nota: Valido solo quando datatype=workouts e exportversion=v2
workouttypes
  • Tipo: String (valori UInt separati da virgola)
  • Predefinito: Vuoto (tutti i tipi di allenamento)
  • Descrizione: Tipi di allenamento specifici da includere (valido solo per il tipo di dati workouts)
  • Esempio: workouttypes=1,2,3
  • Nota: Utilizza identificatori di tipo di allenamento HealthKit

Notifiche

notifyonupdate

  • Tipo: Boolean
  • Predefinito: true
  • Descrizione: Ricevi notifiche quando i dati in cache vengono aggiornati
  • Esempio: notifyonupdate=true

notifywhenrun

  • Tipo: Boolean
  • Predefinito: true
  • Descrizione: Ricevi notifiche ogni volta che l'automazione viene eseguita
  • Esempio: notifywhenrun=false

Esempi

Automazione API REST di base

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

Crea un'automazione di base che invia dati JSON all'endpoint specificato.

Con intestazioni di autenticazione

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

Crea un'automazione con intestazioni di autenticazione personalizzate.

Metriche sanitarie con metriche specifiche

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

Crea un'automazione che esporta solo passi e frequenza cardiaca, aggregati per ora.

Allenamenti con dati di percorso

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

Crea un'automazione per allenamenti con dati di percorso e metriche di allenamento, utilizzando la versione di esportazione 2.

Esempio di configurazione completa

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

Un esempio completo con tutti i parametri principali configurati.

Esempio formato CSV

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

Crea un'automazione di esportazione CSV. Nota che il formato CSV abilita automaticamente l'aggregazione dei dati.

Codifica URL

I caratteri speciali nei valori dei parametri devono essere codificati in URL. Codifiche comuni:

  • Spazio: %20
  • Virgola: %2C
  • Due punti: %3A
  • Punto e virgola: %3B
  • Uguale: %3D
  • E commerciale: %26
  • Più: %2B

Esempio:

  • Originale: My Automation Name
  • Codificato: My%20Automation%20Name

Esempio intestazioni:

  • Originale: Authorization, Bearer token123
  • Codificato: Authorization,Bearer%20token123

La maggior parte dei linguaggi di programmazione e strumenti fornisce funzioni di codifica URL:

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

Da Safari (iOS)

  1. Apri Safari sul tuo dispositivo iOS
  2. Inserisci l'URL deep link nella barra degli indirizzi
  3. Tocca Vai
  4. L'app dovrebbe aprirsi e creare l'automazione

Da Terminale (macOS/Simulatore iOS)

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

Da Xcode

Aggiungi un punto di interruzione o usa la console del debugger:

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

Dall'app Scorciatoie

  1. Crea una nuova scorciatoia
  2. Aggiungi l'azione "Apri URL"
  3. Inserisci il tuo URL deep link
  4. Esegui la scorciatoia

Risoluzione dei problemi

Problemi comuni

"Impossibile analizzare l'URL"

  • Verifica che lo schema URL sia corretto: com.HealthExport://automation
  • Controlla che tutti i valori dei parametri siano correttamente codificati in URL
  • Assicurati che i nomi dei parametri siano scritti correttamente (non distinguono tra maiuscole e minuscole)

"Valore parametro URL non valido"

  • Verifica che l'URL sia un URL HTTP/HTTPS valido
  • Controlla la codifica URL appropriata
  • Assicurati che l'URL non contenga caratteri non validi

"Tipo di dati non valido"

  • Usa valori esatti del tipo di dati: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
  • Controlla ortografia e maiuscole/minuscole (sebbene sia supportata la corrispondenza senza distinzione tra maiuscole e minuscole)

"Intervallo cadenza sincronizzazione non valido"

  • Per API REST, usa solo: minutes, hours, days, weeks
  • Usa seconds solo quando period=realtime

"Le impostazioni di aggregazione sono valide solo per il tipo di dati healthMetrics"

  • I parametri aggregatedata e interval funzionano solo con datatype=healthMetrics
  • Rimuovi questi parametri o cambia il tipo di dati

"Le richieste batch sono valide solo per API REST con formato JSON"

  • batchrequests funziona solo quando format=json
  • Cambia il formato in JSON o rimuovi il parametro batchrequests

"Le impostazioni di allenamento sono valide solo per il tipo di dati workouts"

  • includeroutes, includeworkoutmetadata e workoutsmetadatainterval funzionano solo con datatype=workouts
  • Cambia il tipo di dati in workouts o rimuovi questi parametri

"Il parametro metrics è valido solo per il tipo di dati healthMetrics"

  • Il parametro metrics funziona solo con datatype=healthMetrics
  • Cambia il tipo di dati o rimuovi il parametro metrics

"Nome metrica non valido"

  • Usa valori rawValues esatti di MetricName (ad esempio, "Step Count", "Heart Rate")
  • Controlla ortografia e maiuscole
  • Vedi la schermata di selezione delle metriche dell'app per i nomi validi

"Timeout richiesta non valido"

  • Deve essere tra 60 e 86400 secondi
  • Usa un valore all'interno di questo intervallo

"È richiesto un nome per l'automazione"

  • Assicurati che il parametro name sia incluso
  • Controlla che il valore non sia vuoto dopo la decodifica URL

Limitazioni di lunghezza URL

URL molto lunghi (specialmente con molte metriche o intestazioni) possono superare i limiti del sistema. Considera:

  • Usare meno metriche nel parametro metrics
  • Ridurre il numero di intestazioni
  • Usare valori di parametri più corti quando possibile
  • Dividere configurazioni complesse in più automazioni più semplici

Precedenza dei parametri

Quando più parametri entrano in conflitto:

  1. La selezione del tipo di dati (datatype) reimposta automaticamente i flag di inclusione
  2. Il formato CSV (format=csv) imposta automaticamente aggregatedata=true
  3. Il periodo in tempo reale (period=realtime) richiede syncinterval=seconds
  4. Verranno generati errori di validazione per combinazioni incompatibili

Best practice

  1. Codifica sempre in URL i valori dei parametri contenenti caratteri speciali
  2. Testa prima con URL semplici, poi aggiungi complessità
  3. Usa nomi descrittivi per facilitare l'identificazione
  4. Valida gli URL prima di creare deep link mediante programmazione
  5. Gestisci gli errori con eleganza quando analizzi i deep link
  6. Documenta i tuoi formati deep link se crei strumenti che li generano
  7. Considera la lunghezza dell'URL quando includi molte metriche o intestazioni
  8. Testa su dispositivi reali oltre che su simulatori

Documentazione correlata

Supporto

Se riscontri problemi non coperti in questa guida:

  1. Controlla il messaggio di errore per problemi specifici dei parametri
  2. Verifica che la tua codifica URL sia corretta
  3. Testa prima con un URL minimale
  4. Usa il pulsante Supporto chat nell'app per assistenza