Automatización de Deep Link

Las automatizaciones de deep link te permiten crear automatizaciones de API REST mediante programación usando esquemas de URL. Esto es ideal para scripts de automatización, gestión de configuración o integración con sistemas externos que necesitan configurar exportaciones de datos de salud.

Resumen

Las automatizaciones de deep link utilizan un esquema de URL personalizado para crear y configurar automatizaciones de API REST sin ingresar manualmente la configuración en la app. Cuando abres una URL de deep link, la app crea automáticamente una nueva automatización con la configuración especificada.

Casos de uso:

• Configuración programática de automatizaciones desde scripts o herramientas
• Configuración masiva de automatizaciones
• Integración con sistemas de gestión de configuración
• Configuración rápida desde aplicaciones o sitios web externos
• Flujos de trabajo de pruebas y desarrollo

Características principales:

• Crear automatizaciones mediante esquema de URL
• Configurar todas las opciones de automatización de API REST
• Validación de parámetros con seguridad de tipos
• Mensajes de error completos

Limitaciones

• Los deep links solo admiten automatizaciones de API REST (no Dropbox, Google Drive, etc.)
• Los límites de longitud de URL pueden restringir listas de parámetros muy largas
• Se aplican todas las limitaciones de las automatizaciones de API REST (procesamiento en segundo plano, acceso a datos de salud, etc.)

Formato de URL

La URL de deep link sigue esta estructura:

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

URL base: com.HealthExport://automation

Parámetros: Todos los parámetros son opcionales excepto name y url. Los parámetros no distinguen entre mayúsculas y minúsculas.

Referencia de parámetros

Parámetros requeridos

url (requerido)

• Tipo: String (URL válida)
• Descripción: La URL del endpoint donde se enviarán los datos de salud
• Ejemplo: https://api.example.com/health-data
• Nota: Debe ser una URL HTTP/HTTPS válida

name (requerido)

• Tipo: String
• Descripción: Un nombre descriptivo para la automatización
• Ejemplo: My%20Backend%20API (codificado en URL: "My Backend API")
• Nota: Debe estar codificado en URL si contiene espacios o caracteres especiales

Configuración básica

format

• Tipo: Enum (json, csv)
• Por defecto: json
• Descripción: Formato de exportación para los datos
• Ejemplo: format=json o format=csv
• Nota: El formato CSV habilita automáticamente la agregación de datos

enabled

• Tipo: Boolean (true, false, 1, 0, yes, no)
• Por defecto: false
• Descripción: Si la automatización está habilitada inmediatamente después de la creación
• Ejemplo: enabled=true

datatype

• Tipo: Enum (ver Tipos de datos a continuación)
• Por defecto: healthMetrics
• Descripción: Tipo de datos de salud a exportar
• Ejemplo: datatype=workouts
• Nota: Solo se puede seleccionar un tipo de datos. Establecer esto configura automáticamente las banderas de inclusión apropiadas.

Tipos de datos válidos:

• healthMetrics - Métricas de salud (pasos, frecuencia cardíaca, sueño, etc.)
• workouts - Actividades de ejercicio y fitness
• symptoms - Síntomas y condiciones de salud
• ecg - Lecturas de electrocardiograma
• heartRateNotification - Eventos de frecuencia cardíaca alta/baja
• stateOfMind - Entradas de estado de ánimo y estado mental (iOS 18.0+)
• cycleTracking - Datos del ciclo menstrual y salud reproductiva
• medications - Registros de medicamentos y adherencia (iOS 26.0+)

Configuración de exportación

period

• Tipo: Enum
• Por defecto: none
• Descripción: Rango de fechas para la exportación de datos
• Ejemplo: period=today

Valores válidos:

• none - Por defecto (día anterior completo más día actual)
• lastsync - Desde la última sincronización
• today - Día actual
• yesterday - Día anterior
• previous7days - Últimos 7 días
• realtime - Actualizaciones en tiempo real (requiere intervalo de sincronización en segundos)

interval

• Tipo: Enum
• Por defecto: none
• Descripción: Intervalo de agrupación/agregación de tiempo (solo válido para el tipo de datos healthMetrics)
• Ejemplo: interval=hours

Valores válidos:

• none - Por defecto (sin agregación)
• minutes - Agrupar por minuto
• hours - Agrupar por hora
• days - Agrupar por día
• weeks - Agrupar por semana
• months - Agrupar por mes
• years - Agrupar por año

Nota: Este parámetro solo es válido cuando datatype=healthMetrics. El formato CSV siempre agrega datos.

aggregatedata

• Tipo: Boolean
• Por defecto: true (para CSV), false (para JSON)
• Descripción: Si agregar/resumir datos (solo válido para healthMetrics con formato JSON)
• Ejemplo: aggregatedata=true
• Nota: Se establece automáticamente en true cuando format=csv

aggregatesleep

• Tipo: Boolean
• Por defecto: true
• Descripción: Si agregar datos de sueño
• Ejemplo: aggregatesleep=true

exportversion

• Tipo: Enum (v1, v2, 1, 2)
• Por defecto: v2
• Descripción: Versión del formato de exportación
• Ejemplo: exportversion=v2
• Nota: La versión 2 incluye datos de entrenamiento mejorados y metadatos más detallados

batchrequests

• Tipo: Boolean
• Por defecto: false
• Descripción: Enviar datos en lotes a través de múltiples solicitudes (solo válido para API REST con formato JSON)
• Ejemplo: batchrequests=true
• Nota: Solo válido cuando format=json y exportDestination=restApi

Cadencia de sincronización

syncinterval

• Tipo: Enum
• Por defecto: minutes
• Descripción: Intervalo para la cadencia de sincronización
• Ejemplo: syncinterval=hours

Valores válidos:

• minutes - Sincronizar cada N minutos
• hours - Sincronizar cada N horas
• days - Sincronizar cada N días
• weeks - Sincronizar cada N semanas
• seconds - Solo válido cuando period=realtime

Nota: Para automatizaciones de API REST, solo minutes, hours, days y weeks son válidos a menos que se use exportación en tiempo real.

syncquantity

• Tipo: Integer (positivo)
• Por defecto: 5
• Descripción: Número de intervalos entre sincronizaciones
• Ejemplo: syncquantity=10 (sincronizar cada 10 minutos si syncinterval=minutes)
• Nota: Debe ser mayor que 0

Configuración HTTP

headers

• Tipo: String (pares clave-valor separados por comas)
• Por defecto: Ninguno
• Descripción: Encabezados HTTP para autenticación o metadatos
• Ejemplo: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Formato: key1,value1,key2,value2,...
• Nota: Los valores deben estar codificados en URL. Cada encabezado requiere tanto una clave como un valor.

Ejemplos de encabezados:

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

requesttimeout

• Tipo: Integer (60-86400)
• Por defecto: 60
• Descripción: Tiempo de espera de la solicitud en segundos
• Ejemplo: requesttimeout=300
• Nota: Debe estar entre 60 y 86400 segundos (1 minuto a 24 horas)

Configuración específica del tipo de datos

Configuración de métricas de salud

metrics

• Tipo: String (valores rawValues de MetricName separados por comas)
• Por defecto: Todas las métricas disponibles
• Descripción: Métricas de salud específicas a incluir (solo válido para el tipo de datos healthMetrics)
• Ejemplo: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Nota: Debe usar valores rawValues exactos de MetricName. Si no se especifica, se incluyen todas las métricas disponibles.

Nombres de métricas comunes:

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

Consulta la pantalla de selección de métricas de la app para ver la lista completa de métricas disponibles.

Configuración de entrenamientos

includeroutes

• Tipo: Boolean
• Por defecto: true
• Descripción: Incluir datos de ruta para entrenamientos (solo válido para el tipo de datos workouts)
• Ejemplo: includeroutes=true

includeworkoutmetadata

• Tipo: Boolean
• Por defecto: true
• Descripción: Incluir métricas de entrenamiento (frecuencia cardíaca, calorías, etc.) recopiladas durante los entrenamientos (solo válido para el tipo de datos workouts)
• Ejemplo: includeworkoutmetadata=true

workoutsmetadatainterval

• Tipo: Enum (minutes, seconds)
• Por defecto: minutes
• Descripción: Agrupación de tiempo para métricas de entrenamiento (solo válido para el tipo de datos workouts con exportVersion v2)
• Ejemplo: workoutsmetadatainterval=seconds
• Nota: Solo válido cuando datatype=workouts y exportversion=v2

workouttypes

• Tipo: String (valores UInt separados por comas)
• Por defecto: Vacío (todos los tipos de entrenamiento)
• Descripción: Tipos de entrenamiento específicos a incluir (solo válido para el tipo de datos workouts)
• Ejemplo: workouttypes=1,2,3
• Nota: Usa identificadores de tipo de entrenamiento de HealthKit

Notificaciones

notifyonupdate

• Tipo: Boolean
• Por defecto: true
• Descripción: Recibir notificaciones cuando se actualicen los datos en caché
• Ejemplo: notifyonupdate=true

notifywhenrun

• Tipo: Boolean
• Por defecto: true
• Descripción: Recibir notificaciones cada vez que se ejecute la automatización
• Ejemplo: notifywhenrun=false

Ejemplos

Automatización básica de API REST

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

Crea una automatización básica que envía datos JSON al endpoint especificado.

Con encabezados de autenticación

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 una automatización con encabezados de autenticación personalizados.

Métricas de salud con métricas específicas

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 una automatización que exporta solo pasos y frecuencia cardíaca, agregados por hora.

Entrenamientos con datos de ruta

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 una automatización para entrenamientos con datos de ruta y métricas de entrenamiento, usando la versión de exportación 2.

Ejemplo de configuración 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 ejemplo completo con todos los parámetros principales configurados.

Ejemplo de formato CSV

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

Crea una automatización de exportación CSV. Nota que el formato CSV habilita automáticamente la agregación de datos.

Codificación de URL

Los caracteres especiales en los valores de los parámetros deben estar codificados en URL. Codificaciones comunes:

• Espacio: %20
• Coma: %2C
• Dos puntos: %3A
• Punto y coma: %3B
• Igual: %3D
• Y comercial: %26
• Más: %2B

Ejemplo:

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

Ejemplo de encabezados:

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

La mayoría de los lenguajes de programación y herramientas proporcionan funciones de codificación de URL:

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

Prueba de deep links

Desde Safari (iOS)

1. Abre Safari en tu dispositivo iOS
2. Ingresa la URL de deep link en la barra de direcciones
3. Toca Ir
4. La app debería abrirse y crear la automatización

Desde Terminal (macOS/Simulador de iOS)

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

Desde Xcode

Agrega un punto de interrupción o usa la consola del depurador:

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

Desde la app Atajos

1. Crea un nuevo atajo
2. Agrega la acción "Abrir URLs"
3. Ingresa tu URL de deep link
4. Ejecuta el atajo

Solución de problemas

Problemas comunes

"No se pudo analizar la URL"

• Verifica que el esquema de URL sea correcto: com.HealthExport://automation
• Verifica que todos los valores de los parámetros estén correctamente codificados en URL
• Asegúrate de que los nombres de los parámetros estén escritos correctamente (no distinguen entre mayúsculas y minúsculas)

"Valor de parámetro de URL inválido"

• Verifica que la URL sea una URL HTTP/HTTPS válida
• Verifica la codificación de URL correcta
• Asegúrate de que la URL no contenga caracteres inválidos

"Tipo de datos inválido"

• Usa valores exactos de tipo de datos: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Verifica la ortografía y las mayúsculas/minúsculas (aunque se admite coincidencia sin distinguir mayúsculas y minúsculas)

"Intervalo de cadencia de sincronización inválido"

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

"La configuración de agregación solo es válida para el tipo de datos healthMetrics"

• Los parámetros aggregatedata e interval solo funcionan con datatype=healthMetrics
• Elimina estos parámetros o cambia el tipo de datos

"Las solicitudes por lotes solo son válidas para API REST con formato JSON"

• batchrequests solo funciona cuando format=json
• Cambia el formato a JSON o elimina el parámetro batchrequests

"La configuración de entrenamiento solo es válida para el tipo de datos workouts"

• includeroutes, includeworkoutmetadata y workoutsmetadatainterval solo funcionan con datatype=workouts
• Cambia el tipo de datos a workouts o elimina estos parámetros

"El parámetro metrics solo es válido para el tipo de datos healthMetrics"

• El parámetro metrics solo funciona con datatype=healthMetrics
• Cambia el tipo de datos o elimina el parámetro metrics

"Nombre de métrica inválido"

• Usa valores rawValues exactos de MetricName (por ejemplo, "Step Count", "Heart Rate")
• Verifica la ortografía y las mayúsculas
• Consulta la pantalla de selección de métricas de la app para ver nombres válidos

"Tiempo de espera de solicitud inválido"

• Debe estar entre 60 y 86400 segundos
• Usa un valor dentro de este rango

"Se requiere un nombre para la automatización"

• Asegúrate de que el parámetro name esté incluido
• Verifica que el valor no esté vacío después de la decodificación de URL

Limitaciones de longitud de URL

Las URL muy largas (especialmente con muchas métricas o encabezados) pueden exceder los límites del sistema. Considera:

• Usar menos métricas en el parámetro metrics
• Reducir el número de encabezados
• Usar valores de parámetros más cortos cuando sea posible
• Dividir configuraciones complejas en múltiples automatizaciones más simples

Precedencia de parámetros

Cuando múltiples parámetros entran en conflicto:

1. La selección de tipo de datos (datatype) restablece automáticamente las banderas de inclusión
2. El formato CSV (format=csv) establece automáticamente aggregatedata=true
3. El período en tiempo real (period=realtime) requiere syncinterval=seconds
4. Se lanzarán errores de validación para combinaciones incompatibles

Mejores prácticas

1. Siempre codifica en URL los valores de los parámetros que contengan caracteres especiales
2. Prueba con URL simples primero, luego agrega complejidad
3. Usa nombres descriptivos para facilitar la identificación
4. Valida las URL antes de crear deep links mediante programación
5. Maneja los errores con gracia al analizar deep links
6. Documenta tus formatos de deep link si construyes herramientas que los generen
7. Considera la longitud de la URL al incluir muchas métricas o encabezados
8. Prueba en dispositivos reales además de simuladores

Documentación relacionada

• Guía de automatización de API REST - Información detallada sobre automatizaciones de API REST
• Resumen de automatizaciones - Conceptos generales de automatización
• Guía de exportación manual - Cómo exportar datos manualmente

Soporte

Si encuentras problemas no cubiertos en esta guía:

1. Revisa el mensaje de error para problemas específicos de parámetros
2. Verifica que tu codificación de URL sea correcta
3. Prueba con una URL mínima primero
4. Usa el botón de Soporte por chat en la app para obtener ayuda