awty_engine 0.1.0+1

A reliable, decoupled step tracking engine for Flutter applications. Provides pure step counting and goal notification services.

AWTY Engine

Are We There Yet? - A reliable, decoupled step tracking engine for Flutter applications.

What is AWTY?

AWTY Engine is a community-driven, open source Flutter package that provides pure step counting and goal notification services for any Flutter application. AWTY solves a common problem: reliably notifying users when they have taken a specific number of additional steps, even if the application is in the background, the device is asleep, or the app is killed.

Website: GamesAfoot.co | GitHub: awty-engine | Contact: [e-mail]

The Story Behind the Name

AWTY stands for "Are We There Yet?" - a phrase that brings back memories of countless family road trips where kids would repeatedly ask their parents this question. Just like those journeys, walking and fitness goals are about progress, patience, and reaching your destination.

AWTY is designed to be a service that enables walking and fitness-related games to encourage a healthier lifestyle in a fun manner. By gamifying physical activity, we hope to make fitness more engaging and accessible to everyone, turning the journey toward health goals into an enjoyable adventure rather than a chore.

Core Philosophy: Decoupling and Reusability

The engine is designed to be completely decoupled from any specific application's logic, UI, or analytics. Its sole responsibility is to count steps and report when a goal is met, firing a generic notification. This makes it a highly reliable tool that can be easily integrated into various projects (fitness apps, walking games, health trackers, etc.) with minimal maintenance.

Features

✅ What AWTY Does:

• Counts steps using the pedometer package (Android & iOS)
• Tracks progress toward step goals (e.g., "walk 1000 more steps")
• Sends immediate goalReached callbacks to the calling application
• Persists goal state across app restarts and device reboots
• Runs reliably in the background via Android foreground service
• Handles system boot step count resets (not midnight rollover)
• Prevents negative step counts through baseline management
• Provides required Android foreground service notification

❌ What AWTY Does NOT Do:

• Know anything about your app's purpose, UI, or business logic
• Handle app-specific navigation, rewards, or user messaging
• Store or process any data beyond step counts and goal status
• Provide custom notifications, sounds, or vibrations (handled by calling app)
• Integrate with analytics, user accounts, or cloud services
• Handle user-facing notifications beyond the required Android foreground service

Host applications handle everything beyond step counting: UI updates, game logic, user rewards, analytics, navigation, and app-specific messaging.

Current Status

✅ Android Support

• Fully implemented with pedometer package
• Native Android foreground service for reliable background operation
• Comprehensive step tracking with goal management
• Immediate goalReached callbacks via platform channel
• Required foreground service notification for background operation

📱 iOS Support - Coming Soon!

Note: As of this first release, AWTY Engine does not yet support iOS devices.

I recently got my iPhone and plan to implement iOS support using HealthKit background delivery. This will be added in a future release through community contributions.

Testing Features

🧪 Test Mode - Available Now!

AWTY Engine includes a test mode feature to make development and testing easier. When test mode is enabled, AWTY will automatically reach the goal after 60 seconds, regardless of the actual number of steps taken.

This feature is particularly useful for:

• Development: Test goal completion without walking
• Debugging: Verify notification and callback systems
• Demos: Show functionality without requiring physical activity
• UI Testing: Test app responses to goal completion

Test mode maintains the same API interface, simply adding an optional testMode parameter to the startStepTracking() method. This ensures backward compatibility while providing a powerful testing tool for developers.

Implementation Status: ✅ Fully implemented and tested

Installation

Add AWTY Engine to your pubspec.yaml:

dependencies:
  awty_engine: ^0.1.0

Quick Start

1. Initialize AWTY Integration

// In main.dart or app initialization
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize AWTY integration
  await AwtyIntegration.initialize();
  
  runApp(MyApp());
}

2. Start Step Tracking

// Start tracking 1000 additional steps
await AwtyIntegration.startStepTracking(
  deltaSteps: 1000,  // Notify when 1000 more steps are taken
  goalId: 'unique_goal_id',
  appName: 'MyApp',  // App name for notifications
);

3. Handle Goal Completion

// Set up goal completion callback
AwtyIntegration.onGoalReached = (String goalId) {
  // Handle goal completion
  print('Goal reached: $goalId');
  // Update UI, show celebration, etc.
};

// Set up error callback
AwtyIntegration.onError = (String error) {
  print('AWTY error: $error');
  // Handle errors
};

4. Monitor Progress (Optional)

// Monitor progress with timers
Timer.periodic(Duration(seconds: 5), (_) async {
  final progress = await AwtyIntegration.getCurrentProgress();
  if (progress != null) {
    updateUI(progress.stepsTaken, progress.stepsRemaining);
  }
});

Use Cases

AWTY Engine works for any app that needs step-based goals:

🎮 Walking Games

// Track steps for a game level
await AwtyEngine.startStepTracking(
  deltaSteps: 1500,
  goalId: 'level_${currentLevel}_${playerId}',
  appName: 'WalkingGame',
);

🏃‍♂️ Fitness Apps

// Start a daily step goal
await AwtyEngine.startStepTracking(
  deltaSteps: 10000,
  goalId: 'daily_${DateFormat('yyyy-MM-dd').format(DateTime.now())}',
  appName: 'FitnessTracker',
);

🚚 Delivery/Rideshare Apps

// Track walking to pickup location
await AwtyEngine.startStepTracking(
  deltaSteps: 500,
  goalId: 'pickup_walk_${orderId}',
  appName: 'DeliveryApp',
);

📚 Educational Apps

// Science lesson while walking
await AwtyEngine.startStepTracking(
  deltaSteps: 2000,
  goalId: 'lesson_${lessonId}_segment_${segmentId}',
  appName: 'WalkingLessons',
);

Android Setup

Add required permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

Note: AWTY uses the pedometer package which handles step counting through device sensors, so Health Connect permissions are not required.

About GamesAfoot.co

GamesAfoot.co is passionate about promoting and marketing walking-related fitness apps, especially games. We believe that combining physical activity with engaging gameplay creates a powerful incentive for people to stay active and healthy.

Our mission is to support the development of innovative walking-based applications that make fitness fun and accessible to everyone. AWTY Engine is our contribution to the Flutter community, designed to help developers create reliable, engaging walking experiences.

Open Source Strategy

AWTY Engine is developed as an open source contribution to the Flutter community with the following goals:

• Fill Market Gap: No existing Flutter packages provide reliable background step tracking with goal management
• Universal Tool: One step counter that works for any app type—fitness, games, education, delivery, healthcare
• Community Development: Enable iOS support and broader device compatibility through community contributions
• Quality Through Usage: More diverse apps using AWTY means better testing across devices and scenarios
• Developer Adoption: Open source removes barriers vs. paid packages, enabling widespread adoption

License: MIT (allows commercial use, modification, and distribution)

Contributing

We welcome contributions from the Flutter community! Areas where help is especially needed:

• iOS Implementation: HealthKit integration and background delivery
• Device Testing: Testing across different Android versions and manufacturers
• Feature Enhancement: Additional health data types, notification customization
• Documentation: Examples, tutorials, and integration guides

Community Governance

• Maintainers: Core team provides oversight and release management
• Contributors: Community members can submit PRs for features and fixes
• Issues: GitHub issues used for bug reports and feature requests
• Releases: Semantic versioning with regular updates to pub.dev

Battery Optimization

For reliable background operation, host applications should request users to exempt the app from battery optimizations (set to "Unrestricted" mode) via system settings. This is critical for ensuring the AWTY engine can deliver milestone notifications and track steps in the background, especially on devices with aggressive battery management.

Documentation

For detailed technical specifications, architecture, and implementation details, see the AWTY Specification.

Links

• Package: pub.dev/packages/awty_engine
• Repository: GitHub
• Company: GamesAfoot.co

License

This project is licensed under the MIT License - see the LICENSE file for details.