Automatyzacja przez deep linki

Automatyzacje przez deep linki pozwalają programowo tworzyć automatyzacje REST API za pomocą schematów URL. Jest to przydatne w skryptach automatyzacji, zarządzaniu konfiguracją lub integracji z systemami zewnętrznymi, które muszą konfigurować eksport danych zdrowotnych.

Przegląd

Automatyzacje przez deep linki wykorzystują niestandardowy schemat URL do tworzenia i konfigurowania automatyzacji REST API bez ręcznego wprowadzania ustawień w aplikacji. Po otwarciu adresu deep link aplikacja automatycznie tworzy nową automatyzację z podaną konfiguracją.

Przypadki użycia:

• Programowe konfigurowanie automatyzacji ze skryptów lub narzędzi
• Masowa konfiguracja automatyzacji
• Integracja z systemami zarządzania konfiguracją
• Szybka konfiguracja z zewnętrznych aplikacji lub stron
• Przepływy pracy testowe i deweloperskie

Kluczowe funkcje:

• Tworzenie automatyzacji przez schemat URL
• Konfiguracja wszystkich ustawień automatyzacji REST API
• Walidacja parametrów z zachowaniem typów
• Szczegółowe komunikaty błędów

Ograniczenia

• Deep linki obsługują wyłącznie automatyzacje REST API (nie Dropbox, Google Drive itd.)
• Limity długości URL mogą ograniczać bardzo długie listy parametrów
• Obowiązują wszystkie ograniczenia automatyzacji REST API (przetwarzanie w tle, dostęp do danych zdrowotnych itd.)

Format URL

Adres deep linka ma następującą strukturę:

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

Podstawowy URL: com.HealthExport://automation

Parametry: Wszystkie parametry są opcjonalne z wyjątkiem name i url. Nazwy parametrów nie rozróżniają wielkości liter.

Referencja parametrów

Parametry wymagane

url (wymagany)

• Typ: Ciąg (prawidłowy URL)
• Opis: Adres URL punktu końcowego, pod który mają być wysyłane dane zdrowotne
• Przykład: https://api.example.com/health-data
• Uwaga: Musi być prawidłowym adresem HTTP/HTTPS

name (wymagany)

• Typ: Ciąg
• Opis: Opisowa nazwa automatyzacji
• Przykład: My%20Backend%20API (zakodowane w URL: «My Backend API»)
• Uwaga: W razie spacji lub znaków specjalnych należy zakodować w URL

Konfiguracja podstawowa

format

• Typ: Enum (json, csv)
• Domyślnie: json
• Opis: Format eksportu danych
• Przykład: format=json lub format=csv
• Uwaga: Format CSV automatycznie włącza agregację danych

enabled

• Typ: Wartość logiczna (true, false, 1, 0, yes, no)
• Domyślnie: false
• Opis: Czy automatyzacja ma być włączona zaraz po utworzeniu
• Przykład: enabled=true

datatype

• Typ: Enum (patrz typy danych poniżej)
• Domyślnie: healthMetrics
• Opis: Rodzaj eksportowanych danych zdrowotnych
• Przykład: datatype=workouts
• Uwaga: Można wybrać tylko jeden typ danych. Ustawia to automatycznie odpowiednie flagi uwzględniania.

Prawidłowe typy danych:

• healthMetrics – Metryki zdrowotne (kroki, tętno, sen itd.)
• workouts – Treningi i aktywność
• symptoms – Objawy i stany zdrowia
• ecg – Zapisy EKG
• heartRateNotification – Zdarzenia wysokiego/niskiego tętna
• stateOfMind – Nastrój i stan psychiczny (iOS 18.0+)
• cycleTracking – Cykl miesiączkowy i zdrowie reprodukcyjne
• medications – Logi leków i przestrzeganie zaleceń (iOS 26.0+)

Ustawienia eksportu

period

• Typ: Enum
• Domyślnie: none
• Opis: Zakres dat eksportu danych
• Przykład: period=today

Prawidłowe wartości:

• none – Domyślnie (cały poprzedni dzień plus bieżący dzień)
• lastsync – Od ostatniej synchronizacji
• today – Bieżący dzień
• yesterday – Poprzedni dzień
• previous7days – Ostatnie 7 dni
• realtime – Aktualizacje w czasie rzeczywistym (wymaga interwału synchronizacji w sekundach)

interval

• Typ: Enum
• Domyślnie: none
• Opis: Interwał grupowania/agregacji czasowej (tylko dla typu danych healthMetrics)
• Przykład: interval=hours

Prawidłowe wartości:

• none – Domyślnie (brak agregacji)
• minutes – Grupowanie co minutę
• hours – Grupowanie co godzinę
• days – Grupowanie co dzień
• weeks – Grupowanie co tydzień
• months – Grupowanie co miesiąc
• years – Grupowanie co rok

Uwaga: Ten parametr ma zastosowanie tylko przy datatype=healthMetrics. Format CSV zawsze agreguje dane.

aggregatedata

• Typ: Wartość logiczna
• Domyślnie: true (dla CSV), false (dla JSON)
• Opis: Czy agregować/podsumowywać dane (tylko dla healthMetrics w formacie JSON)
• Przykład: aggregatedata=true
• Uwaga: Przy format=csv ustawiane automatycznie na true

aggregatesleep

• Typ: Wartość logiczna
• Domyślnie: true
• Opis: Czy agregować dane snu
• Przykład: aggregatesleep=true

exportversion

• Typ: Enum (v1, v2, 1, 2)
• Domyślnie: v2
• Opis: Wersja formatu eksportu
• Przykład: exportversion=v2
• Uwaga: Wersja 2 zawiera rozszerzone dane treningów i bogatsze metadane

batchrequests

• Typ: Wartość logiczna
• Domyślnie: false
• Opis: Wysyłanie danych partiami w wielu żądaniach (tylko dla REST API w formacie JSON)
• Przykład: batchrequests=true
• Uwaga: Tylko przy format=json i exportDestination=restApi

Częstotliwość synchronizacji

syncinterval

• Typ: Enum
• Domyślnie: minutes
• Opis: Interwał częstotliwości synchronizacji
• Przykład: syncinterval=hours

Prawidłowe wartości:

• minutes – Synchronizacja co N minut
• hours – Synchronizacja co N godzin
• days – Synchronizacja co N dni
• weeks – Synchronizacja co N tygodni
• seconds – Tylko przy period=realtime

Uwaga: W automatyzacjach REST API dozwolone są tylko minutes, hours, days i weeks, chyba że używasz eksportu w czasie rzeczywistym.

syncquantity

• Typ: Liczba całkowita dodatnia
• Domyślnie: 5
• Opis: Liczba interwałów między synchronizacjami
• Przykład: syncquantity=10 (synchronizacja co 10 minut, jeśli syncinterval=minutes)
• Uwaga: Musi być większa od 0

Konfiguracja HTTP

headers

• Typ: Ciąg (pary klucz-wartość rozdzielone przecinkami)
• Domyślnie: Brak
• Opis: Nagłówki HTTP do uwierzytelniania lub metadanych
• Przykład: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Format: key1,value1,key2,value2,...
• Uwaga: Wartości należy zakodować w URL. Każdy nagłówek wymaga klucza i wartości.

Przykładowe nagłówki:

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

requesttimeout

• Typ: Liczba całkowita (60–86400)
• Domyślnie: 60
• Opis: Limit czasu żądania w sekundach
• Przykład: requesttimeout=300
• Uwaga: Od 60 do 86400 sekund (1 minuta do 24 godzin)

Ustawienia specyficzne dla typu danych

Ustawienia metryk zdrowotnych

metrics

• Typ: Ciąg (rozdzielone przecinkami wartości MetricName rawValues)
• Domyślnie: Wszystkie dostępne metryki
• Opis: Konkretne metryki do uwzględnienia (tylko dla healthMetrics)
• Przykład: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Uwaga: Używaj dokładnych MetricName rawValues. Jeśli pominięte, uwzględniane są wszystkie dostępne metryki.

Typowe nazwy metryk:

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

Pełną listę znajdziesz na ekranie wyboru metryk w aplikacji.

Ustawienia treningów

includeroutes

• Typ: Wartość logiczna
• Domyślnie: true
• Opis: Uwzględnianie danych trasy dla treningów (tylko dla workouts)
• Przykład: includeroutes=true

includeworkoutmetadata

• Typ: Wartość logiczna
• Domyślnie: true
• Opis: Uwzględnianie metryk zebranych podczas treningu (tętno, kalorie itd.; tylko dla workouts)
• Przykład: includeworkoutmetadata=true

workoutsmetadatainterval

• Typ: Enum (minutes, seconds)
• Domyślnie: minutes
• Opis: Grupowanie czasowe metryk treningu (tylko dla workouts z wersją eksportu v2)
• Przykład: workoutsmetadatainterval=seconds
• Uwaga: Tylko przy datatype=workouts i exportversion=v2

workouttypes

• Typ: Ciąg (wartości UInt rozdzielone przecinkami)
• Domyślnie: Puste (wszystkie typy treningów)
• Opis: Konkretne typy treningów do uwzględnienia (tylko dla workouts)
• Przykład: workouttypes=1,2,3
• Uwaga: Wykorzystuje identyfikatory typów treningów HealthKit

Powiadomienia

notifyonupdate

• Typ: Wartość logiczna
• Domyślnie: true
• Opis: Powiadomienia przy aktualizacji danych w pamięci podręcznej
• Przykład: notifyonupdate=true

notifywhenrun

• Typ: Wartość logiczna
• Domyślnie: true
• Opis: Powiadomienia przy każdym uruchomieniu automatyzacji
• Przykład: notifywhenrun=false

Przykłady

Podstawowa automatyzacja REST API

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

Tworzy prostą automatyzację wysyłającą dane JSON do podanego punktu końcowego.

Z nagłówkami uwierzytelniania

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

Tworzy automatyzację z niestandardowymi nagłówkami uwierzytelniania.

Metryki zdrowotne z wybranymi metrykami

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

Tworzy automatyzację eksportującą tylko kroki i tętno z agregacją godzinową.

Treningi z danymi trasy

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

Tworzy automatyzację treningów z trasą i metrykami treningu, wersja eksportu 2.

Pełny przykład konfiguracji

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

Kompleksowy przykład z ustawionymi głównymi parametrami.

Przykład formatu CSV

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

Tworzy automatyzację eksportu CSV. Format CSV automatycznie włącza agregację danych.

Kodowanie URL

Znaki specjalne w wartościach parametrów muszą być zakodowane w URL. Typowe kodowania:

• Spacja: %20
• Przecinek: %2C
• Dwukropek: %3A
• Średnik: %3B
• Znak równości: %3D
• Ampersand: %26
• Plus: %2B

Przykład:

• Oryginał: My Automation Name
• Zakodowane: My%20Automation%20Name

Przykład nagłówków:

• Oryginał: Authorization, Bearer token123
• Zakodowane: Authorization,Bearer%20token123

Większość języków programowania i narzędzi oferuje funkcje kodowania URL:

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

Testowanie deep linków

Z Safari (iOS)

1. Otwórz Safari na urządzeniu z iOS
2. Wpisz adres deep linka w pasku adresu
3. Stuknij Idź
4. Aplikacja powinna się otworzyć i utworzyć automatyzację

Z Terminala (macOS / symulator iOS)

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

Z Xcode

Ustaw punkt przerwania lub użyj konsoli debuggera:

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

Z aplikacji Skróty

1. Utwórz nowy skrót
2. Dodaj czynność «Otwórz URL»
3. Wpisz adres deep linka
4. Uruchom skrót

Rozwiązywanie problemów

Typowe problemy

"Could not parse the URL"

• Sprawdź, czy schemat URL jest poprawny: com.HealthExport://automation
• Upewnij się, że wszystkie wartości parametrów są prawidłowo zakodowane w URL
• Sprawdź pisownię nazw parametrów (bez rozróżniania wielkości liter)

"Invalid URL parameter value"

• Upewnij się, że URL jest prawidłowym adresem HTTP/HTTPS
• Sprawdź kodowanie URL
• Upewnij się, że URL nie zawiera niedozwolonych znaków

"Invalid data type"

• Używaj dokładnych wartości typów: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Sprawdź pisownię (dopasowanie bez rozróżniania wielkości liter jest obsługiwane)

"Invalid sync cadence interval"

• Dla REST API używaj tylko: minutes, hours, days, weeks
• seconds tylko przy period=realtime

"Aggregation settings are only valid for healthMetrics data type"

• Parametry aggregatedata i interval działają tylko z datatype=healthMetrics
• Usuń te parametry lub zmień typ danych

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

• batchrequests działa tylko przy format=json
• Zmień format na JSON lub usuń parametr batchrequests

"Workout settings are only valid for workouts data type"

• includeroutes, includeworkoutmetadata i workoutsmetadatainterval działają tylko z datatype=workouts
• Zmień typ danych na workouts lub usuń te parametry

"Metrics parameter is only valid for healthMetrics data type"

• Parametr metrics działa tylko z datatype=healthMetrics
• Zmień typ danych lub usuń metrics

"Invalid metric name"

• Używaj dokładnych MetricName rawValues (np. «Step Count», «Heart Rate»)
• Sprawdź pisownię i wielkość liter
• Zobacz ekran wyboru metryk w aplikacji

"Invalid request timeout"

• Musi być między 60 a 86400 sekundami
• Użyj wartości z tego zakresu

"A name is required for the automation"

• Upewnij się, że parametr name jest podany
• Sprawdź, że po dekodowaniu URL wartość nie jest pusta

Ograniczenia długości URL

Bardzo długie adresy URL (zwłaszcza z wieloma metrykami lub nagłówkami) mogą przekraczać limity systemowe. Rozważ:

• mniej metryk w parametrze metrics
• mniej nagłówków
• krótsze wartości parametrów tam, gdzie to możliwe
• podział złożonej konfiguracji na kilka prostszych automatyzacji

Pierwszeństwo parametrów

Gdy parametry są sprzeczne:

1. Wybór typu danych (datatype) resetuje flagi uwzględniania
2. Format CSV (format=csv) automatycznie ustawia aggregatedata=true
3. Okres rzeczywisty (period=realtime) wymaga syncinterval=seconds
4. Dla niezgodnych kombinacji zgłaszane są błędy walidacji

Dobre praktyki

1. Automatyczna synchronizacja (gdy automatyzacje są uruchamiane przez deep linki):

   • Ładuj urządzenie i używaj Lusterka iPhone’a
     • Podczas ładowania iOS nakłada mniej ograniczeń na wydajność, więc dane mogą synchronizować się częściej
     • Lusterko iPhone’a sprawia, że urządzenie zachowuje się jak odblokowane, więc Health Auto Export ma dostęp do danych zdrowotnych dla działań automatycznych

2. Zawsze koduj w URL wartości parametrów ze znakami specjalnymi

3. Najpierw testuj proste URL-e, potem dodawaj złożoność

4. Używaj opisowych nazw dla łatwiejszej identyfikacji

5. Waliduj adresy URL przed programowym tworzeniem deep linków

6. Obsługuj błędy przy parsowaniu deep linków

7. Dokumentuj formaty deep linków, jeśli budujesz narzędzia je generujące

8. Uwzględniaj długość URL przy wielu metrykach lub nagłówkach

9. Testuj na rzeczywistych urządzeniach oraz na symulatorach

Powiązana dokumentacja

• Przewodnik po automatyzacji REST API – Szczegóły automatyzacji REST API
• Przegląd automatyzacji – Ogólne pojęcia dotyczące automatyzacji
• Przewodnik po eksporcie ręcznym – Ręczny eksport danych

Wsparcie

Jeśli napotkasz problemy nieopisane w tym przewodniku:

1. Przeczytaj komunikat błędu pod kątem problemów z parametrami
2. Sprawdź poprawność kodowania URL
3. Najpierw przetestuj minimalny adres URL
4. Skorzystaj z przycisku czatu wsparcia w aplikacji