| Phase |
Android Support |
Major Features |
Critical Fixes |
๐ Phase 1 Core Stability |
- โ
Android 5.0-7.0
- โ
Android 8.0-10.0
- โ
Android 11.0-12.0
|
- ๐ง Basic Virtual Engine
- ๐ฑ App Cloning Support
- ๐ฏ Multi-User System
- ๐ Basic Sandboxing
|
- ๐ Compilation Error Fixes
- ๐ Basic Stability Issues
- ๐ Memory Leak Prevention
|
โก Phase 2 Performance |
- โ
Android 13.0
- โ
MIUI Optimization
- โ
Tablet Support
|
- โก JAR System Overhaul
- ๐ Async Operations
- ๐พ Memory Management
- ๐ Performance Monitoring
|
- ๐ง APK Path Resolution
- ๐ง Resource Loading Fixes
- ๐ง Context Creation Issues
- ๐ง Freezing Bug Elimination
|
๐ก๏ธ Phase 3 Security |
- โ
Android 14.0
- โ
Enhanced Permissions
- โ
Scoped Storage
|
- ๐ก๏ธ Enhanced Sandboxing
- ๐ UID Security Management
- ๐ต๏ธ Xposed Anti-Detection
- ๐ File Integrity Verification
|
- ๐ Security Exception Handling
- ๐ UID Mismatch Resolution
- ๐ Permission Crashes
- ๐ Sandboxed Environment Issues
|
๐ฏ Phase 4 Modern Support |
- โ
Android 15.0
- โ
Latest Security Model
- โ
Edge-to-Edge UI
- โ
64-bit Mandatory
|
- ๐ Multi-Architecture Support
- ๐จ Modern UI Compatibility
- ๐ Advanced Location Spoofing
- ๐ก Enhanced API Support
|
- ๐ Android 15 Compatibility
- ๐ New Permission Model
- ๐ Predictive Back Gesture
- ๐ Enhanced Security Policies
|
### ๐ Android Version Compatibility Matrix
| Android Version |
API Level |
Support Status |
Key Features |
Special Notes |
| ๐ค Android 5.0-5.1 |
21-22 |
โ
Supported |
Basic virtualization, App cloning |
Minimum supported version |
| ๐ค Android 6.0 |
23 |
โ
Supported |
Runtime permissions, Enhanced security |
Permission model updates |
| ๐ค Android 7.0-7.1 |
24-25 |
โ
Supported |
Multi-window, File-based encryption |
Multi-window compatibility |
| ๐ค Android 8.0-8.1 |
26-27 |
โ
Optimized |
Background limits, Notification channels |
Background execution optimized |
| ๐ค Android 9.0 |
28 |
โ
Recommended |
Private API restrictions, Neural Networks |
Best compatibility target |
| ๐ค Android 10.0 |
29 |
โ
Optimized |
Scoped storage, Dark theme |
Scoped storage handled |
| ๐ค Android 11.0 |
30 |
โ
Optimized |
One-time permissions, Bubbles |
Enhanced privacy support |
| ๐ค Android 12.0 |
31 |
โ
Optimized |
Material You, Privacy dashboard |
Material Design 3 support |
| ๐ค Android 13.0 |
33 |
โ
Enhanced |
Themed icons, Per-app languages |
Granular permissions |
| ๐ค Android 14.0 |
34 |
โ
Enhanced |
Predictive back, Partial photo access |
Target SDK version |
| ๐ค Android 15.0 |
35 |
โ
Fully Supported |
Enhanced security, Edge-to-edge |
Latest security fixes included |
### ๐ฏ Feature Implementation Status
#### โ
Completed Features
- **๐ง Core Virtual Engine** - Complete application virtualization
- **๐ฑ Multi-App Cloning** - Run multiple instances simultaneously
- **๐ Enhanced Sandboxing** - Isolated execution environments
- **๐ก๏ธ Xposed Integration** - Hidden framework with anti-detection
- **๐ Multi-Architecture** - ARM64, ARMv7, x86 support
- **๐ Location Spoofing** - GPS coordinate manipulation
- **โก Performance Optimization** - Memory and CPU optimizations
- **๐ Security Hardening** - UID management and permission handling
- **๐ Advanced APIs** - Comprehensive developer interfaces
#### ๐ง Enhanced in This Edition
- **๐ง APK Path Resolution** - Intelligent fallback mechanisms
- **๐ก๏ธ Security Exception Handling** - Robust error recovery
- **โก JAR System** - Complete overhaul with integrity verification
- **๐ Async Operations** - Non-blocking initialization
- **๐พ Memory Management** - Adaptive buffer sizing
- **๐ UID Security** - Enhanced sandboxed environment support
- **๐ฑ Modern Android Support** - Android 15 compatibility
- **๐จ UI Improvements** - Better error handling and user feedback
## ๐ Quick Start Guide
### Prerequisites
Before integrating BlackBox into your project, ensure you have:
- **Android Studio**: Arctic Fox or newer
- **JDK**: Version 17 or higher
- **Android SDK**: API level 24+ with build tools
- **NDK**: Version 29.0.13846066 (automatically downloaded)
### ๐ฑ Installation Methods
#### Method 1: Using Pre-built AAR (Recommended)
1. Download the latest Bcore AAR from [Telegram Channel](https://t.me/blackbox_apks)
2. Place the `.aar` file in your `app/libs/` directory
3. Add to your `app/build.gradle`:
```gradle
dependencies {
implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
}
```
#### Method 2: Building from Source
1. Clone this repository
2. Open in Android Studio
3. Build the Bcore module
4. Include the generated AAR in your project
### โ๏ธ Documentation & Resources
#### ๐ Complete User Guide
- **[Docs.md](Docs.md)** - Comprehensive user guide covering all features, installation, app management, WebView support, Google services, background jobs, troubleshooting, and advanced features
#### ๐ Release Information
- **[RELEASE_NOTES.md](RELEASE_NOTES.md)** - Detailed release notes for version 2.4.0 with all new features, improvements, and bug fixes
#### ๐ง Quick Start & Integration
- **Installation Methods**: Pre-built AAR or source code compilation
- **API Reference**: Complete developer interface documentation
- **Troubleshooting**: Common issues and solutions
- **Performance Metrics**: Benchmarks and compatibility statistics
#### ๐ Documentation Sections
- **App Management**: Install, remove, and manage virtual applications
- **WebView & Browser Support**: Complete WebView compatibility and browser apps
- **Google Services Integration**: GMS, account management, and authentication
- **Background Job Management**: WorkManager and JobScheduler support
- **Advanced Features**: UID spoofing, process management, and security
- **Troubleshooting**: Debug mode, log analysis, and problem resolution
- **API Reference**: Complete class and method documentation
- **FAQ**: Common questions and detailed answers
> ๐ก **Pro Tip**: Start with [Docs.md](Docs.md) for comprehensive usage instructions, then refer to [RELEASE_NOTES.md](RELEASE_NOTES.md) for detailed feature information.
### ๐ก๏ธ Xposed Framework Integration
BlackBox provides comprehensive Xposed support with advanced stealth capabilities:
#### Features
- **โ
Full Xposed API Support**: Compatible with most Xposed modules
- **๐ต๏ธ Anti-Detection**: Hidden from detection tools like [Xposed Checker](https://www.coolapk.com/apk/190247) and [XposedDetector](https://github.com/vvb2060/XposedDetector)
- **๐ Sandboxed Execution**: Xposed modules run in isolated environment
- **โก High Performance**: Optimized hook implementation with minimal overhead
#### Usage Example
```java
// Check Xposed availability
try {
boolean xposedAvailable = BlackBoxCore.get().isXposedEnabled();
Log.d("BlackBox", "Xposed available: " + xposedAvailable);
} catch (Exception e) {
Log.e("BlackBox", "Failed to check Xposed status", e);
}
// Install Xposed module
try {
boolean success = BlackBoxCore.get().installXposedModule(
"/sdcard/module.apk", userId);
if (success) {
Log.d("BlackBox", "Xposed module installed successfully");
}
} catch (Exception e) {
Log.e("BlackBox", "Failed to install Xposed module", e);
}
```
## ๐ ๏ธ Build Instructions
### Prerequisites
- **Android Studio**: 2023.1.1 (Hedgehog) or newer
- **JDK**: OpenJDK 17 or Oracle JDK 17
- **Android SDK**: API 24-35 with build tools 34.0.0+
- **NDK**: Version 29.0.13846066 (automatically installed)
- **Git**: For version control
### Building from Source
```bash
# Clone the repository
git clone https://github.com/your-repo/NewBlackbox.git
cd NewBlackbox
# Open in Android Studio or build via command line
./gradlew assembleDebug
# For release build
./gradlew assembleRelease
```
### Build Configuration
```gradle
// Project-level build.gradle
compileSdkVersion 35
targetSdkVersion 34
minSdkVersion 24
// App-level configuration
android {
compileSdk 35
ndkVersion "29.0.13846066"
defaultConfig {
applicationId "top.niunaijun.blackboxa"
minSdk 24
targetSdk 34
versionCode 2
versionName "2.0-r1beta"
}
}
```
## ๐ง Troubleshooting Guide
### Common Issues & Solutions
#### ๐ App Crashes on Startup
**Symptoms**: App crashes with SecurityException or NullPointerException
**Solutions**:
1. **UID Mismatch Issues**:
```java
// Check logcat for: "Calling uid: X doesn't match source uid: Y"
// Solution: Enhanced UID management is automatically handled
```
2. **Missing APK Files**:
```java
// Check logcat for: "Unable to open APK" or "I/O error"
// Solution: APK path resolution with fallback mechanisms included
```
#### ๐ Virtual Apps Won't Install
**Symptoms**: InstallPackageAsUser returns false
**Solutions**:
1. Check storage permissions
2. Verify APK file integrity
3. Ensure sufficient storage space
4. Check target architecture compatibility
#### ๐ Freezing During App Loading
**Symptoms**: App freezes when loading virtual applications
**Solutions**:
1. **Resource Loading Issues**: Enhanced error handling implemented
2. **Memory Issues**: Memory-aware buffer sizing included
3. **Context Creation Failures**: Multiple fallback mechanisms added
#### ๐ Android 15 Compatibility Issues
**Symptoms**: Crashes on Android 15 devices
**Solutions**:
1. **Security Restrictions**: Enhanced security exception handling
2. **Permission Model**: Updated permission handling for Android 15
3. **Edge-to-Edge UI**: Modern UI compatibility improvements
#### ๐ MIUI Device Issues
**Symptoms**: Crashes or instability on Xiaomi devices
**Solutions**:
1. **MIUI Security**: Special optimizations for MIUI security policies
2. **Background Restrictions**: Enhanced background execution handling
3. **Permission Management**: MIUI-specific permission handling
### ๐ Debug Checklist
- [ ] Check Android version compatibility (5.0-15.0)
- [ ] Verify device architecture (ARM64/ARMv7/x86)
- [ ] Ensure storage permissions granted
- [ ] Check available storage space (>100MB)
- [ ] Monitor logcat for specific error messages
- [ ] Test with different target architecture builds
### ๐ Logging & Debugging
```java
// Enable debug logging
Log.d("BlackBox", "Debug message");
Log.e("BlackBox", "Error message", exception);
// Monitor key components
- APK path resolution
- UID management
- Security exceptions
- Context creation
- JAR file operations
```
## ๐ค Contributing to the Project
### Project Architecture
- **๐ฑ App Module**: User interface and interaction handling (Kotlin)
- **โ๏ธ Bcore Module**: Core virtual engine functionality (Java/Kotlin)
- **๐ง Native Core**: Low-level system integration
- **๐ Utils**: Utility classes and helper functions
### Contribution Guidelines
1. **Code Quality**: Follow existing code style and patterns
2. **Documentation**: Document new features and APIs
3. **Testing**: Test on multiple Android versions and devices
4. **Commit Messages**: Use clear, descriptive commit messages (English/Chinese OK)
5. **Pull Requests**: Provide detailed descriptions of changes
### Development Focus Areas
- **๐ง Core Engine**: Virtual application management improvements
- **๐ก๏ธ Security**: Enhanced sandboxing and permission handling
- **โก Performance**: Memory and CPU optimization
- **๐ฑ Compatibility**: Support for newer Android versions
- **๐จ UI/UX**: Improved user interface and experience
## ๐ Future Roadmap
### Planned Enhancements
- **๐ Enhanced Service API Virtualization**
- **๐ง Advanced Developer Interfaces**
- Virtual location manipulation
- Process injection capabilities
- Custom environment variables
- **๐ Performance Monitoring Dashboard**
- **๐ก๏ธ Advanced Security Features**
- **๐ฏ Plugin Architecture Support**
## ๐ฐ Commercial Availability & Support
### ๐ Contact ALEX502 for Commercial Use
The enhanced source code with all improvements and fixes is available for commercial licensing:
#### ๐ฑ Contact Methods
- **Telegram**: [@ALEX5402](https://t.me/ALEX5402) - Direct message for inquiries
- **Email**: Contact via Telegram for email details
- **Response Time**: Usually within 24 hours
#### ๐ผ What's Included in Commercial License
- **๐ฆ Complete Enhanced Source Code** - All fixes and improvements
- **๐ง Build Scripts & Configuration** - Ready-to-use project setup
- **๐ Comprehensive Documentation** - Implementation guides and API docs
- **๐ ๏ธ Technical Support** - Direct support from ALEX502
- **๐ Future Updates** - Access to ongoing improvements
- **๐ข Commercial Usage Rights** - Full licensing for commercial projects
#### ๐ฏ Perfect For
- **App Development Companies** - Virtual app solutions
- **Security Research** - Sandboxing and isolation studies
- **Educational Institutions** - Android virtualization research
- **Enterprise Solutions** - Custom virtual environment needs
---
## ๐ Sponsorship & Support
This project represents significant development effort in creating a stable, secure virtual engine. Your support helps continue development and maintenance.
### ๐ช Cryptocurrency Donations
- **BTC (Btc)**: `14z658gFXzNTbGEXySNJLGxwHfJmMViRaB`
- **USDT (TRC20)**: `TFNQw5HgWUS33Ke1eNmSFTwoQySGU7XNsK`
### โ Support Development
- **Buy ALEX502 a Coffee**: Help fuel continued development
- **Feature Sponsorship**: Contact for custom feature development
- **Priority Support**: Commercial users receive priority assistance
## ๐ Credits & Acknowledgments
### ๐จโ๐ป Enhanced Edition Developer
- **ALEX502** - Complete enhanced edition with comprehensive bug fixes, security improvements, and performance optimizations
### ๐ง Fixes & Improvements by ALEX502
- **APK Path Resolution System** - Intelligent fallback mechanisms for missing APK files
- **Security Exception Handling** - Robust UID management for Android 15 and MIUI devices
- **Performance Optimization** - Memory-aware buffer sizing and async operations
- **JAR System Overhaul** - Complete rewrite with integrity verification and caching
- **Error Recovery Mechanisms** - Comprehensive error handling throughout the application
- **Compilation Fixes** - Resolution of critical build and runtime errors
- **Freezing Bug Elimination** - Complete fix for NullPointerException issues
- **Context Creation Enhancement** - Multiple fallback strategies for package contexts
### ๐ Original Framework Credits
- [VirtualApp](https://github.com/asLody/VirtualApp) - Original virtual application framework
- [VirtualAPK](https://github.com/didi/VirtualAPK) - Plugin framework inspiration
- [BlackReflection](https://github.com/CodingGay/BlackReflection) - Reflection utilities
- [FreeReflection](https://github.com/tiann/FreeReflection) - Enhanced reflection support
- [Dobby](https://github.com/jmpews/Dobby) - Native hook framework for ARM/ARM64/x86/x64
- [xDL](https://github.com/hexhacking/xDL) - Android dynamic linker utilities
### License
> ```
> Copyright 2022 BlackBox
>
> Licensed under the Apache License, Version 2.0 (the "License");
> you may not use this file except in compliance with the License.
> You may obtain a copy of the License at
>
> http://www.apache.org/licenses/LICENSE-2.0
>
> Unless required by applicable law or agreed to in writing, software
> distributed under the License is distributed on an "AS IS" BASIS,
> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> See the License for the specific language governing permissions and
> limitations under the License.
> ```