HealthyApps Help Center

딥 링크 자동화

URL 스킴을 사용해 자동화를 프로그래밍 방식으로 만듭니다.

Last updated: April 5, 2026

이 페이지에서

딥 링크 자동화는 URL 스킴을 사용해 REST API 자동화를 프로그래밍 방식으로 만들 수 있게 합니다. 자동화 스크립트, 구성 관리, 건강 데이터 내보내기를 설정해야 하는 외부 시스템과 통합할 때 적합합니다.

개요

딥 링크 자동화는 사용자 정의 URL 스킴을 사용해 앱에서 설정을 직접 입력하지 않고도 REST API 자동화를 만들고 구성합니다. 딥 링크 URL을 열면 앱이 지정한 구성으로 새 자동화를 자동으로 만듭니다.

사용 사례:

  • 스크립트나 도구에서 프로그래밍 방식으로 자동화 설정
  • 자동화 일괄 구성
  • 구성 관리 시스템과의 통합
  • 외부 앱이나 웹사이트에서 빠른 설정
  • 테스트 및 개발 워크플로

주요 기능:

  • URL 스킴으로 자동화 생성
  • REST API 자동화 설정 전체 구성
  • 타입 안전 매개변수 검증
  • 자세한 오류 메시지

제한 사항

  • 딥 링크는 REST API 자동화만 지원합니다(Dropbox, Google Drive 등은 해당 없음).
  • URL 길이 제한으로 매개변수 목록이 매우 길면 제한될 수 있습니다.
  • REST API 자동화의 모든 제한(백그라운드 처리, 건강 데이터 접근 등)이 그대로 적용됩니다.

URL 형식

딥 링크 URL은 다음 구조를 따릅니다.

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

기본 URL: com.HealthExport://automation

매개변수: name과 url을 제외한 모든 매개변수는 선택 사항입니다. 매개변수 이름은 대소문자를 구분하지 않습니다.

매개변수 참조

필수 매개변수

url (필수)

  • 유형: 문자열(유효한 URL)
  • 설명: 건강 데이터를 보낼 엔드포인트 URL
  • 예: https://api.example.com/health-data
  • 참고: 유효한 HTTP/HTTPS URL이어야 합니다.

name (필수)

  • 유형: 문자열
  • 설명: 자동화를 설명하는 이름
  • 예: My%20Backend%20API(URL 인코딩: My Backend API)
  • 참고: 공백이나 특수 문자가 있으면 URL 인코딩해야 합니다.

기본 구성

format

  • 유형: 열거형(json, csv)
  • 기본값: json
  • 설명: 데이터 내보내기 형식
  • 예: format=json 또는 format=csv
  • 참고: CSV 형식을 선택하면 데이터 집계가 자동으로 켜집니다.

enabled

  • 유형: 불리언(true, false, 1, 0, yes, no)
  • 기본값: false
  • 설명: 생성 직후 자동화를 바로 켤지 여부
  • 예: enabled=true

datatype

  • 유형: 열거형(아래 데이터 유형 참고)
  • 기본값: healthMetrics
  • 설명: 내보낼 건강 데이터 유형
  • 예: datatype=workouts
  • 참고: 데이터 유형은 하나만 선택할 수 있습니다. 설정하면 해당하는 포함 플래그가 자동으로 구성됩니다.

유효한 데이터 유형:

  • healthMetrics — 걸음 수, 심박수, 수면 등 건강 지표
  • workouts — 운동 및 피트니스 활동
  • symptoms — 건강 증상 및 상태
  • ecg — 심전도 측정
  • heartRateNotification — 심박수 높음/낮음 알림
  • stateOfMind — 기분 및 정신 상태 항목(iOS 18.0+)
  • cycleTracking — 생리 주기 및 생식 건강 데이터
  • medications — 복약 기록 및 순응(iOS 26.0+)

내보내기 설정

period

  • 유형: 열거형
  • 기본값: none
  • 설명: 데이터 내보내기 날짜 범위
  • 예: period=today

유효한 값:

  • none — 기본값(전날 전체 + 당일)
  • lastsync — 마지막 동기화 이후
  • today — 오늘
  • yesterday — 어제
  • previous7days — 최근 7일
  • realtime — 실시간 업데이트(초 단위 동기화 간격 필요)

interval

  • 유형: 열거형
  • 기본값: none
  • 설명: 시간 묶음/집계 간격(healthMetrics 유형에서만 유효)
  • 예: interval=hours

유효한 값:

  • none — 기본값(집계 없음)
  • minutes — 분 단위 묶음
  • hours — 시간 단위 묶음
  • days — 일 단위 묶음
  • weeks — 주 단위 묶음
  • months — 월 단위 묶음
  • years — 연 단위 묶음

참고: datatype=healthMetrics일 때만 유효합니다. CSV 형식은 항상 데이터를 집계합니다.

aggregatedata

  • 유형: 불리언
  • 기본값: CSV는 true, JSON은 false
  • 설명: 데이터를 집계·요약할지 여부(healthMetrics와 JSON 형식에서만 유효)
  • 예: aggregatedata=true
  • 참고: format=csv이면 자동으로 true입니다.

aggregatesleep

  • 유형: 불리언
  • 기본값: true
  • 설명: 수면 데이터를 집계할지 여부
  • 예: aggregatesleep=true

exportversion

  • 유형: 열거형(v1, v2, 1, 2)
  • 기본값: v2
  • 설명: 내보내기 형식 버전
  • 예: exportversion=v2
  • 참고: 버전 2에는 향상된 운동 데이터와 더 자세한 메타데이터가 포함됩니다.

batchrequests

  • 유형: 불리언
  • 기본값: false
  • 설명: 여러 요청에 나누어 데이터 전송(JSON 형식의 REST API에서만 유효)
  • 예: batchrequests=true
  • 참고: format=json이고 exportDestination=restApi일 때만 유효합니다.

동기화 주기

syncinterval

  • 유형: 열거형
  • 기본값: minutes
  • 설명: 동기화 주기의 단위
  • 예: syncinterval=hours

유효한 값:

  • minutes — N분마다 동기화
  • hours — N시간마다 동기화
  • days — N일마다 동기화
  • weeks — N주마다 동기화
  • seconds — period=realtime일 때만 유효

참고: REST API 자동화에서는 실시간 내보내기가 아니면 minutes, hours, days, weeks만 사용할 수 있습니다.

syncquantity

  • 유형: 정수(양수)
  • 기본값: 5
  • 설명: 동기화 사이의 간격 개수
  • 예: syncquantity=10(syncinterval=minutes이면 10분마다 동기화)
  • 참고: 0보다 커야 합니다.

HTTP 구성

headers

  • 유형: 문자열(쉼표로 구분된 키-값 쌍)
  • 기본값: 없음
  • 설명: 인증이나 메타데이터용 HTTP 헤더
  • 예: headers=Authorization,Bearer%20token123,X-API-Key,abc123
  • 형식: key1,value1,key2,value2,...
  • 참고: 값은 URL 인코딩해야 합니다. 헤더마다 키와 값이 모두 필요합니다.

헤더 예:

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

requesttimeout

  • 유형: 정수(60–86400)
  • 기본값: 60
  • 설명: 요청 시간 제한(초)
  • 예: requesttimeout=300
  • 참고: 60초 이상 86400초(1분~24시간) 사이여야 합니다.

데이터 유형별 설정

건강 지표 설정

metrics
  • 유형: 문자열(쉼표로 구분된 MetricName rawValue)
  • 기본값: 사용 가능한 모든 지표
  • 설명: 포함할 건강 지표(healthMetrics 유형에서만 유효)
  • 예: metrics=Step%20Count,Heart%20Rate,Active%20Energy
  • 참고: 정확한 MetricName rawValue를 사용해야 합니다. 생략하면 사용 가능한 모든 지표가 포함됩니다.

일반적인 지표 이름:

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

전체 목록은 앱의 지표 선택 화면을 참조하세요.

운동 설정

includeroutes
  • 유형: 불리언
  • 기본값: true
  • 설명: 운동에 경로 데이터 포함(workouts 유형에서만 유효)
  • 예: includeroutes=true
includeworkoutmetadata
  • 유형: 불리언
  • 기본값: true
  • 설명: 운동 중 수집한 지표(심박수, 칼로리 등) 포함(workouts 유형에서만 유효)
  • 예: includeworkoutmetadata=true
workoutsmetadatainterval
  • 유형: 열거형(minutes, seconds)
  • 기본값: minutes
  • 설명: 운동 지표의 시간 묶음(workouts이고 내보내기 버전 v2일 때만 유효)
  • 예: workoutsmetadatainterval=seconds
  • 참고: datatype=workouts이고 exportversion=v2일 때만 유효합니다.
workouttypes
  • 유형: 문자열(쉼표로 구분된 UInt 값)
  • 기본값: 비어 있음(모든 운동 유형)
  • 설명: 포함할 운동 유형(workouts 유형에서만 유효)
  • 예: workouttypes=1,2,3
  • 참고: HealthKit 운동 유형 식별자를 사용합니다.

알림

notifyonupdate

  • 유형: 불리언
  • 기본값: true
  • 설명: 캐시된 데이터가 갱신될 때 알림 받기
  • 예: notifyonupdate=true

notifywhenrun

  • 유형: 불리언
  • 기본값: true
  • 설명: 자동화가 실행될 때마다 알림 받기
  • 예: notifywhenrun=false

예시

기본 REST API 자동화

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

지정한 엔드포인트로 JSON 데이터를 보내는 기본 자동화를 만듭니다.

인증 헤더 포함

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

사용자 정의 인증 헤더가 있는 자동화를 만듭니다.

특정 지표만 건강 지표

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

걸음 수와 심박수만 시간 단위로 집계해 내보내는 자동화를 만듭니다.

경로 데이터가 있는 운동

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

내보내기 버전 2로 경로와 운동 지표를 포함한 운동 내보내기 자동화를 만듭니다.

구성 전체 예시

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

주요 매개변수를 모두 설정한 종합 예시입니다.

CSV 형식 예시

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

CSV 내보내기 자동화를 만듭니다. CSV 형식은 데이터 집계가 자동으로 켜집니다.

URL 인코딩

매개변수 값에 특수 문자가 있으면 URL 인코딩해야 합니다. 자주 쓰는 인코딩:

  • 공백: %20
  • 쉼표: %2C
  • 콜론: %3A
  • 세미콜론: %3B
  • 등호: %3D
  • 앰퍼샌드: %26
  • 플러스: %2B

예:

  • 원문: My Automation Name
  • 인코딩: My%20Automation%20Name

헤더 예:

  • 원문: Authorization, Bearer token123
  • 인코딩: Authorization,Bearer%20token123

대부분의 프로그래밍 언어와 도구에서 URL 인코딩 함수를 제공합니다.

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

딥 링크 테스트

Safari에서(iOS)

  1. iOS 기기에서 Safari를 엽니다.
  2. 주소 표시줄에 딥 링크 URL을 입력합니다.
  3. 이동을 탭합니다.
  4. 앱이 열리고 자동화가 생성되어야 합니다.

터미널에서(macOS/iOS 시뮬레이터)

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

Xcode에서

중단점을 넣거나 디버거 콘솔을 사용합니다.

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

단축어 앱에서

  1. 새 단축어를 만듭니다.
  2. "URL 열기" 동작을 추가합니다.
  3. 딥 링크 URL을 입력합니다.
  4. 단축어를 실행합니다.

문제 해결

자주 발생하는 문제

"Could not parse the URL"

  • URL 스킴이 com.HealthExport://automation인지 확인합니다.
  • 모든 매개변수 값이 올바르게 URL 인코딩되었는지 확인합니다.
  • 매개변수 이름 철자를 확인합니다(대소문자 무시).

"Invalid URL parameter value"

  • URL이 유효한 HTTP/HTTPS URL인지 확인합니다.
  • URL 인코딩이 올바른지 확인합니다.
  • URL에 잘못된 문자가 없는지 확인합니다.

"Invalid data type"

  • 정확한 데이터 유형 값을 사용합니다: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
  • 철자 확인(대소문자 무시 매칭 지원).

"Invalid sync cadence interval"

  • REST API에서는 minutes, hours, days, weeks만 사용합니다.
  • seconds는 period=realtime일 때만 사용합니다.

"Aggregation settings are only valid for healthMetrics data type"

  • aggregatedata와 interval은 datatype=healthMetrics에서만 동작합니다.
  • 해당 매개변수를 제거하거나 데이터 유형을 변경합니다.

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

  • batchrequests는 format=json일 때만 동작합니다.
  • JSON으로 바꾸거나 batchrequests를 제거합니다.

"Workout settings are only valid for workouts data type"

  • includeroutes, includeworkoutmetadata, workoutsmetadatainterval은 datatype=workouts에서만 동작합니다.
  • 데이터 유형을 workouts로 바꾸거나 해당 매개변수를 제거합니다.

"Metrics parameter is only valid for healthMetrics data type"

  • metrics는 datatype=healthMetrics에서만 동작합니다.
  • 데이터 유형을 바꾸거나 metrics를 제거합니다.

"Invalid metric name"

  • 정확한 MetricName rawValue를 사용합니다(예: "Step Count", "Heart Rate").
  • 철자와 대소문자를 확인합니다.
  • 유효한 이름은 앱의 지표 선택 화면을 참조합니다.

"Invalid request timeout"

  • 60초 이상 86400초 사이여야 합니다.
  • 이 범위 안의 값을 사용합니다.

"A name is required for the automation"

  • name 매개변수가 포함되어 있는지 확인합니다.
  • URL 디코딩 후 값이 비어 있지 않은지 확인합니다.

URL 길이 제한

매우 긴 URL(많은 지표나 헤더)은 시스템 한도를 넘을 수 있습니다. 다음을 고려하세요.

  • metrics에 넣는 지표 수 줄이기
  • 헤더 개수 줄이기
  • 가능한 한 짧은 매개변수 값 사용
  • 복잡한 구성을 여러 개의 단순한 자동화로 나누기

매개변수 우선순위

여러 매개변수가 충돌할 때:

  1. 데이터 유형(datatype) 선택이 포함 플래그를 자동으로 재설정합니다.
  2. CSV 형식(format=csv)이 aggregatedata=true를 자동으로 설정합니다.
  3. 실시간 기간(period=realtime)은 syncinterval=seconds가 필요합니다.
  4. 호환되지 않는 조합은 검증 오류가 발생합니다.

권장 사항

  1. 자동 동기화(딥 링크로 자동화가 실행될 때):

    • 기기를 충전하고 iPhone 미러링을 사용합니다.
      • 충전 중에는 iOS가 기기 성능에 대한 제한을 덜 걸어 데이터를 더 자주 동기화할 수 있습니다.
      • iPhone 미러링을 사용하면 기기가 잠금 해제된 것과 같이 동작합니다. 따라서 Health Auto Export가 자동 작업을 실행할 수 있도록 건강 데이터에 접근할 수 있습니다.

  2. 특수 문자가 있는 매개변수 값은 항상 URL 인코딩합니다.

  3. 먼저 간단한 URL로 테스트한 뒤 복잡도를 높입니다.

  4. 구분하기 쉬운 설명적인 이름을 사용합니다.

  5. 딥 링크를 프로그래밍 방식으로 만들기 전에 URL을 검증합니다.

  6. 딥 링크를 파싱할 때 오류를 적절히 처리합니다.

  7. 딥 링크 형식을 생성하는 도구를 만드는 경우 형식을 문서화합니다.

  8. 많은 지표나 헤더를 넣을 때 URL 길이를 고려합니다.

  9. 시뮬레이터뿐 아니라 실제 기기에서도 테스트합니다.

관련 문서

지원

이 가이드에 없는 문제가 있으면:

  1. 오류 메시지에서 특정 매개변수 문제를 확인합니다.
  2. URL 인코딩이 올바른지 확인합니다.
  3. 먼저 최소한의 URL로 테스트합니다.
  4. 앱의 채팅 지원 버튼으로 도움을 요청합니다.