عاجلًا أو آجلًا يحتاج تطبيق الهاتف أن يطلب من مستخدميه التحديث. أحيانًا يكون اقتراحًا: صدرت نسخة جديدة وهذا ما تغيّر. وأحيانًا يكون شرطًا: النسخة القديمة تتصل بـ API لم يعد موجودًا، والسماح بالدخول لن يُري الناس إلا أخطاء.
الآلية سهلة الوصف. يسأل التطبيق الخادم "ما أدنى نسخة مقبولة، وما أحدث نسخة؟"، ويقارن ذلك بنسخته، ثم يعرض نافذة حوار أو صفحة تمنع الدخول. والجزء الخطير هو صفحة المنع. إذا كانت القاعدة خاطئة، فخطأ مطبعي في رقم النسخة أو ملف JSON عُدّل نصفه قد يحبس كل المستخدمين خارج التطبيق، ومنهم من نسخته محدَّثة تمامًا. ولا تستطيع إصلاح تطبيق محبوس بتحديث لا يمكن إخبار المستخدمين به.
update_gate حزمة (package) لـ Flutter لهذه النوافذ. تعمل مع أي مصدر لقواعد النسخ: endpoint يُرجع JSON خاص بك، أو Remote Config، أو قاعدة بيانات. وهي تفشل نحو الفتح (fails open)، أي أن القاعدة المعطوبة لا تحبس المستخدمين أبدًا.
ماذا تقدّم
تحليل أرقام النسخ. AppVersion يحلّل صيغًا شبيهة بـ semver (1.2 و5 وv1.2.3 و1.2.3+45 و1.0.0-beta.2+7) ويرتّبها، ومن ذلك أرقام الـ build الرقمية.
كائن للسياسة. UpdatePolicy يحمل أدنى نسخة مطلوبة، وأحدث نسخة، ورابط المتجر، ومدة "ذكّرني لاحقًا"، وعنوانًا ورسالة لكل لغة، وقيمًا خاصة بكل منصة. ويقرأ صيغة JSON بسيطة.
دالة قرار صرفة (pure). UpdateDecision.evaluate تُرجع none أو optional أو forced. البيانات الناقصة، وأرقام النسخ غير المفهومة، وأي خطأ، كلها تعطي none.
مصادر قابلة للاستبدال. UpdatePolicySource واجهة فيها دالة واحدة هي fetch(). وفي الحزمة JsonUrlSource (مبني على package:http، مع client قابل للحقن) وStaticSource.
الـ widget المسمّى UpdateGate.
-
إجباري (forced): صفحة بملء الشاشة لا يستطيع الرجوع إغلاقها (
PopScope). -
اختياري (optional): نافذة حوار قابلة للإغلاق، لا تظهر من جديد إلا بعد مدة التذكير، مع
RemindLaterStoreقابل للاستبدال. - يفتح المتجر عبر callback تكتبه أنت، فلا اعتماد على url_launcher.
- يقرأ النسخة الحالية عبر callback تكتبه أنت، فلا اعتماد على package_info_plus.
النصوص. النصوص الافتراضية بالإنجليزية والفرنسية والعربية، وواجهات RTL تتبع الـ Directionality المحيط. وتستطيع استبدال صفحة التحديث الإجباري ونافذة الحوار بـ builders خاصة بك.
طريقة الاستعمال
أضِفها من GitHub:
dependencies:
update_gate:
git: https://github.com/AbdeldjalilChougui/update_gate
ثم غلِّف صفحتك الرئيسية. package_info_plus وurl_launcher اعتماديات تطبيقك أنت، وليست اعتماديات هذه الحزمة:
import 'package:flutter/material.dart';
import 'package:package_info_plus/package_info_plus.dart';
import 'package:update_gate/update_gate.dart';
import 'package:url_launcher/url_launcher.dart';
MaterialApp(
home: UpdateGate(
source: JsonUrlSource(Uri.parse('https://example.com/app/update.json')),
currentVersion: () async {
final info = await PackageInfo.fromPlatform();
return '${info.version}+${info.buildNumber}';
},
onOpenStore: (decision) async {
final url = decision.storeUrl;
if (url != null) {
await launchUrl(url, mode: LaunchMode.externalApplication);
}
},
child: const HomePage(),
),
);
الـ gate يحتاج Navigator. إذا وضعته في home يجده بنفسه. وإذا وضعته في MaterialApp.builder، أي فوق الـ navigator، مرّر نفس الـ navigatorKey للاثنين.
والـ JSON الذي يُرجعه الـ endpoint يكون هكذا:
{
"min_required_version": "1.2.0",
"latest_version": "1.4.0+52",
"store_url": "https://play.google.com/store/apps/details?id=my.app",
"remind_after_hours": 24,
"title": {"en": "New version", "fr": "Nouvelle version"},
"message": {
"en": "Faster sync and bug fixes.",
"fr": "Synchronisation plus rapide et corrections.",
"ar": "مزامنة أسرع وإصلاحات."
},
"platforms": {
"ios": {
"min_required_version": "1.3.0",
"store_url": "https://apps.apple.com/app/id000000000"
}
}
}
كل الحقول اختيارية. title وmessage يمكن أن يكونا نصًّا عاديًا. مفاتيح اللغة تُطابَق تمامًا أولًا (fr_CA أو fr-CA)، ثم حسب اللغة، ثم default، ثم en. وإن لم يوجد تطابق يُستعمل النص المدمج. ومفاتيح المنصات هي android وios وmacos وwindows وlinux وfuchsia وweb.
القواعد
تستطيع أيضًا اتخاذ القرار دون الـ widget ومنع الدخول بطريقتك:
final decision = UpdateDecision.evaluate(
currentVersion: '1.2.0+12',
policy: const UpdatePolicy(minRequiredVersion: '1.3.0'),
platform: UpdatePlatform.android,
);
if (decision.isForced) {
// Block the app your own way.
}
جدول القرار قصير ويسهل حفظه:
- النسخة الحالية أقل من min: النتيجة
forced. - النسخة الحالية بين min (أو تساويه) وأقل من latest: النتيجة
optional. - النسخة الحالية تساوي latest أو أحدث، أو حُدِّد min فقط والنسخة الحالية تساويه أو أحدث: النتيجة
none. - لا توجد سياسة، أو النسخة الحالية فارغة أو غير مفهومة: النتيجة
none. - قيمة min أو latest مضبوطة لكنها غير مفهومة: النتيجة
noneللقاعدتين معًا. - لا min ولا latest: النتيجة
none.
الأسطر الثلاثة الأخيرة هي معنى "الفشل نحو الفتح". حين لا تستطيع الحزمة التأكد، تترك المستخدم يدخل.
مصادر أخرى وواجهة مخصصة
أي backend يصلح خلف UpdatePolicySource. في الـ README adapters لـ Firebase Remote Config و Supabase، وRemindLaterStore فوق shared_preferences حتى يبقى اختيار "لاحقًا" بعد إعادة التشغيل. والـ README يصف الثلاثة بوضوح بأنها مخططات أولية (sketches) لم تُترجَم (compile) ضمن الحزمة، فاعتبرها نقطة انطلاق واختبرها في تطبيقك.
وفي الواجهة، تستطيع تغيير نص واحد أو استبدال الـ widgets:
UpdateGate(
// ...
strings: UpdateGateStrings.fr.copyWith(later: 'Pas maintenant'),
forcedBuilder: (context, prompt) => MyForcedPage(
title: prompt.title,
message: prompt.message,
onUpdate: prompt.onUpdate,
),
optionalBuilder: (context, prompt) => AlertDialog(
title: Text(prompt.title),
actions: [
TextButton(onPressed: prompt.onLater, child: Text(prompt.strings.later)),
TextButton(onPressed: prompt.onUpdate, child: Text(prompt.strings.update)),
],
),
child: const HomePage(),
);
مسار التحديث الإجباري يُغلَّف بـ PopScope(canPop: false) مهما أرجع الـ builder.
أشياء يجب معرفتها
- الـ gate يتحقق مرة واحدة، عند بنائه أول مرة. لا يعيد التحقق عند عودة التطبيق من الخلفية (resume).
-
صفحة التحديث الإجباري route مدفوع (pushed). الكود الذي يستدعي لاحقًا
Navigator.popمباشرة، وليسmaybePop، يستطيع إزالتها. - مدة تذكير واحدة لكل سياسة. توجد مدة "ذكّرني لاحقًا" واحدة فقط لكل سياسة (24 ساعة افتراضيًا)، ونسخة latest أحدث تعيد ضبطها دائمًا.
- مخزن التذكير الافتراضي ينسى عند إعادة التشغيل. احفظه بأي مخزن key-value إذا أردت أن يدوم اختيار "لاحقًا".
-
الـ build metadata غير الرقمية تُهمل عند المقارنة. شيء مثل
+exp.sha.5114f85يُحتفظ به لكنه لا يدخل في الترتيب. - النصوص الافتراضية العربية والفرنسية مكتوبة يدويًا. يطلب الـ README مراجعتها مع متحدث أصلي حسب جمهورك.
لماذا بنيتها
يذكر الـ README في فقرته الأولى الفكرتين اللتين بُنيت عليهما الحزمة: تعمل مع أي مصدر لقواعد النسخ، وتفشل نحو الفتح.
الأولى تخص الاعتماديات. نافذة التحديث ميزة صغيرة، ولا ينبغي أن تقرر أي backend تستعمل، ولا أن تجرّ إضافة لرقم النسخة وإضافة للروابط إلى كل تطبيق. لذلك المصدر واجهة، والنسخة الحالية ورابط المتجر يمرّان عبر callback-ين. وإذا كانت قواعدك في ملف JSON على خادمك، فهذا يكفي.
والثانية تخص أسوأ الحالات. شاشة التحديث الإجباري هي الشاشة الوحيدة في التطبيق المصمَّمة لإيقاف الناس. أردت أن يكون القرار دالة صرفة لها جدول مكتوب، حيث كل مُدخل مشكوك فيه (لا سياسة، نسخة غير مقروءة، خطأ أثناء الجلب) ينتهي إلى none. نافذة لم تظهر مشكلة صغيرة. أما مستخدمون محبوسون خارج التطبيق فلا.
احصل على الكود
المصدر، وصيغة الـ JSON، ومخططات الـ adapters، والاختبارات، كلها على GitHub: https://github.com/AbdeldjalilChougui/update_gate. الرخصة MIT. الملاحظات (issues) وطلبات الدمج (pull requests) مرحّب بها.
نُشر في الأصل على abdeldjalilchougui.biz.
Top comments (0)