HealthyApps Help Center

Tự động hóa Deep Link

Tạo tự động hóa bằng chương trình qua URL scheme.

Last updated: April 5, 2026

Trên trang này

Tự động hóa deep link cho phép bạn tạo tự động hóa REST API bằng chương trình qua URL scheme. Phù hợp cho script tự động, quản lý cấu hình hoặc tích hợp hệ thống bên ngoài cần cấu hình xuất dữ liệu sức khỏe.

Tổng quan

Tự động hóa deep link dùng URL scheme tùy chỉnh để tạo và cấu hình tự động hóa REST API mà không cần nhập thủ công trong ứng dụng. Khi mở URL deep link, ứng dụng tự tạo tự động hóa mới với cấu hình đã chỉ định.

Trường hợp sử dụng:

  • Thiết lập tự động hóa từ script hoặc công cụ
  • Cấu hình hàng loạt tự động hóa
  • Tích hợp hệ thống quản lý cấu hình
  • Thiết lập nhanh từ ứng dụng hoặc trang web bên ngoài
  • Quy trình kiểm thử và phát triển

Tính năng chính:

  • Tạo tự động hóa qua URL scheme
  • Cấu hình mọi cài đặt tự động hóa REST API
  • Xác thực tham số an toàn kiểu
  • Thông báo lỗi đầy đủ

Hạn chế

  • Deep link chỉ hỗ trợ tự động hóa REST API (không phải Dropbox, Google Drive, v.v.)
  • Giới hạn độ dài URL có thể hạn chế danh sách tham số rất dài
  • Mọi hạn chế của tự động hóa REST API đều áp dụng (xử lý nền, truy cập dữ liệu sức khỏe, v.v.)

Định dạng URL

URL deep link có cấu trúc:

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

URL cơ sở: com.HealthExport://automation

Tham số: Mọi tham số đều tùy chọn trừ name và url. Tên tham số không phân biệt hoa thường.

Tham chiếu tham số

Tham số bắt buộc

url (bắt buộc)

  • Kiểu: Chuỗi (URL hợp lệ)
  • Mô tả: URL điểm cuối nhận dữ liệu sức khỏe
  • Ví dụ: https://api.example.com/health-data
  • Lưu ý: Phải là URL HTTP/HTTPS hợp lệ

name (bắt buộc)

  • Kiểu: Chuỗi
  • Mô tả: Tên mô tả cho tự động hóa
  • Ví dụ: My%20Backend%20API (mã hóa URL: My Backend API)
  • Lưu ý: Phải mã hóa URL nếu có khoảng trắng hoặc ký tự đặc biệt

Cấu hình cơ bản

format

  • Kiểu: Enum (json, csv)
  • Mặc định: json
  • Mô tả: Định dạng xuất dữ liệu
  • Ví dụ: format=json hoặc format=csv
  • Lưu ý: Định dạng CSV tự bật gom dữ liệu

enabled

  • Kiểu: Boolean (true, false, 1, 0, yes, no)
  • Mặc định: false
  • Mô tả: Tự động hóa có bật ngay sau khi tạo không
  • Ví dụ: enabled=true

datatype

  • Kiểu: Enum (xem Loại dữ liệu bên dưới)
  • Mặc định: healthMetrics
  • Mô tả: Loại dữ liệu sức khỏe cần xuất
  • Ví dụ: datatype=workouts
  • Lưu ý: Chỉ chọn một loại. Đặt tham số này tự cấu hình cờ include phù hợp.

Loại dữ liệu hợp lệ:

  • healthMetrics — Chỉ số sức khỏe (bước chân, nhịp tim, giấc ngủ, v.v.)
  • workouts — Hoạt động thể dục, thể thao
  • symptoms — Triệu chứng và tình trạng
  • ecg — Đo điện tim
  • heartRateNotification — Sự kiện nhịp tim cao/thấp
  • stateOfMind — Tâm trạng và trạng thái tinh thần (iOS 18.0+)
  • cycleTracking — Chu kỳ kinh nguyệt và sức khỏe sinh sản
  • medications — Nhật ký và tuân thủ thuốc (iOS 26.0+)

Cài đặt xuất

period

  • Kiểu: Enum
  • Mặc định: none
  • Mô tả: Khoảng ngày xuất dữ liệu
  • Ví dụ: period=today

Giá trị hợp lệ:

  • none — Mặc định (cả ngày hôm trước và ngày hiện tại)
  • lastsync — Kể từ lần đồng bộ trước
  • today — Ngày hiện tại
  • yesterday — Ngày hôm qua
  • previous7days — 7 ngày trước
  • realtime — Cập nhật thời gian thực (cần khoảng đồng bộ giây)

interval

  • Kiểu: Enum
  • Mặc định: none
  • Mô tả: Khoảng gom/nhóm thời gian (chỉ hợp lệ với loại healthMetrics)
  • Ví dụ: interval=hours

Giá trị hợp lệ:

  • none — Mặc định (không gom)
  • minutes — Gom theo phút
  • hours — Gom theo giờ
  • days — Gom theo ngày
  • weeks — Gom theo tuần
  • months — Gom theo tháng
  • years — Gom theo năm

Lưu ý: Chỉ hợp lệ khi datatype=healthMetrics. Định dạng CSV luôn gom dữ liệu.

aggregatedata

  • Kiểu: Boolean
  • Mặc định: true (CSV), false (JSON)
  • Mô tả: Có gom/tóm tắt dữ liệu không (chỉ healthMetrics với JSON)
  • Ví dụ: aggregatedata=true
  • Lưu ý: Tự đặt true khi format=csv

aggregatesleep

  • Kiểu: Boolean
  • Mặc định: true
  • Mô tả: Có gom dữ liệu giấc ngủ không
  • Ví dụ: aggregatesleep=true

exportversion

  • Kiểu: Enum (v1, v2, 1, 2)
  • Mặc định: v2
  • Mô tả: Phiên bản định dạng xuất
  • Ví dụ: exportversion=v2
  • Lưu ý: Phiên bản 2 có dữ liệu buổi tập nâng cao và siêu dữ liệu chi tiết hơn

batchrequests

  • Kiểu: Boolean
  • Mặc định: false
  • Mô tả: Gửi dữ liệu theo lô qua nhiều yêu cầu (chỉ REST API với JSON)
  • Ví dụ: batchrequests=true
  • Lưu ý: Chỉ hợp lệ khi format=json và exportDestination=restApi

Chu kỳ đồng bộ

syncinterval

  • Kiểu: Enum
  • Mặc định: minutes
  • Mô tả: Khoảng thời gian cho chu kỳ đồng bộ
  • Ví dụ: syncinterval=hours

Giá trị hợp lệ:

  • minutes — Đồng bộ mỗi N phút
  • hours — Đồng bộ mỗi N giờ
  • days — Đồng bộ mỗi N ngày
  • weeks — Đồng bộ mỗi N tuần
  • seconds — Chỉ hợp lệ khi period=realtime

Lưu ý: Với REST API, chỉ minutes, hours, days, weeks hợp lệ trừ khi xuất thời gian thực.

syncquantity

  • Kiểu: Số nguyên dương
  • Mặc định: 5
  • Mô tả: Số khoảng giữa các lần đồng bộ
  • Ví dụ: syncquantity=10 (đồng bộ mỗi 10 phút nếu syncinterval=minutes)
  • Lưu ý: Phải lớn hơn 0

Cấu hình HTTP

headers

  • Kiểu: Chuỗi (cặp khóa-giá trị phân tách bằng dấu phẩy)
  • Mặc định: Không
  • Mô tả: Tiêu đề HTTP cho xác thực hoặc siêu dữ liệu
  • Ví dụ: headers=Authorization,Bearer%20token123,X-API-Key,abc123
  • Định dạng: key1,value1,key2,value2,...
  • Lưu ý: Giá trị nên mã hóa URL. Mỗi tiêu đề cần cả khóa và giá trị.

Ví dụ tiêu đề:

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

requesttimeout

  • Kiểu: Số nguyên (60–86400)
  • Mặc định: 60
  • Mô tả: Thời gian chờ yêu cầu (giây)
  • Ví dụ: requesttimeout=300
  • Lưu ý: Từ 60 đến 86400 giây (1 phút đến 24 giờ)

Cài đặt theo loại dữ liệu

Cài đặt Chỉ số sức khỏe

metrics
  • Kiểu: Chuỗi (MetricName rawValues phân tách bằng dấu phẩy)
  • Mặc định: Mọi chỉ số có sẵn
  • Mô tả: Chỉ số sức khỏe cụ thể (chỉ healthMetrics)
  • Ví dụ: metrics=Step%20Count,Heart%20Rate,Active%20Energy
  • Lưu ý: Phải dùng đúng MetricName rawValues. Nếu không chỉ định, gồm mọi chỉ số.

Tên chỉ số thường gặp:

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

Xem màn hình chọn chỉ số trong ứng dụng để biết danh sách đầy đủ.

Cài đặt Buổi tập

includeroutes
  • Kiểu: Boolean
  • Mặc định: true
  • Mô tả: Gồm dữ liệu lộ trình buổi tập (chỉ workouts)
  • Ví dụ: includeroutes=true
includeworkoutmetadata
  • Kiểu: Boolean
  • Mặc định: true
  • Mô tả: Gồm chỉ số buổi tập (nhịp tim, calo, v.v.) (chỉ workouts)
  • Ví dụ: includeworkoutmetadata=true
workoutsmetadatainterval
  • Kiểu: Enum (minutes, seconds)
  • Mặc định: minutes
  • Mô tả: Gom nhóm thời gian cho chỉ số buổi tập (chỉ workouts với exportversion v2)
  • Ví dụ: workoutsmetadatainterval=seconds
  • Lưu ý: Chỉ hợp lệ khi datatype=workouts và exportversion=v2
workouttypes
  • Kiểu: Chuỗi (UInt phân tách bằng dấu phẩy)
  • Mặc định: Rỗng (mọi loại buổi tập)
  • Mô tả: Loại buổi tập cụ thể (chỉ workouts)
  • Ví dụ: workouttypes=1,2,3
  • Lưu ý: Dùng mã định danh loại buổi tập HealthKit

Thông báo

notifyonupdate

  • Kiểu: Boolean
  • Mặc định: true
  • Mô tả: Thông báo khi dữ liệu bộ nhớ đệm cập nhật
  • Ví dụ: notifyonupdate=true

notifywhenrun

  • Kiểu: Boolean
  • Mặc định: true
  • Mô tả: Thông báo mỗi lần tự động hóa thực thi
  • Ví dụ: notifywhenrun=false

Ví dụ

Tự động hóa REST API cơ bản

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

Tạo tự động hóa cơ bản gửi dữ liệu JSON tới điểm cuối đã chỉ định.

Có tiêu đề xác thực

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

Tạo tự động hóa với tiêu đề xác thực tùy chỉnh.

Chỉ số sức khỏe với chỉ số cụ thể

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

Tạo tự động hóa chỉ xuất bước chân và nhịp tim, gom theo giờ.

Buổi tập có dữ liệu lộ trình

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

Tạo tự động hóa buổi tập có lộ trình và chỉ số buổi tập, phiên bản xuất 2.

Ví dụ cấu hình đầy đủ

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

Ví dụ toàn diện với các tham số chính.

Ví dụ định dạng CSV

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

Tạo tự động hóa xuất CSV. Định dạng CSV tự bật gom dữ liệu.

Mã hóa URL

Ký tự đặc biệt trong giá trị tham số phải mã hóa URL. Mã thường gặp:

  • Khoảng trắng: %20
  • Dấu phẩy: %2C
  • Dấu hai chấm: %3A
  • Dấu chấm phẩy: %3B
  • Dấu bằng: %3D
  • Dấu và: %26
  • Dấu cộng: %2B

Ví dụ:

  • Gốc: My Automation Name
  • Đã mã hóa: My%20Automation%20Name

Ví dụ tiêu đề:

  • Gốc: Authorization, Bearer token123
  • Đã mã hóa: Authorization,Bearer%20token123

Hầu hết ngôn ngữ lập trình có hàm mã hóa URL:

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

Từ Safari (iOS)

  1. Mở Safari trên thiết bị iOS
  2. Nhập URL deep link vào thanh địa chỉ
  3. Chạm Đi
  4. Ứng dụng sẽ mở và tạo tự động hóa

Khắc phục sự cố

Sự cố thường gặp

« Could not parse the URL »

  • Kiểm tra scheme đúng: com.HealthExport://automation
  • Giá trị tham số đã mã hóa URL đúng
  • Tên thám số đúng chính tả (không phân biệt hoa thường)

« Invalid URL parameter value »

  • URL là HTTP/HTTPS hợp lệ
  • Mã hóa URL đúng
  • URL không chứa ký tự không hợp lệ

« Invalid data type »

  • Dùng đúng giá trị: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
  • Kiểm tra chính tả (vẫn hỗ trợ khớp không phân biệt hoa thường)

« Invalid sync cadence interval »

  • Với REST API chỉ dùng: minutes, hours, days, weeks
  • Chỉ dùng seconds khi period=realtime

« Aggregation settings are only valid for healthMetrics data type »

  • aggregatedata và interval chỉ với datatype=healthMetrics
  • Xóa tham số hoặc đổi loại dữ liệu

« Batch requests are only valid for REST API with JSON format »

  • batchrequests chỉ khi format=json
  • Đổi sang JSON hoặc xóa batchrequests

« Workout settings are only valid for workouts data type »

  • includeroutes, includeworkoutmetadata, workoutsmetadatainterval chỉ với datatype=workouts
  • Đổi loại hoặc xóa các tham số này

« Metrics parameter is only valid for healthMetrics data type »

  • metrics chỉ với datatype=healthMetrics
  • Đổi loại hoặc xóa metrics

« Invalid metric name »

  • Dùng đúng MetricName rawValues (ví dụ « Step Count », « Heart Rate »)
  • Kiểm tra chính tả và viết hoa
  • Xem màn hình chọn chỉ số trong ứng dụng

« Invalid request timeout »

  • Phải từ 60 đến 86400 giây

« A name is required for the automation »

  • Có tham số name
  • Giá trị không rỗng sau giải mã URL

Giới hạn độ dài URL

URL rất dài (nhiều chỉ số hoặc tiêu đề) có thể vượt giới hạn hệ thống. Cân nhắc:

  • Giảm số chỉ số trong metrics
  • Giảm số tiêu đề
  • Dùng giá trị ngắn hơn khi có thể
  • Chia cấu hình phức tạp thành nhiều tự động hóa đơn giản hơn

Thứ tự ưu tiên tham số

Khi tham số xung đột:

  1. datatype tự đặt lại cờ include
  2. format=csv tự đặt aggregatedata=true
  3. period=realtime yêu cầu syncinterval=seconds
  4. Kết hợp không tương thích sẽ báo lỗi xác thực

Thực hành tốt

  1. Đồng bộ tự động (khi kích hoạt tự động hóa qua deep link):

    • Sạc thiết bị và dùng iPhone Mirroring
      • Khi sạc, iOS hạn chế hiệu năng ít hơn nên đồng bộ thường xuyên hơn
      • iPhone Mirroring khiến thiết bị như mở khóa, dữ liệu sức khỏe có thể truy cập để chạy tự động hóa

  2. Luôn mã hóa URL cho giá trị có ký tự đặc biệt

  3. Thử URL đơn giản trước, sau đó tăng độ phức tạp

  4. Dùng tên mô tả để dễ nhận diện

  5. Xác thực URL trước khi tạo deep link bằng chương trình

  6. Xử lý lỗi gọn khi phân tích deep link

  7. Ghi lại định dạng deep link nếu xây công cụ tạo chúng

  8. Cân nhắc độ dài URL khi gồm nhiều chỉ số hoặc tiêu đề

  9. Thử trên thiết bị thật cũng như trình mô phỏng

Tài liệu liên quan

Hỗ trợ

Nếu gặp vấn đề chưa có trong hướng dẫn:

  1. Đọc thông báo lỗi để biết tham số cụ thể
  2. Kiểm tra mã hóa URL
  3. Thử URL tối thiểu trước
  4. Dùng nút Hỗ trợ trò chuyện trong ứng dụng