Otomatisasi Deep Link

Automatisasi deep link memungkinkan Anda membuat otomatisasi REST API secara terprogram menggunakan skema URL. Ini ideal untuk skrip otomasi, manajemen konfigurasi, atau integrasi dengan sistem eksternal yang perlu mengonfigurasi ekspor data kesehatan.

Ringkasan

Automatisasi deep link menggunakan skema URL khusus untuk membuat dan mengonfigurasi otomatisasi REST API tanpa memasukkan pengaturan secara manual di aplikasi. Saat Anda membuka URL deep link, aplikasi secara otomatis membuat otomatisasi baru dengan konfigurasi yang ditentukan.

Contoh penggunaan:

• Penyiapan otomatisasi terprogram dari skrip atau alat
• Konfigurasi otomatisasi secara massal
• Integrasi dengan sistem manajemen konfigurasi
• Penyiapan cepat dari aplikasi atau situs eksternal
• Alur kerja pengujian dan pengembangan

Fitur utama:

• Membuat otomatisasi melalui skema URL
• Mengonfigurasi semua pengaturan otomatisasi REST API
• Validasi parameter yang aman secara tipe
• Pesan error yang komprehensif

Keterbatasan

• Deep link hanya mendukung otomatisasi REST API (bukan Dropbox, Google Drive, dll.)
• Batas panjang URL dapat membatasi daftar parameter yang sangat panjang
• Semua keterbatasan dari otomatisasi REST API berlaku (proses latar belakang, akses data kesehatan, dll.)

Format URL

URL deep link mengikuti struktur berikut:

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

Base URL: com.HealthExport://automation

Parameter: Semua parameter bersifat opsional kecuali name dan url. Nama parameter tidak peka huruf besar/kecil.

Referensi parameter

Parameter wajib

url (wajib)

• Tipe: String (URL valid)
• Deskripsi: URL endpoint tempat data kesehatan akan dikirim
• Contoh: https://api.example.com/health-data
• Catatan: Harus berupa URL HTTP/HTTPS yang valid

name (wajib)

• Tipe: String
• Deskripsi: Nama deskriptif untuk otomatisasi
• Contoh: My%20Backend%20API (URL-encoded: My Backend API)
• Catatan: Harus di-URL-encode jika berisi spasi atau karakter khusus

Konfigurasi dasar

format

• Tipe: Enum (json, csv)
• Default: json
• Deskripsi: Format ekspor untuk data
• Contoh: format=json atau format=csv
• Catatan: Format CSV secara otomatis mengaktifkan agregasi data

enabled

• Tipe: Boolean (true, false, 1, 0, yes, no)
• Default: false
• Deskripsi: Apakah otomatisasi langsung diaktifkan setelah dibuat
• Contoh: enabled=true

datatype

• Tipe: Enum (lihat Tipe data di bawah)
• Default: healthMetrics
• Deskripsi: Tipe data kesehatan yang diekspor
• Contoh: datatype=workouts
• Catatan: Hanya satu tipe data yang dapat dipilih. Mengatur ini secara otomatis mengonfigurasi flag penyertaan yang sesuai.

Tipe data valid:

• healthMetrics – Metrik kesehatan (langkah, detak jantung, tidur, dll.)
• workouts – Aktivitas olahraga dan kebugaran
• symptoms – Gejala dan kondisi kesehatan
• ecg – Pembacaan elektrokardiogram
• heartRateNotification – Event detak jantung tinggi/rendah
• stateOfMind – Entri suasana hati dan mental (iOS 18.0+)
• cycleTracking – Data siklus menstruasi dan kesehatan reproduksi
• medications – Log obat dan kepatuhan (iOS 26.0+)

Pengaturan ekspor

period

• Tipe: Enum
• Default: none
• Deskripsi: Rentang tanggal untuk ekspor data
• Contoh: period=today

Nilai valid:

• none – Default (hari sebelumnya penuh ditambah hari berjalan)
• lastsync – Sejak sinkronisasi terakhir
• today – Hari ini
• yesterday – Hari kemarin
• previous7days – 7 hari sebelumnya
• realtime – Pembaruan real-time (memerlukan interval sinkronisasi detik)

interval

• Tipe: Enum
• Default: none
• Deskripsi: Interval pengelompokan/agregasi waktu (hanya valid untuk tipe data healthMetrics)
• Contoh: interval=hours

Nilai valid:

• none – Default (tanpa agregasi)
• minutes – Kelompok per menit
• hours – Kelompok per jam
• days – Kelompok per hari
• weeks – Kelompok per minggu
• months – Kelompok per bulan
• years – Kelompok per tahun

Catatan: Parameter ini hanya valid saat datatype=healthMetrics. Format CSV selalu mengagregasi data.

aggregatedata

• Tipe: Boolean
• Default: true (untuk CSV), false (untuk JSON)
• Deskripsi: Apakah data diagregasi/diringkas (hanya valid untuk healthMetrics dengan format JSON)
• Contoh: aggregatedata=true
• Catatan: Secara otomatis diset ke true saat format=csv

aggregatesleep

• Tipe: Boolean
• Default: true
• Deskripsi: Apakah data tidur diagregasi
• Contoh: aggregatesleep=true

exportversion

• Tipe: Enum (v1, v2, 1, 2)
• Default: v2
• Deskripsi: Versi format ekspor
• Contoh: exportversion=v2
• Catatan: Versi 2 menyertakan data workout yang ditingkatkan dan metadata lebih detail

batchrequests

• Tipe: Boolean
• Default: false
• Deskripsi: Mengirim data dalam batch melalui beberapa permintaan (hanya valid untuk REST API dengan format JSON)
• Contoh: batchrequests=true
• Catatan: Hanya valid saat format=json dan exportDestination=restApi

Frekuensi sinkronisasi

syncinterval

• Tipe: Enum
• Default: minutes
• Deskripsi: Interval untuk frekuensi sinkronisasi
• Contoh: syncinterval=hours

Nilai valid:

• minutes – Sinkron setiap N menit
• hours – Sinkron setiap N jam
• days – Sinkron setiap N hari
• weeks – Sinkron setiap N minggu
• seconds – Hanya valid saat period=realtime

Catatan: Untuk otomatisasi REST API, hanya minutes, hours, days, dan weeks yang valid kecuali menggunakan ekspor real-time.

syncquantity

• Tipe: Integer (positif)
• Default: 5
• Deskripsi: Jumlah interval antar sinkronisasi
• Contoh: syncquantity=10 (sinkron setiap 10 menit jika syncinterval=minutes)
• Catatan: Harus lebih besar dari 0

Konfigurasi HTTP

headers

• Tipe: String (pasangan kunci-nilai dipisahkan koma)
• Default: Tidak ada
• Deskripsi: Header HTTP untuk autentikasi atau metadata
• Contoh: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Format: key1,value1,key2,value2,...
• Catatan: Nilai harus di-URL-encode. Setiap header memerlukan kunci dan nilai.

Contoh header:

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

requesttimeout

• Tipe: Integer (60–86400)
• Default: 60
• Deskripsi: Batas waktu permintaan dalam detik
• Contoh: requesttimeout=300
• Catatan: Harus antara 60 dan 86400 detik (1 menit hingga 24 jam)

Pengaturan khusus tipe data

Pengaturan Health Metrics

metrics

• Tipe: String (rawValue MetricName dipisahkan koma)
• Default: Semua metrik yang tersedia
• Deskripsi: Metrik kesehatan spesifik yang disertakan (hanya valid untuk tipe healthMetrics)
• Contoh: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Catatan: Harus menggunakan rawValue MetricName yang tepat. Jika tidak ditentukan, semua metrik yang tersedia disertakan.

Nama metrik umum:

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

Lihat layar pemilihan metrik di aplikasi untuk daftar lengkap metrik yang tersedia.

Pengaturan Workout

includeroutes

• Tipe: Boolean
• Default: true
• Deskripsi: Sertakan data rute untuk workout (hanya valid untuk tipe workouts)
• Contoh: includeroutes=true

includeworkoutmetadata

• Tipe: Boolean
• Default: true
• Deskripsi: Sertakan metrik workout (detak jantung, kalori, dll.) yang dikumpulkan selama workout (hanya valid untuk workouts)
• Contoh: includeworkoutmetadata=true

workoutsmetadatainterval

• Tipe: Enum (minutes, seconds)
• Default: minutes
• Deskripsi: Pengelompokan waktu untuk metrik workout (hanya valid untuk workouts dengan exportVersion v2)
• Contoh: workoutsmetadatainterval=seconds
• Catatan: Hanya valid saat datatype=workouts dan exportversion=v2

workouttypes

• Tipe: String (nilai UInt dipisahkan koma)
• Default: Kosong (semua tipe workout)
• Deskripsi: Tipe workout spesifik yang disertakan (hanya valid untuk workouts)
• Contoh: workouttypes=1,2,3
• Catatan: Menggunakan pengidentifikasi tipe workout HealthKit

Notifikasi

notifyonupdate

• Tipe: Boolean
• Default: true
• Deskripsi: Terima notifikasi saat data cache diperbarui
• Contoh: notifyonupdate=true

notifywhenrun

• Tipe: Boolean
• Default: true
• Deskripsi: Terima notifikasi setiap kali otomatisasi dijalankan
• Contoh: notifywhenrun=false

Contoh

Otomatisasi REST API dasar

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

Membuat otomatisasi dasar yang mengirim data JSON ke endpoint yang ditentukan.

Dengan header autentikasi

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

Membuat otomatisasi dengan header autentikasi kustom.

Health Metrics dengan metrik tertentu

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

Membuat otomatisasi yang hanya mengekspor langkah dan detak jantung, diagregasi per jam.

Workouts dengan data rute

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

Membuat otomatisasi untuk workout dengan data rute dan metrik workout, menggunakan versi ekspor 2.

Contoh konfigurasi lengkap

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

Contoh komprehensif dengan semua parameter utama dikonfigurasi.

Contoh format CSV

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

Membuat otomatisasi ekspor CSV. Perhatikan bahwa format CSV secara otomatis mengaktifkan agregasi data.

URL encoding

Karakter khusus dalam nilai parameter harus di-URL-encode. Pengkodean umum:

• Spasi: %20
• Koma: %2C
• Titik dua: %3A
• Titik koma: %3B
• Sama dengan: %3D
• Ampersand: %26
• Plus: %2B

Contoh:

• Asli: My Automation Name
• Terencode: My%20Automation%20Name

Contoh header:

• Asli: Authorization, Bearer token123
• Terencode: Authorization,Bearer%20token123

Sebagian besar bahasa pemrograman dan alat menyediakan fungsi pengkodean URL:

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

Pengujian deep link

Dari Safari (iOS)

1. Buka Safari di perangkat iOS Anda
2. Masukkan URL deep link di bilah alamat
3. Ketuk Go
4. Aplikasi harus terbuka dan membuat otomatisasi

Dari Terminal (macOS/Simulator iOS)

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

Dari Xcode

Tambahkan breakpoint atau gunakan konsol debugger:

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

Dari app Shortcuts

1. Buat pintasan baru
2. Tambahkan aksi "Open URLs"
3. Masukkan URL deep link Anda
4. Jalankan pintasan

Pemecahan masalah

Masalah umum

"Could not parse the URL"

• Pastikan skema URL benar: com.HealthExport://automation
• Periksa bahwa semua nilai parameter sudah di-URL-encode dengan benar
• Pastikan nama parameter dieja benar (tidak peka huruf besar/kecil)

"Invalid URL parameter value"

• Pastikan URL merupakan HTTP/HTTPS yang valid
• Periksa pengkodean URL yang benar
• Pastikan URL tidak berisi karakter tidak valid

"Invalid data type"

• Gunakan nilai tipe data yang tepat: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Periksa ejaan dan huruf besar/kecil (meskipun pencocokan tidak peka huruf besar/kecil didukung)

"Invalid sync cadence interval"

• Untuk REST API, gunakan hanya: minutes, hours, days, weeks
• Gunakan seconds hanya saat period=realtime

"Aggregation settings are only valid for healthMetrics data type"

• Parameter aggregatedata dan interval hanya bekerja dengan datatype=healthMetrics
• Hapus parameter ini atau ubah tipe data

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

• batchrequests hanya bekerja saat format=json
• Ubah format ke JSON atau hapus parameter batchrequests

"Workout settings are only valid for workouts data type"

• includeroutes, includeworkoutmetadata, dan workoutsmetadatainterval hanya bekerja dengan datatype=workouts
• Ubah tipe data ke workouts atau hapus parameter ini

"Metrics parameter is only valid for healthMetrics data type"

• Parameter metrics hanya bekerja dengan datatype=healthMetrics
• Ubah tipe data atau hapus parameter metrics

"Invalid metric name"

• Gunakan rawValue MetricName yang tepat (misalnya "Step Count", "Heart Rate")
• Periksa ejaan dan kapitalisasi
• Lihat layar pemilihan metrik di aplikasi untuk nama yang valid

"Invalid request timeout"

• Harus antara 60 dan 86400 detik
• Gunakan nilai dalam rentang ini

"A name is required for the automation"

• Pastikan parameter name disertakan
• Periksa bahwa nilai tidak kosong setelah dekode URL

Batas panjang URL

URL yang sangat panjang (terutama dengan banyak metrik atau header) dapat melebihi batas sistem. Pertimbangkan:

• Menggunakan lebih sedikit metrik dalam parameter metrics
• Mengurangi jumlah header
• Menggunakan nilai parameter yang lebih pendek jika memungkinkan
• Memecah konfigurasi kompleks menjadi beberapa otomatisasi yang lebih sederhana

Prioritas parameter

Saat beberapa parameter bertentangan:

1. Pemilihan tipe data (datatype) secara otomatis mengatur ulang flag penyertaan
2. Format CSV (format=csv) secara otomatis menyetel aggregatedata=true
3. Periode real-time (period=realtime) memerlukan syncinterval=seconds
4. Error validasi akan dilempar untuk kombinasi yang tidak kompatibel

Praktik terbaik

1. Sinkronisasi otomatis (saat otomatisasi dipicu melalui deep link):

   • Isi daya perangkat Anda dan gunakan iPhone Mirroring
     • Saat perangkat sedang diisi daya, iOS memberi pembatasan lebih sedikit pada performa perangkat, sehingga data dapat disinkronkan lebih sering
     • Dengan iPhone Mirroring, perangkat Anda berperilaku seperti saat tidak terkunci. Ini berarti data kesehatan dapat diakses oleh Health Auto Export untuk menjalankan tindakan otomatis

2. Selalu URL-encode nilai parameter yang berisi karakter khusus

3. Uji dengan URL sederhana terlebih dahulu, lalu tambah kompleksitas

4. Gunakan nama deskriptif untuk identifikasi yang lebih mudah

5. Validasi URL sebelum membuat deep link secara terprogram

6. Tangani error dengan baik saat mengurai deep link

7. Dokumentasikan format deep link jika membangun alat yang menghasilkan deep link

8. Pertimbangkan panjang URL saat menyertakan banyak metrik atau header

9. Uji di perangkat nyata serta di simulator

Dokumentasi terkait

• Panduan otomatisasi REST API – Informasi detail tentang otomatisasi REST API
• Ringkasan otomatisasi – Konsep otomatisasi umum
• Panduan manual export – Cara mengekspor data secara manual

Dukungan

Jika Anda mengalami masalah yang tidak tercakup dalam panduan ini:

1. Periksa pesan error untuk masalah parameter spesifik
2. Verifikasi pengkodean URL Anda benar
3. Uji dengan URL minimal terlebih dahulu
4. Gunakan tombol Chat Support di aplikasi untuk bantuan