Skip to main content

SDK Initialization

Obtain your API key from the Developer Portal.

Understanding SDK Initialization​

When you initialize the SDK, several critical processes occur:

  1. API Authentication: Your API key is validated against the Autonomic Health API
  2. Test Configuration Retrieval: The SDK fetches a dynamic test configuration tailored to the specific user context
  3. Device Manager Setup: Selected device adapters are initialized and ready for Bluetooth pairing

Dynamic Test Configuration​

The test configuration object is particularly important - it's not a static configuration you define in code. Instead, it's dynamically generated server-side and returned after initialization when you present the test flow.

Why Dynamic Configuration?

Test protocols must adapt to each patient's unique clinical situation. A one-size-fits-all approach would either over-test healthy individuals or under-test those with complex autonomic dysfunction.

The configuration adapts based on:

User History & Previous Testing:

  • First-time users: Longer baseline periods (5-6 minutes) to establish individual autonomic norms
  • Returning users: Optimized protocols focusing on previously identified problem areas
  • Failed tests: Modified protocols addressing specific validity issues from prior attempts

Device Capabilities:

  • Native RR Intervals (Polar H10): Enables advanced HRV analysis with high-frequency components
  • BPM-only devices (Apple Watch): Adjusted algorithms with reconstruction models
  • Accelerometer availability: Motion artifacts can be filtered more aggressively

Form Completion & Requirements:

  • Required forms vary by use case (diagnostic vs wellness vs research)
  • Incomplete forms may trigger additional screening questions during test flow
  • Forms include: 28-Symptom Autonomic questionnaire, medical history, current medications, lifestyle factors

This dynamic approach ensures every test is optimized for clinical validity while maintaining personalization.

Basic Initialization​

import AHSDKCore
import AHSDKPolar

class YourViewController: UIViewController {
    var sdk: AutonomicHealthSDK!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Initialize device manager for Polar devices
        let polarManager = AHPolarDeviceManager()

        // Initialize SDK with API key and device managers
        sdk = AutonomicHealthSDK(
            apiKey: "your-api-key",
            environment: .production,
            deviceManagers: [polarManager]
        )
        sdk.delegate = self
    }
}

Choosing Device Adapters​

The SDK uses a tree-shakable architecture - you only include the device adapters you need, preventing unnecessary bloat in your application binary.

Available Adapters​

import AHSDKCore
import AHSDKPolar      // Polar H10, H9, Verity Sense, OH1
import AHSDKGarmin     // Garmin HRM-Pro, HRM-Dual, HRM-Run
import AHSDKBLEHeartRate  // Generic BLE heart rate monitors
import AHSDKWatchKit   // Apple Watch integration

// Initialize multiple device managers
let polarManager = AHPolarDeviceManager()
let garminManager = AHGarminDeviceManager()
let bleManager = AHBLEHeartRateDeviceManager()

// SDK will support all three device types
sdk = AutonomicHealthSDK(
    apiKey: "your-api-key",
    environment: .production,
    deviceManagers: [polarManager, garminManager, bleManager]
)
Device Adapter Selection

See the Installation page for a detailed cross-correlation table of supported wearables and their capabilities, including important warnings about RR interval reconstruction for BPM-only devices.

The SDK handles device capabilities automatically - you don't need to write different code paths. However, test results will include a data quality score and confidence interval reflecting the precision of the underlying sensor data.

Test Configuration Object​

After SDK initialization, the test configuration is fetched automatically when you present the test flow. This configuration includes:

// Test configuration is returned when presenting the test
sdk.presentANSChallenge(from: self, configuration: .default, animated: true)

// The configuration includes:
// - phaseDefinitions: Array of test phases (baseline, deep breathing, Valsalva, standing)
// - phaseDurations: Duration in seconds for each phase
// - requiredForms: Form IDs that must be completed before testing
// - deviceRequirements: Minimum device capabilities needed

Why Dynamic Configuration?​

Test protocols vary based on user context:

  • First-time users: May get a longer baseline period to establish individual norms
  • Follow-up testing: Shorter protocols focusing on previously-identified problem areas
  • Research studies: Standardized protocols matching clinical trial requirements

Caching Policy​

The SDK follows a strict caching policy similar to the Google Maps/Places API. This policy is designed to protect patient safety and ensure regulatory compliance.

What You CAN Cache

Only identifiers may be cached (client-side or server-side):

  • User IDs (patientId)
  • Test IDs (testId)
  • Form submission IDs (submissionId)
  • Treatment plan IDs (treatmentId)

These identifiers are stable and can be stored indefinitely for quick lookup and reference.

Example: You can cache a testId locally and use it to fetch fresh test results whenever needed.

What You CANNOT Cache

Never cache autonomic data or medical information, including:

Sensor Data & Measurements:

  • RR interval measurements (beat-to-beat timing)
  • Heart rate time series data
  • Accelerometer, gyroscope, or motion data
  • Raw sensor streams from wearables

ANS Analysis & Results:

  • P&S metrics (RFa, LFa values in bpm²)
  • Sympathovagal balance calculations
  • Phase-specific results (baseline, standing, Valsalva, breathing)
  • Test validity scores or confidence intervals
  • Data quality assessments

Clinical Information:

  • Test results or physician analysis
  • Treatment recommendations or prescriptions
  • Diagnosis codes or clinical interpretations
  • Form responses containing medical data (symptoms, medications, history)

Media & Processing Status:

  • Video recordings or frames
  • Test review status or physician notes
  • Processing state or upload progress

This data must always be fetched fresh from the API to ensure:

  • Data Integrity: No stale or outdated medical information shown to patients
  • Regulatory Compliance: HIPAA requires audit trails for all PHI (Protected Health Information) access
  • Clinical Safety: Physicians may update treatment plans or reject tests between API calls
  • Legal Liability: Displaying outdated diagnoses could constitute medical malpractice

Why This Policy?​

Medical data changes frequently and unpredictably:

Test Review Updates:

  • Physicians may mark a test as invalid hours after initial upload
  • Test status changes from pending_review → under_review → reviewed or requires_retest
  • Validity issues discovered during review require patient notification

Treatment Plan Evolution:

  • Treatment recommendations get updated as conditions evolve
  • Medication dosages may be adjusted based on new test results
  • Physicians may add contraindications or warnings after peer consultation

Form Response Amendments:

  • Patients may correct medication lists before test analysis begins
  • Medical history updates can change test interpretation
  • Incomplete forms may be completed after initial test upload

Patient Safety Scenarios: If you cached treatment data and displayed an outdated medication recommendation, you could:

  • Display a medication the physician has since contraindicated
  • Show incorrect dosages after a physician adjustment
  • Miss critical safety warnings added during review
Legal & Regulatory Implications

Caching medical data violates:

  • HIPAA Minimum Necessary Standard: Only access PHI when needed, not preemptively
  • 21 CFR Part 11: Electronic records must be traceable and auditable
  • State Medical Practice Acts: Displaying stale diagnoses may constitute practicing medicine without proper oversight

The Autonomic Health API logs every data access for regulatory compliance. Caching circumvents these audit trails.

Multiple Device Manager Support​

You can initialize the SDK with multiple device managers simultaneously:

// Support all device types in your app
let managers: [AHDeviceManager] = [
    AHPolarDeviceManager(),
    AHGarminDeviceManager(),
    AHBLEHeartRateDeviceManager(),
    AHAppleWatchDeviceManager()
]

sdk = AutonomicHealthSDK(
    apiKey: "your-api-key",
    environment: .production,
    deviceManagers: managers
)

// During test setup, users can choose any compatible device
// The SDK handles device-specific protocols automatically
Best Practice

Include multiple device managers to maximize user compatibility. The tree-shakable architecture ensures unused device SDKs don't impact your app size - only the managers you instantiate are included in the final binary.

Environment Configuration​

The SDK supports multiple environments for development and testing:

// Production environment (default)
sdk = AutonomicHealthSDK(
    apiKey: "your-production-key",
    environment: .production,
    deviceManagers: [polarManager]
)

// Staging environment for testing
sdk = AutonomicHealthSDK(
    apiKey: "your-staging-key",
    environment: .staging,
    deviceManagers: [polarManager]
)

// Development environment with verbose logging
sdk = AutonomicHealthSDK(
    apiKey: "your-dev-key",
    environment: .development,
    deviceManagers: [polarManager]
)
API Key Security

Never commit API keys to version control. Use environment variables or secure key management services:

  • iOS: Store in xcconfig files excluded from git
  • Android: Use local.properties or BuildConfig fields
  • CI/CD: Inject keys as environment variables during build

Next Steps​

Continue to Test Flow to present the ANS challenge test and understand the pre-test, test, and post-test phases.