Sleeptrack Foundation

Overview

This skill provides essential foundational knowledge for integrating the Asleep sleep tracking platform. It covers core concepts, authentication patterns, data structures, error handling, and platform-agnostic best practices that apply across all implementation approaches (iOS, Android, and backend API).

Use this skill when developers need to understand:

•What Asleep is and how sleep tracking works
•API authentication and key management
•Sleep session concepts and lifecycle
•Data structures (Sessions, Reports, Statistics)
•Error codes and troubleshooting
•Platform-agnostic integration patterns

Core Concepts

What is Asleep?

Asleep is a sleep tracking platform that analyzes sleep using audio-based monitoring through device microphones. The platform provides:

•Real-time sleep stage analysis: Wake, Light, Deep, REM detection
•Comprehensive sleep metrics: Efficiency, latency, total sleep time, wake after sleep onset
•Snoring detection and analysis: Snoring stages and patterns
•Multi-platform SDKs: Native iOS and Android SDKs plus REST API
•Dashboard analytics: Web-based analytics and user management

User Management

Each application user must be registered with Asleep before tracking sleep.

Key Points:

•User ID is managed by the host application (not generated by Asleep)
•One user can have multiple sleep sessions
•User data persists across sessions for trend analysis
•Users can be created, retrieved, updated, and deleted via API

Example User ID Schemes:

code

- UUID: "550e8400-e29b-41d4-a716-446655440000"
- Email-based: "user@example.com"
- App-specific: "app_user_12345"

Sleep Sessions

A session represents one complete sleep tracking period from start to stop.

Session Lifecycle States:

•IDLE: No tracking in progress
•INITIALIZING: SDK preparing resources
•INITIALIZED: Ready to start tracking
•TRACKING_STARTED: Active tracking in progress
•TRACKING_STOPPING: Ending session and uploading data

Session Requirements:

•Minimum tracking duration: 5 minutes for valid session
•Microphone access required throughout tracking
•Network connectivity needed for data upload
•One active session per user at a time

Real-time Data Access:

•Available after sequence 10
•Check every 10 sequences thereafter
•Provides preliminary sleep stage data during tracking

Sleep Reports

Reports contain comprehensive analysis of completed sleep sessions.

Report Structure:

code

Report
├── Session Metadata
│   ├── session_id
│   ├── user_id
│   ├── start_time
│   └── end_time
├── Sleep Stages Timeline
│   ├── Wake periods
│   ├── Light sleep periods
│   ├── Deep sleep periods
│   └── REM sleep periods
├── Sleep Statistics
│   ├── Total sleep time
│   ├── Time in bed
│   ├── Sleep efficiency (%)
│   ├── Sleep latency (time to fall asleep)
│   ├── Wake after sleep onset (WASO)
│   ├── Sleep stage durations
│   └── Sleep stage ratios
└── Snoring Analysis
    ├── Snoring detected (yes/no)
    ├── Snoring stages timeline
    └── Snoring statistics

Key Metrics Explained:

•
Sleep Efficiency: (Total sleep time / Time in bed) × 100%
- •Good: > 85%
- •Fair: 75-85%
- •Poor: < 75%
•
Sleep Latency: Time from lying down to falling asleep
- •Normal: 10-20 minutes
- •Fast: < 10 minutes (may indicate sleep deprivation)
- •Slow: > 20 minutes (may indicate insomnia)
•
WASO: Total wake time after initial sleep onset
- •Lower is better (indicates fewer disruptions)

Statistics

Aggregated metrics across multiple sessions for trend analysis.

Available Statistics:

•Average sleep duration over time range
•Average sleep efficiency
•Sleep stage distribution averages
•Trends and patterns

Statistics API:

code

GET /users/{user_id}/statistics/average?from={date}&to={date}

Authentication

API Key Management

All Asleep integrations require an API key for authentication.

Obtaining an API Key:

•Sign up at https://dashboard.asleep.ai
•Navigate to API key generation section
•Create API key for the application
•Store securely (never commit to version control)

Using API Keys:

For SDK Integration (iOS/Android):

kotlin

// Android
AsleepConfig.init(
    apiKey = "your_api_key_here",
    userId = "user_unique_id",
    ...
)

swift

// iOS
AsleepConfig.init(
    apiKey: "your_api_key_here",
    userId: "user_unique_id",
    ...
)

For REST API Integration:

http

GET /sessions/{session_id}
X-API-Key: your_api_key_here

Security Best Practices:

•Store API keys in environment variables or secure storage
•Never hardcode keys in source code
•Use different keys for development and production
•Rotate keys periodically
•Monitor usage in Dashboard to detect unauthorized access
•Revoke compromised keys immediately

Error Handling

Understanding error codes is critical for robust integration.

Error Categories

Critical Errors (must stop tracking): These errors indicate conditions that prevent continued tracking and require user intervention or code fixes.

Warning Errors (can continue tracking): These are transient issues that the SDK handles automatically while tracking continues.

Error Code Reference

Critical Errors

ERR_MIC_PERMISSION

•Cause: App lacks microphone access permission
•Action: Request microphone permission from user
•
Platform Notes:
- •Android: Check RECORD_AUDIO permission
- •iOS: Check NSMicrophoneUsageDescription and authorization status

ERR_AUDIO

•Cause: Microphone unavailable or in use by another app
•
Action:
- •Close conflicting apps using microphone
- •Check microphone hardware functionality
- •Verify no audio conflicts in device settings

ERR_INVALID_URL

•Cause: Malformed API endpoint URL in configuration
•Action: Verify AsleepConfig URL format
•Example Fix: Ensure base URL is valid HTTPS endpoint

ERR_COMMON_EXPIRED

•Cause: API rate limit exceeded or subscription plan expired
•
Action:
- •Check Dashboard for plan status
- •Review API usage patterns
- •Upgrade plan if needed
- •Implement rate limiting in application

ERR_UPLOAD_FORBIDDEN

•Cause: Multiple simultaneous tracking attempts with same user_id
•
Action:
- •Ensure only one device tracks per user at a time
- •Check for orphaned sessions
- •Implement proper session cleanup

ERR_UPLOAD_NOT_FOUND / ERR_CLOSE_NOT_FOUND

•Cause: Attempting to interact with non-existent or already-ended session
•
Action:
- •Verify session exists before operations
- •Handle session expiration properly
- •Implement session state management

Warning Errors

ERR_AUDIO_SILENCED

•Cause: Audio temporarily unavailable but tracking continues
•Impact: Minimal, SDK handles gracefully
•Action: Log for monitoring, tracking continues

ERR_AUDIO_UNSILENCED

•Cause: Audio restored after silence period
•Impact: Tracking resumes normally
•Action: Log for monitoring

ERR_UPLOAD_FAILED

•Cause: Network connectivity issue during data upload
•Impact: SDK will retry automatically
•
Action:
- •Verify network connectivity
- •Check for firewall/proxy issues
- •Monitor retry success

Error Handling Patterns

Distinguish Error Severity:

kotlin

// Android example
when (errorCode) {
    in criticalErrors -> {
        // Stop tracking, notify user
        stopTracking()
        showErrorDialog(errorCode)
    }
    in warningErrors -> {
        // Log and continue
        logWarning(errorCode)
    }
}

Provide User-Friendly Messages:

kotlin

fun getUserFriendlyMessage(errorCode: AsleepErrorCode): String {
    return when (errorCode) {
        ERR_MIC_PERMISSION -> "Please allow microphone access to track sleep"
        ERR_AUDIO -> "Another app is using the microphone. Please close it and try again"
        ERR_COMMON_EXPIRED -> "Your subscription has expired. Please renew to continue tracking"
        // ... more mappings
    }
}

Implement Retry Logic:

kotlin

// For network-related errors
suspend fun uploadWithRetry(maxRetries: Int = 3) {
    repeat(maxRetries) { attempt ->
        try {
            upload()
            return
        } catch (e: NetworkException) {
            if (attempt == maxRetries - 1) throw e
            delay(2.0.pow(attempt) * 1000) // Exponential backoff
        }
    }
}

Data Plan Considerations

Asleep operates on different data plans that affect API usage.

Plan Limits:

•Request rate limits
•Total sessions per month
•Data retention periods
•Feature availability

Monitoring Usage:

•Check Dashboard regularly
•Implement usage tracking in application
•Set up alerts for approaching limits
•Plan capacity for user growth

Integration Workflows

Typical Integration Flow

•
Setup Phase:
- •Obtain API key from Dashboard
- •Install SDK (iOS/Android) or configure REST API client
- •Configure authentication
•
User Registration:
- •Create user in Asleep system
- •Store user_id mapping in application
•
Sleep Tracking Session:
- •Request necessary permissions
- •Initialize SDK with user credentials
- •Start tracking session
- •Monitor session state
- •Handle real-time data (optional)
- •Stop tracking session
•
Report Generation:
- •Wait for report processing (automatic)
- •Fetch completed report
- •Display sleep analysis to user
•
Statistics & Trends:
- •Query historical sessions
- •Calculate aggregated statistics
- •Display trends over time

Common Integration Scenarios

Scenario 1: First-Time User Setup

code

User downloads app
  → Request microphone permission
  → Create Asleep user (POST /users)
  → Initialize SDK with API key + user_id
  → Guide user through first tracking session

Scenario 2: Returning User

code

User opens app
  → Load user_id from local storage
  → Initialize SDK with credentials
  → Check for existing running session (reconnect if found)
  → Display previous sleep reports

Scenario 3: Background Tracking

code

User starts tracking before sleep
  → Start foreground service (Android) / background mode (iOS)
  → Maintain microphone access
  → Handle app lifecycle events
  → Continue tracking through sleep
  → Stop tracking in morning
  → Process and display report

Platform Selection Guide

Choose the appropriate integration approach based on application type:

Use iOS SDK (sleeptrack-ios):

•Native iOS application
•Need deep iOS integration (Siri, HealthKit, etc.)
•Require iOS-specific UI patterns
•Swift/SwiftUI development

Use Android SDK (sleeptrack-android):

•Native Android application
•Need Android-specific features (foreground service, etc.)
•Require Android UI patterns
•Kotlin/Jetpack Compose development

Use REST API (sleeptrack-be):

•Backend/server-side integration
•Multi-platform web application
•Data aggregation and analytics
•Webhook-based event processing
•Cross-platform mobile framework (React Native, Flutter) with custom bridge

Resources

Official Documentation

•Main Documentation: https://docs-en.asleep.ai
•LLM-Optimized Reference: https://docs-en.asleep.ai/llms.txt
•Dashboard: https://dashboard.asleep.ai

Key Documentation Pages

•QuickStart Guide: https://docs-en.asleep.ai/docs/quickstart.md
•Sleep Data Overview: https://docs-en.asleep.ai/docs/sleep-data.md
•System Overview: https://docs-en.asleep.ai/docs/system-overview.md
•API Basics: https://docs-en.asleep.ai/docs/api-basics.md
•Webhook Guide: https://docs-en.asleep.ai/docs/webhook.md
•Sleep Environment Guidelines: https://docs-en.asleep.ai/docs/sleep-environment-guideline.md

Platform-Specific Documentation

Android:

•Get Started: https://docs-en.asleep.ai/docs/android-get-started.md
•Error Codes: https://docs-en.asleep.ai/docs/android-error-codes.md
•AsleepConfig: https://docs-en.asleep.ai/docs/android-asleep-config.md
•SleepTrackingManager: https://docs-en.asleep.ai/docs/android-sleep-tracking-manager.md

iOS:

•Get Started: https://docs-en.asleep.ai/docs/ios-get-started.md
•Error Codes: https://docs-en.asleep.ai/docs/ios-error-codes.md
•AsleepConfig: https://docs-en.asleep.ai/docs/ios-asleep-config.md
•SleepTrackingManager: https://docs-en.asleep.ai/docs/ios-sleep-tracking-manager.md

Reference Files

This skill includes detailed API reference documentation:

•references/asleep_api_reference.md: Comprehensive API endpoint reference, data structures, and integration patterns

To load this reference for detailed API information:

code

Read references/asleep_api_reference.md

Best Practices Summary

Security

•Never expose API keys in client code
•Implement secure storage for credentials
•Use HTTPS for all API communications
•Validate user permissions before operations

Performance

•Cache reports when appropriate
•Batch API requests to respect rate limits
•Implement efficient session state management
•Monitor real-time data access patterns

User Experience

•Provide clear permission rationales
•Show friendly error messages
•Display progress during tracking
•Handle app lifecycle gracefully

Reliability

•Implement comprehensive error handling
•Add retry logic for transient failures
•Log errors for debugging
•Test edge cases (interruptions, low battery, etc.)

Data Management

•Clean up old sessions appropriately
•Respect user privacy and data retention
•Implement proper user deletion flows
•Backup critical session data

Next Steps

After understanding these foundational concepts, proceed to platform-specific skills:

•iOS Development: Use sleeptrack-ios skill
•Android Development: Use sleeptrack-android skill
•Backend API Integration: Use sleeptrack-be skill

Each platform-specific skill builds on this foundation with implementation details, code examples, and platform-specific patterns.