Full Documentation - Sign-In Required

You're viewing the complete WatchOS SDK documentation. This content requires authentication.

RotationKit 🔄

Smart screen rotation technology for watchOS apps

Transform your watchOS app with patented wrist-based screen rotation that keeps your interface readable at any angle. Perfect for fitness, navigation, and outdoor activity apps.

✨ Features

🎯 Intelligent Rotation: Patented algorithm keeps your interface upright regardless of wrist position
🔄 Quick Toggle System: Instantly switch between Standard, Auto-rotation, and Manual modes
👑 Digital Crown Control: Precision manual rotation using the digital crown
🧩 Modular Widgets: Drop-in UI components for fitness, navigation, and custom data
⚡ High Performance: Optimized for 60fps with minimal battery impact (<2%)
🎨 Fully Customizable: Configure sensitivity, animations, and layouts
📦 Zero Dependencies: Self-contained with no external requirements
🛠 Easy Integration: Works with existing SwiftUI views

🚀 Quick Start

> New to RotationKit? Check out our 5-minute Quick Start Guide for the fastest way to get started!

Step 1: Get Your API Key

Visit RotationKit Developer Portal
Sign up with your email (takes 30 seconds)
Click "Create API Key"
Select platform: WatchOS
Choose type:
Developer: Free for testing and development (never expires)
Production: For App Store releases (requires license)
Copy your API key (starts with rk_dev_watchos_ or rk_live_watchos_)

Your API key enables:

📊 Real-time analytics dashboard
📈 Usage metrics and session tracking
🔍 Error monitoring and debugging
🔐 License validation for production

Step 2: Installation

Swift Package Manager (Recommended)

dependencies: [
    .package(url: "https://github.com/rotationkit/RotationKit.git", from: "1.0.0")
]

Xcode

File → Add Package Dependencies
Enter: https://github.com/rotationkit/RotationKit.git
Add to your watchOS target

Step 3: Basic Integration

import SwiftUI
import RotationKit

struct MyWatchApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

struct ContentView: View {
    // Initialize RotationKit with telemetry and analytics
    @StateObject private var rotationEngine = RotationEngine(
        configuration: RotationConfiguration(
            apiKey: "rk_dev_watchos_YOUR_KEY_HERE", // ← Paste your API key
            enableQuickToggle: true
        )
    )

    var body: some View {
        RotationHUD(rotationEngine: rotationEngine) {
            VStack {
                Text("My Fitness App")
                    .font(.headline)
                Text("Always Readable!")
                    .font(.body)
            }
            .foregroundColor(.white)
        }
    }
}

That's it! Your app now has:

✅ Intelligent auto-rotation based on wrist position
✅ Automatic session tracking
✅ Real-time analytics in your developer portal
✅ Usage metrics and engagement data

Quick Toggle Feature

Enable users to quickly switch between rotation modes with a long press:

import SwiftUI
import RotationKit

struct MyWatchView: View {
    var body: some View {
        RotationKit.toggleableHUD {
            VStack {
                Text("My App")
                    .font(.headline)
                Text("Long press to toggle modes!")
                    .font(.body)
            }
            .foregroundColor(.white)
        }
    }
}

Three Rotation Modes:

🔒 Standard: Fixed orientation, no rotation
🌐 Auto-Rotation: Gravity-based intelligent rotation (default)
👑 Manual: Digital crown controlled precision rotation

Usage:

Long press the watch face to cycle between modes
Digital crown rotation in Manual mode for precise control
Visual indicators show current mode and angle

📱 Real-World Examples

Fitness App Integration

import RotationKit

struct WorkoutView: View {
    @StateObject private var rotationEngine = RotationEngine(
        configuration: .forActivity(.fitness)
    )
    
    var body: some View {
        RotationHUD(rotationEngine: rotationEngine) {
            ZStack {
                // Progress ring
                Circle()
                    .stroke(Color.gray.opacity(0.3), lineWidth: 4)
                    .frame(width: 185, height: 185)
                
                Circle()
                    .trim(from: 0, to: workoutProgress)
                    .stroke(Color.orange, style: StrokeStyle(lineWidth: 6, lineCap: .round))
                    .frame(width: 185, height: 185)
                    .rotationEffect(.degrees(-90))
                
                // Positioned widgets
                WidgetBuilder.mixedWidgets([
                    AnyHUDWidget(TextWidget(data: "27:32", position: 0)),           // Time
                    AnyHUDWidget(IconTextWidget(                                     // Heart Rate
                        data: IconTextWidget.IconTextData(
                            iconName: "heart.fill", 
                            text: "142 bpm",
                            iconColor: .red
                        ), 
                        position: 2
                    )),
                    AnyHUDWidget(SpeedWidget(                                        // Speed
                        data: SpeedWidget.SpeedData(speed: 7.2, unit: .mph), 
                        position: 4
                    )),
                    AnyHUDWidget(TextWidget(data: "3.2 mi", position: 6))           // Distance
                ], rotationEngine: rotationEngine)
            }
        }
    }
}

struct NavigationView: View {
    @StateObject private var rotationEngine = RotationEngine(
        configuration: .forActivity(.navigation)
    )
    
    var body: some View {
        RotationHUD(rotationEngine: rotationEngine) {
            WidgetBuilder.mixedWidgets([
                AnyHUDWidget(DirectionWidget(
                    data: DirectionWidget.DirectionData(
                        direction: .turnRight,
                        distance: "0.5 mi",
                        streetName: "Main Street"
                    ),
                    position: 0
                )),
                AnyHUDWidget(TextWidget(data: "12:45 PM", position: 4))
            ], rotationEngine: rotationEngine)
        }
    }
}

🎛 Configuration Options

Rotation Mode Settings

Configure rotation modes and toggle behavior:

// Enable quick toggle with specific initial mode
var config = RotationConfiguration()
config.enableQuickToggle = true
config.rotationMode = .autoRotation
config.manualRotationSensitivity = 5.0  // Degrees per crown click
config.snapToCardinalAngles = true      // Snap to 0°, 90°, 180°, 270°

let engine = RotationEngine(configuration: config)

Programmatic Mode Control

// Create engine with toggle support
@StateObject private var rotationEngine = RotationEngine(
    configuration: RotationConfiguration(enableQuickToggle: true)
)

// Switch modes programmatically
rotationEngine.setRotationMode(.manual)
rotationEngine.setRotationMode(.standard)
rotationEngine.setRotationMode(.autoRotation)

// Manual rotation control
rotationEngine.adjustManualRotation(delta: 45.0)  // Rotate 45 degrees
rotationEngine.resetManualRotation()              // Reset to 0 degrees

Activity-Based Presets

// High sensitivity for dynamic sports
let cycling = RotationEngine(configuration: .forActivity(.fitness))

// Precision mode for navigation
let navigation = RotationEngine(configuration: .forActivity(.navigation))

// Gentle rotation for reading
let reading = RotationEngine(configuration: .forActivity(.reading))

Custom Configuration

var config = RotationConfiguration()
config.rotationSensitivity = 0.8    // Higher sensitivity
config.smoothingFactor = 0.1        // More responsive
config.maxRotationSpeed = 25.0      // Faster rotation

let engine = RotationEngine(configuration: config)

🧩 Built-in Widgets

| Widget | Description | Usage |

|--------|-------------|-------|

| TextWidget | Simple text display | Time, distance, any string |

| IconWidget | Icon with background | Status indicators, simple metrics |

| IconTextWidget | Icon + text combination | Heart rate, speed, labeled values |

| DirectionWidget | Navigation arrows | Turn-by-turn directions |

| SpeedWidget | Speed/pace display | MPH, KPH, pace per mile/km |

// 8 positions around the watch face (0-7)
TextWidget(data: "Top", position: 0)        // 12 o'clock
TextWidget(data: "Right", position: 2)      // 3 o'clock  
TextWidget(data: "Bottom", position: 4)     // 6 o'clock
TextWidget(data: "Left", position: 6)       // 9 o'clock

📊 Performance

Battery Impact: <2% additional drain
Frame Rate: Maintains 60fps during rotation
Memory Usage: <5MB additional memory
Compatibility: watchOS 9.0+, all Apple Watch models

🛠 Advanced Features

Custom Widgets

struct CustomWidget: HUDWidget {
    let data: String
    let position: Int
    let shouldCounterRotate: Bool = true
    
    var body: some View {
        Text(data)
            .font(.custom("MyFont", size: 16))
            .foregroundColor(.purple)
            .padding()
            .background(Color.black.opacity(0.5))
            .cornerRadius(10)
    }
}

Preset Layouts

// Use predefined layouts
let fitnessLayout = RotationKit.layout(for: .fitness)
let runningLayout = RotationKit.layout(for: .running)
let cyclingLayout = RotationKit.layout(for: .cycling)

Haptic Feedback

// Built-in haptic feedback
RotationKit.Haptics.light()    // Subtle feedback
RotationKit.Haptics.medium()   // Standard feedback
RotationKit.Haptics.success()  // Success indication

📊 Developer Portal & Analytics

Real-Time Dashboard

Every RotationKit integration includes access to a comprehensive developer portal with real-time analytics.

Access your portal: https://rotationkit-5ea5d.web.app

What you get:

📈 Session Metrics: Total sessions, active users, session duration
🔄 Rotation Analytics: Mode usage, angle changes, tracking duration
📱 Device Insights: Device models, watchOS versions, Apple Watch series distribution
⚠️ Error Monitoring: Error rates, crash tracking, performance metrics
🔑 API Key Management: Create, revoke, and monitor API key usage

Automatic Event Tracking

RotationKit automatically tracks these events (no code required):

session_started - When user opens your app
session_ended - When user closes your app
rotation_tracking_started - When rotation engine starts
rotation_tracking_stopped - When rotation engine stops
rotation_mode_changed - When user switches modes
rotation_angle_changed - When rotation angle changes >5°

Privacy by design:

No personal identifiable information (PII) collected
No names, emails, or phone numbers
No health data from HealthKit
Only anonymous session and usage data
GDPR/CCPA compliant by default

Custom Event Tracking

Track app-specific events for deeper insights:

import RotationKit

// Track screen views
telemetrySink.enqueue(ScreenViewedEvent(
    timestamp: Int64(Date().timeIntervalSince1970 * 1000),
    sessionId: sessionId,
    screenName: "WorkoutDetail",
    previousScreen: "WorkoutList"
))

// Track feature usage
telemetrySink.enqueue(FeatureUsedEvent(
    timestamp: Int64(Date().timeIntervalSince1970 * 1000),
    sessionId: sessionId,
    featureName: "start_workout",
    metadata: ["type": "running", "duration": "30min"]
))

// Track custom events
telemetrySink.enqueue(CustomEvent(
    timestamp: Int64(Date().timeIntervalSince1970 * 1000),
    sessionId: sessionId,
    name: "workout_completed",
    properties: [
        "type": "running",
        "distance": 5.2,
        "duration": 1800
    ]
))

Telemetry Configuration

Control telemetry behavior:

// Disable telemetry completely (not recommended)
var config = RotationConfiguration()
config.apiKey = nil  // No analytics
config.enableTelemetry = false

// Custom telemetry settings
var config = RotationConfiguration()
config.apiKey = "your_api_key"
config.telemetryBatchSize = 10       // Events per batch
config.telemetryFlushInterval = 30.0 // Seconds between flushes
config.telemetryMaxQueueSize = 1000  // Max queued events

Analytics Best Practices

Always include API key - Enables full analytics features
Use descriptive names - Make screen/feature names meaningful
Add custom events - Track app-specific user journeys
Monitor error rates - Check portal regularly for issues
Review device distribution - Optimize for popular Apple Watch models

What Data is Collected?

Automatic Events:

Session ID (ephemeral, changes per session)
Timestamp (Unix epoch milliseconds)
Device model (e.g., "Apple Watch Series 9")
watchOS version (e.g., "watchOS 10.2")
App version (from Info.plist)
Rotation mode, angle, and tracking duration

NOT Collected:

User names or emails
Location data (GPS coordinates)
Health metrics or HealthKit data
Personal identifiable information
End-user iCloud account IDs

Learn more: See TELEMETRY_EVENTS.md for complete event reference

📁 Project Structure

RotationKit/
├── Sources/
│   └── RotationKit/
│       ├── Core/                    # Core rotation technology
│       │   ├── RotationEngine.swift
│       │   └── RotationConfiguration.swift
│       ├── HUD/                     # HUD system
│       │   ├── RotationHUD.swift
│       │   └── HUDLayout.swift
│       ├── Widgets/                 # Widget components
│       │   └── HUDWidget.swift
│       ├── Utils/                   # Utilities
│       │   ├── MotionManager.swift
│       │   └── Extensions.swift
│       └── RotationKit.swift        # Public API
├── Tests/
├── Examples/
│   ├── BasicExample/               # Simple integration demo
│   ├── FitnessExample/            # Workout app example
│   └── NavigationExample/         # Turn-by-turn example
└── Documentation/

🎯 Use Cases

Perfect for:

🏃‍♂️ Fitness Apps: Keep workout metrics readable during exercise
🗺 Navigation Apps: Turn-by-turn directions that stay upright
🚴‍♀️ Cycling Apps: Power, cadence, and speed data at any handlebar position
🏔 Outdoor Apps: Hiking, climbing, and adventure sports interfaces
⌚ Watch Faces: Dynamic complications that adapt to wrist position

📚 Documentation

🚀 Examples

Run the included example projects to see RotationKit in action:

BasicExample: Simple rotation demonstration
FitnessExample: Complete workout app with metrics
NavigationExample: Turn-by-turn navigation interface

# Clone and run examples
git clone https://github.com/rotationkit/RotationKit.git
cd RotationKit/Examples/BasicExample
open BasicExample.xcodeproj

🤝 Integration Checklist

[ ] Add RotationKit dependency to your project
[ ] Import RotationKit in your watch app
[ ] Wrap main view in RotationHUD
[ ] Convert static elements to positioned widgets (optional)
[ ] Enable quick toggle for better user experience (recommended)
[ ] Add rotation mode selection to settings menu (recommended)
[ ] Test rotation sensitivity for your use case
[ ] Test all three rotation modes with your content
[ ] Optimize widget positions for your data

📄 Licensing

RotationKit watchOS SDK is available for commercial partnerships with flexible licensing options.

License Options

🔧 Developer License (Free Forever)

✅ Full SDK access for development and testing
✅ Complete analytics dashboard
✅ Unlimited API key generation
✅ Never expires
✅ Perfect for prototyping and evaluation
❌ Not for production deployment

💼 Commercial License (Contact Sales)

✅ Production deployment rights for App Store
✅ Single application license
✅ Backend license validation
✅ Priority email support (<24hr response)
✅ 1 year of updates and bug fixes
✅ Full telemetry and analytics
💰 Pricing: Contact for quote

🏢 Enterprise License (Contact Sales)

✅ Everything in Commercial License
✅ Multiple applications (up to 5)
✅ White-label options available
✅ Dedicated Slack channel
✅ Integration consultation (up to 10 hours)
✅ Priority feature requests
✅ Custom SLA agreements
💰 Pricing: Contact for quote

How Licensing Works

Development Phase (Free)
Create Developer API key in portal
Use key starting with rk_dev_watchos_
Full SDK functionality for testing

Production Deployment (Requires License)
Purchase Commercial or Enterprise license
Create Production API key in portal
Use key starting with rk_live_watchos_
Backend validates license on first app launch

License Validation
Automatic validation against Firebase backend
Runs once per device installation
Cached locally after first validation
No recurring checks (no internet required after first launch)

Get a Production License

Contact Sales: licensing@rotationkit.com
Provide:
App name and bundle ID
Expected user count
Deployment timeline
Receive license agreement and pricing quote
Sign agreement and complete payment
Production API key activated in your portal within 24 hours

Contact: licensing@rotationkit.com

🆘 Support

📧 Technical Support: support@rotationkit.com
💬 Discord Community: discord.gg/rotationkit
📚 Documentation: docs.rotationkit.com
🐛 Issues: GitHub Issues

🔄 Version History

1.0.0 (Current)

✅ Initial release
✅ Core rotation engine with patented algorithm
✅ Quick toggle system with three rotation modes
✅ Digital crown integration for manual rotation
✅ Long press gesture support for mode switching
✅ Modular widget system
✅ Preset layouts for common use cases
✅ Performance optimized for watchOS 9.0+
✅ Comprehensive documentation and examples

See CHANGELOG.md for complete version history.

🙏 Acknowledgments

RotationKit is built with ❤️ for the watchOS developer community. Special thanks to early beta testers and the fitness app developers who provided invaluable feedback.

Made with ❤️ by the RotationKit Team

Transform your watchOS app today - because your users' comfort matters.

Get Started → | View Examples → | API Reference →

RotationKit 🔄

✨ Features

🚀 Quick Start

Step 1: Get Your API Key

Step 2: Installation

Step 3: Basic Integration

Quick Toggle Feature

📱 Real-World Examples

Fitness App Integration

Navigation App Integration

🎛 Configuration Options

Rotation Mode Settings

Programmatic Mode Control

Activity-Based Presets

Custom Configuration

🧩 Built-in Widgets

Widget Positioning

📊 Performance

🛠 Advanced Features

Custom Widgets

Preset Layouts

Haptic Feedback

📊 Developer Portal & Analytics

Real-Time Dashboard

Automatic Event Tracking

Custom Event Tracking

Telemetry Configuration

Analytics Best Practices

What Data is Collected?

📁 Project Structure

🎯 Use Cases

📚 Documentation

🚀 Examples

🤝 Integration Checklist

📄 Licensing

License Options

How Licensing Works

Get a Production License

🆘 Support

🔄 Version History

1.0.0 (Current)

🙏 Acknowledgments