تجربة ترقية مشروع Flutter إلى Target API 35: اتباع متطلبات متجر Google Play الجديدة

اعتباراً من أغسطس 2025، يطلب متجر Google Play من جميع التطبيقات الجديدة والتحديثات أن تستهدف API level 35 (Android 15). إليكم تجربتي في ترقية مشاريع Flutter لتلبية متطلبات متجر التطبيقات الجديدة.

🔧 التغييرات الرئيسية

1. تحديث compileSdkVersion و targetSdkVersion

في ملف android/app/build.gradle:

android {
    compileSdkVersion 35  // سابقاً: 34 أو أقدم
    
    defaultConfig {
        targetSdkVersion 35  // سابقاً: 34 أو أقدم
        // ... باقي الإعدادات
    }
}

2. إعدادات Flutter Local Notifications (في حالة الاستخدام)

⚠️ ملاحظة مهمة: هذه الخطوة مطلوبة فقط إذا كان مشروعك يستخدم plugin flutter_local_notifications. إذا لم تكن تستخدم هذا البرنامج المساعد، انتقل إلى الخطوة 3.

أ. إضافة Core Library Desugaring

في ملف android/app/build.gradle:

android {
    compileSdkVersion 35
    
    compileOptions {
        coreLibraryDesugaringEnabled true
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    
    defaultConfig {
        targetSdkVersion 35
        minSdkVersion 21  // تأكد من الحد الأدنى SDK 21 أو أعلى
        // ... باقي الإعدادات
    }
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
    coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.0.4"
}

ب. تحديث صلاحيات الإشعارات

في ملف android/app/src/main/AndroidManifest.xml:

<!-- صلاحيات الإشعارات الموجودة -->
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.VIBRATE" />

<!-- مطلوبة لـ API 35+ -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />

وتحديث إعدادات الخدمة:

<application>
    <!-- ... الإعدادات الموجودة ... -->
    
    <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ActionBroadcastReceiver" />
    <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationReceiver" />
</application>

3. تحديث Android Gradle Plugin

في ملف android/build.gradle:

dependencies {
    classpath 'com.android.tools.build:gradle:8.3.2'  // تحديث إلى أحدث إصدار
    // ... باقي التبعيات
}

4. تحديث Gradle Wrapper

في ملف android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-all.zip

5. إضافة Build Logger (اختياري)

إذا كنت تريد تسجيل تفاصيل إصدارات Flutter/Dart أثناء البناء لمساعدة المطورين الجدد على إعداد البيئة المحلية، أضف هذا إلى android/build.gradle:

// BUILD LOGGER - لتتبع إصدارات البيئة
def buildId = UUID.randomUUID().toString().substring(0, 8)
def buildStartTime = new Date()
def buildStatus = "SUCCESS"
def hasLoggedThisBuild = false

gradle.taskGraph.afterTask { task, state ->
    if (state.failure) {
        buildStatus = "FAILED"
    }
    
    def mainTasks = ['assembleRelease', 'assembleDebug', 'bundleRelease', 'bundleDebug']
    
    if (task.name in mainTasks && !hasLoggedThisBuild) {
        def endTime = new Date()
        def duration = (endTime.time - buildStartTime.time) / 1000
        
        def pubspec = new File("${rootDir.parent}/pubspec.yaml")
        def versionLine = pubspec.readLines().find { it.startsWith("version:") }
        def appVersion = versionLine?.replace("version:", "")?.trim() ?: "unknown"
        def flutterVersion = "flutter --version".execute().text.trim()
        def logFile = new File("${rootDir.parent}/build_history.md")
        
        if (!logFile.exists()) {
            logFile.text = "# Build History\n\n"
        }
        
        def buildLog = """
## Build ${buildId}
- **App Version:** ${appVersion}
- **Date:** ${endTime.format("dd/MM/yyyy HH:mm:ss")}
- **Build Type:** ${task.name}
- **Duration:** ${duration}s
- **Status:** ${buildStatus}
- **Flutter Version:** ${flutterVersion.split('\n')[0]}

---
"""
        
        logFile.text = buildLog + logFile.text
        hasLoggedThisBuild = true
    }
}

🚨 أمور يجب الانتباه إليها

1. احفظ نسخة احتياطية من مشروعك قبل الترقية
2. اختبر على أجهزة Android مختلفة بعد الترقية
3. انتبه للتغييرات الجذرية في التبعيات التي تستخدمها
4. حدث جميع البرامج المساعدة إلى أحدث الإصدارات التي تدعم API 35
5. core library desugaring مطلوب فقط عند استخدام برامج مساعدة معينة مثل flutter_local_notifications

💡 نصائح حل المشاكل

• إذا حصلت على أخطاء AAPT2، احذف مجلد android/.gradle وأعد البناء
• تأكد من تثبيت Android SDK Platform 35 في Android Studio
• استخدم flutter doctor للتأكد من صحة البيئة
• إذا لم تكن تستخدم flutter_local_notifications، تخط إعدادات desugaring
• إذا حصلت على أخطاء متعلقة بـ desugaring، تأكد من صحة توافق Java 8

🎯 الخلاصة

الترقية إلى API 35 مباشرة جداً لمعظم مشاريع Flutter - فقط حدث compileSdkVersion و targetSdkVersion إلى 35. الإعدادات الإضافية مثل core library desugaring مطلوبة فقط عند استخدام برامج مساعدة معينة تتطلب ميزات Java 8+.

أهم شيء هو الاختبار الشامل بعد الترقية للتأكد من أن جميع الميزات ما زالت تعمل بشكل صحيح.

📚 المراجع

• دليل توافق Android 15
• إعدادات بناء Flutter Android
• متطلبات Google Play
• Core Library Desugaring

هذا المقال مبني على تجربة ترقية مشاريع Flutter الإنتاجية إلى target API 35. إذا كان لديك أسئلة أو مشاكل أخرى، لا تتردد في المناقشة!