DEV Community

Cover image for throttled_location: أرسل نقاط GPS أقل دون أن تفقد مسار عامل التوصيل
Abdeldjalil Chougui
Abdeldjalil Chougui

Posted on Originally published at abdeldjalilchougui.biz

throttled_location: أرسل نقاط GPS أقل دون أن تفقد مسار عامل التوصيل

الهاتف يستطيع إنتاج موقع GPS (fix) كل ثانية. وفي تطبيق توصيل أو طلب سيارات، أول ما يخطر على البال هو إرسال كل موقع إلى الخادم. يشرح README هذه الحزمة لماذا هذه صفقة خاسرة: إرسال كل موقع يستهلك البطارية وبيانات الهاتف وعمليات الكتابة في الخادم، ومع ذلك يترك فراغًا على الخريطة بمجرد دخول عامل التوصيل نفقًا.

ما تحتاجه الخريطة يختلف عما ينتجه الـ GPS. على الطريق السريع، نقطة كل بضع ثوانٍ ترسم المسار جيدًا. وعامل التوصيل متوقف، نقطة كل بضع دقائق تكفي لتقول "ما زال هنا". وعند المنعطف، يجب أن تخرج النقطة مبكرًا حتى لا يقطع الخط الزاوية. وعند انقطاع الشبكة، يجب أن تنتظر النقاط ثم تُعاد بالترتيب.

throttled_location تضع هذه السياسة بين الـ GPS والـ API الخاص بك. تقرّر متى يُرسل الموقع، وماذا يُرسل، وماذا تفعل دون اتصال. وتعمل مع أي إضافة لتحديد الموقع، لأنها لا تقرأ الـ GPS بنفسها أبدًا.

ماذا تقدّم

المكوّنات. LocationFix يحمل lat و lon و accuracy و speed و heading و altitude و timestamp و isMocked، مع التحويل إلى JSON ومنه. وThrottledLocationReporter يأخذ المواقع من LocationSource ويرسلها دفعات عبر LocationSink.

سياسة إرسال. كل قاعدة في ReportingPolicy قابلة للضبط، والقواعد تعمل معًا:

  • حد أدنى للمدة بين إرسالين، لا يُتجاوز أبدًا؛
  • مدة تتكيف مع السرعة (SpeedBand): افتراضيًا 30 ثانية عند المشي أو التوقف، 15 ثانية على دراجة، 10 ثوانٍ في زحام المدينة، و5 ثوانٍ على الطريق السريع؛
  • حد أدنى للمسافة المقطوعة، محسوبة بصيغة Haversine، قبل الإرسال الدوري؛
  • عتبة لتغيّر الاتجاه (heading)، حتى تُرسل المنعطفات مبكرًا؛
  • فلتر للدقة يحذف المواقع التي نصف قطر دقتها أسوأ من عدد محدد من الأمتار؛
  • فلتر اختياري للمواقع المزيّفة (mocked)؛
  • كاشف للتوقف، يوقف الإرسال ويرسل نبضة (heartbeat) كل N دقيقة، أما الخروج من دائرة التوقف فيُرسل فورًا؛
  • قيمة من الخادم تغيّر المدة (مثل next_update_seconds)، محصورة بين [minInterval, maxInterval].

فلتر القفزات (jitter). يرفض القفزات المستحيلة بالتحقق من أن السرعة بين موقعين معقولة، بعد طرح نصفي قطر الدقة. ويعيد المزامنة بعد N مواقع متسقة إذا كان الجهاز قد تحرك فعلًا.

مخزون دون اتصال (backlog). محدود بالعدد وبالعمر. عند الامتلاء، إما يحذف أقدم النقاط أو يخفّف العينة فيُبقي كل نقطة رقم k. وعندما يخبر الـ Stream<bool> الخاص بك أن الاتصال عاد، تُعاد النقاط من الأقدم إلى الأحدث، في دفعات حجمها قابل للضبط.

تخزين قابل للاستبدال. InMemoryBacklogStore هو الافتراضي، وJsonFileBacklogStore (من io.dart) يكتب الملف بطريقة ذرّية (atomic). وتستطيع تنفيذ BacklogStore فوق أي شيء آخر.

حماية أثناء الإرسال. عمليات الإرسال لا تتداخل أبدًا. الإرسال الفاشل يُعاد مع exponential backoff (RetryBackoff)، وعودة الاتصال تعيد المحاولة فورًا.

دورة الحياة والإحصاءات. start وpause وresume وstop، مع statsStream فيه أعداد المُرسَل والمنتظِر والمتجاوَز والمحذوف حسب السبب.

قابلة للاختبار. الساعة قابلة للحقن وكل المؤقتات تستعمل dart:async، فكل المسار نتيجته ثابتة تحت fake_async. الحزمة Dart فقط وبلا اعتماديات، والمكتبة الأساسية تعمل على كل المنصات ومنها الويب.

طريقة الاستعمال

أضِفها من GitHub:

dependencies:
  throttled_location:
    git: https://github.com/AbdeldjalilChougui/throttled_location
Enter fullscreen mode Exit fullscreen mode

ثم ابنِ reporter من مصدر و sink وسياستين:

import 'package:throttled_location/io.dart';
import 'package:throttled_location/throttled_location.dart';

Future<ThrottledLocationReporter> startTracking({
  required LocationSource source, // see the adapter below
  required Stream<bool> online, // e.g. from connectivity_plus
  required String backlogPath, // e.g. from path_provider
  required Future<Map<String, Object?>> Function(List<Map<String, Object?>>)
      postPoints, // your HTTP call
}) async {
  final reporter = ThrottledLocationReporter(
    source: source,
    sink: LocationSink.fromFunction((batch) async {
      // Throwing (offline, timeout, 5xx) keeps the batch and retries.
      final body = await postPoints([for (final f in batch) f.toJson()]);
      final next = body['next_update_seconds'];
      return SinkResult.accepted(
        nextInterval: next is int ? Duration(seconds: next) : null,
      );
    }),
    policy: const ReportingPolicy(
      minInterval: Duration(seconds: 5),
      maxInterval: Duration(minutes: 2),
      maxAccuracyMeters: 50,
      heartbeatInterval: Duration(minutes: 5),
    ),
    backlog: BacklogPolicy(
      maxCount: 500,
      maxAge: const Duration(hours: 1),
      overflow: BacklogOverflow.downsample(keepEvery: 2),
    ),
    store: JsonFileBacklogStore(backlogPath),
    connectivity: online,
    batchSize: 50,
  );
  reporter.statsStream.listen((s) => print(s));
  await reporter.start();
  return reporter;
}
Enter fullscreen mode Exit fullscreen mode

استدعِ pause() عندما ينهي عامل التوصيل دوامه، وresume() عندما يعود، وstop() عندما تنتهي المهمة. stop() تقوم بمحاولة إرسال أخيرة ثم تحفظ ما بقي في الانتظار.

المصدر عبارة عن adapter حول إضافة الموقع التي تستعملها. مع geolocator يكون هكذا:

final geolocatorSource = LocationSource.fromStream(
  () => Geolocator.getPositionStream(
    locationSettings: const LocationSettings(
      accuracy: LocationAccuracy.high,
      distanceFilter: 0, // the policy does the throttling
    ),
  ).map(
    (p) => LocationFix(
      lat: p.latitude,
      lon: p.longitude,
      accuracy: p.accuracy,
      // Platforms report -1 (or 0 on some devices) when unknown.
      speed: p.speed >= 0 ? p.speed : null,
      heading: p.heading >= 0 ? p.heading : null,
      altitude: p.altitude,
      timestamp: p.timestamp,
      isMocked: p.isMocked,
    ),
  ),
);
Enter fullscreen mode Exit fullscreen mode

اطلب إذن الموقع قبل استدعاء start(). الحزمة لا تطلب أي إذن أبدًا. وللإضافات التي توفّر فقط استدعاء واحدًا للموقع الحالي، غلِّف الاستدعاء بـ PollingLocationSource(read, period: ...)، والقراءات لا تتداخل. وفي الـ README أيضًا adapter لـ background_location_free، وهي حزمة شقيقة توفّر stream للموقع عبر foreground service في Android. وهذه الحزمة لا تعتمد عليها.

كيف يُحكم على كل موقع

القواعد تعمل بترتيب ثابت:

  1. فلتر المواقع المزيّفة، وفلتر الدقة، وفلتر الترتيب الزمني، وفلتر القفزات. الموقع الذي يفشل في أي منها يُحذف.
  2. أول موقع بعد start أو resume يُرسل.
  3. الموقع الذي يأتي قبل مرور minInterval على آخر إرسال يُتجاوز.
  4. الموقع الذي يخرج من دائرة التوقف يُرسل.
  5. أثناء التوقف، يُتجاوز الموقع إلا إذا حان موعد نبضة.
  6. إذا مرّت المدة (قيمة الخادم، وإلا نطاق السرعة) وتحرك الجهاز مسافة minDistanceMeters على الأقل، يُرسل الموقع.
  7. تغيّر في الاتجاه بمقدار turnDegrees على الأقل، عند سرعة turnMinSpeedMps على الأقل، يُرسل.
  8. إذا حان موعد نبضة يُرسل الموقع. وإلا يُتجاوز.

وهناك مؤقت للنبضات يعيد إرسال آخر موقع صالح عندما يسكت الـ GPS.

ReportingPolicyEngine هو النواة المتزامنة (synchronous) وراء هذه القواعد. لا يقوم بأي I/O ولا يشغّل مؤقتات، فتستطيع استعماله وحده، مثلًا لتخفيف مسار مسجَّل: engine.evaluate(fix, now) تُرجع SendDecision أو SkipDecision أو DropDecision.

أشياء يجب معرفتها

  • لا تقرأ الـ GPS ولا تطلب الأذونات. أنت من يوفّر الـ LocationSource.
  • المسافات تفترض أرضًا كروية: صيغة Haversine مع نصف القطر المتوسط حسب IUGG، أي 6 371 008.8 متر. الفرق عن الشكل الإهليلجي WGS-84 يصل إلى نحو 0.5%، وهو أقل بكثير من ضجيج الـ GPS في المسافات المعنية.
  • الـ timestamps مهمة. حدود العمر ومؤقت التوقف تقارن timestamp الخاص بالموقع مع الساعة المحقونة. الجهاز الذي ساعته خاطئة كثيرًا قد تنتهي صلاحية نقاطه مبكرًا أو متأخرًا.
  • القيم الافتراضية اجتهاد هندسي. نطاقات السرعة، ودائرة التوقف 30 مترًا، وحد القفزة 70 م/ث، ضُبطت على مسارات اصطناعية. ليست قيمًا من دراسة. اضبطها حسب أسطولك.
  • JsonFileBacklogStore يعيد كتابة الملف كله عند كل تغيير. هذا مناسب لبضعة آلاف نقطة. لأكثر من ذلك، نفّذ BacklogStore فوق قاعدة بيانات. ويحتاج dart:io، فهو غير متاح على الويب.
  • stop() نهائية. أنشئ reporter جديدًا للتتبع من جديد.

لماذا بنيتها

المشكلة التي يصفها الـ README هي عدم تطابق: الـ GPS يعطي موقعًا كل ثانية، ولا البطارية ولا باقة البيانات ولا الخادم يريد طلبًا كل ثانية. المؤقت الثابت هو الاختصار المعتاد، وهو خاطئ في الاتجاهين. يرسل أكثر من اللازم وعامل التوصيل متوقف، وأقل من اللازم في المنعطف. ولا يفعل شيئًا في حالة النفق.

أردت أن يكون القرار في مكان واحد، على شكل قواعد تُقرأ وتُختبر: قائمة مرتبة تقول لماذا أُرسل كل موقع أو تُجووز أو حُذف. وأردته مفصولًا عن إضافة الـ GPS وعن عميل HTTP، حتى تعمل نفس السياسة مهما كان ما يستعمله التطبيق للحصول على المواقع أو لإرسالها، وحتى يعمل كل شيء تحت fake_async دون جهاز.

احصل على الكود

المصدر، والـ adapters، والاختبارات، كلها على GitHub: https://github.com/AbdeldjalilChougui/throttled_location. الرخصة MIT. الملاحظات (issues) وطلبات الدمج (pull requests) مرحّب بها.


نُشر في الأصل على abdeldjalilchougui.biz.

Top comments (0)