نقل بيانات التطبيق المتوافق مع Android SDK SDK

تتيح لك حزمة SDK المخصصة للمستهلكين لنظام التشغيل Android إنشاء تطبيقات مشاركة الرحلات باستخدام بنية معيارية. يمكنك استخدام أجزاء واجهة برمجة التطبيقات التي تريد استخدامها لتطبيقك بعينه ودمجها مع واجهات برمجة التطبيقات الخاصة بك. يتم تضمين واجهات برمجة التطبيقات لحزمة تطوير البرامج (SDK) للمستهلكين في ما يتعلق بالميزات المختلفة في وحدات منفصلة.

إذا كان تطبيق "مشاركة الرحلة" يستخدم إصدارات سابقة من حزمة تطوير البرامج (SDK) للمستهلك، ستحتاج إلى ترقية تطبيقك لاستخدام هذه البنية النموذجية. يصف دليل نقل البيانات هذا طريقة ترقية تطبيقك.

نظرة عامة

تقدّم البنية النمطية لحزمة تطوير البرامج (SDK) للمستهلك كائن جلسة يحمل حالة واجهة المستخدم. في الإصدارات السابقة من SDK للمستهلكين كان تدفق التطبيقات بين الولايات. باستخدام هذه البنية النمطية، يمكنك إنشاء كائن جلسة ويكون لديك خيار عرض الجلسة على الخريطة. إذا لم يتم عرض أي جلسات، فتكون الخريطة فارغة. لم تعد هناك حالة "فارغة" أو "مهيأة".

يمثل كائن الجلسة مثيلاً واحدًا لاستخدام دورة حياة الوحدة. الجلسات هي نقاط الوصول إلى واجهات برمجة التطبيقات للوحدة. على سبيل المثال، تتبع جلسة "مشاركة الرحلة" رحلة واحدة. وتتفاعل مع كائن الجلسة لمراقبة الرحلة.

يرتبط كائن الجلسة بنوع وحدة. يرتبط سلوك كائن الجلسة بدورة حياة الكائن المستخدَم لتهيئةه.

لنفترض أنّك أنشأت كائن TripModel لتتبّع TRIP_A. إذا حاولت الحصول على كائن TripModel لـ TRIP_A مرة أخرى، ستحصل على كائن TripModel نفسه. لتتبع TRIP_B، احصل على كائن TripModel جديد.

حالات الجلسة

يمكن أن تكون الجلسة واحدة من حالات عديدة:

  • يتم تمثيل الجلسة التي تم إنشاؤها بكائن جلسة. يمكنك إنشاء جلسة عن طريق استدعاء طريقة create. مثال:

    JourneySharingSession sessionA = JourneySharingSession.createInstance(TripModelA)

  • يتم تسجيل جلسة تم بدؤها لتحديثات البيانات وقيم عناصر واجهة المستخدم. يمكنك بدء جلسة من خلال استدعاء طريقة start. مثال:

    sessionA.start()

  • تبدأ الجلسة المعروضة تلقائيًا. إنه يعرض عناصر واجهة المستخدم ويقوم بتحديثها استجابة لتحديثات البيانات. يمكنك عرض جلسة من خلال استدعاء طريقة showSession. مثال:

    ConsumerController.showSession(sessionA)

  • تتوقف الجلسة المتوقفة عن إعادة تحميل بياناتها وتتوقّف عن تعديل عناصر واجهة المستخدم. يمكنك إيقاف جلسة من خلال استدعاء طريقة stop. مثال:

    sessionA.stop()

استخدام مكونات البيانات فقط وواجهة المستخدم

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

استخدام مكونات البيانات فقط

لإنشاء تطبيق مشاركة الرحلات باستخدام مكوّنات توفّر البيانات فقط، يجب اتّباع الخطوات التالية:

  • إعداد كائن ConsumerApi.
  • يمكنك الحصول على الكائن TripModelManager من ConsumerApi.
  • يمكنك بدء تتبُّع رحلة باستخدام ميزة "TripModelManager" لتلقّي عنصر TripModel.
  • تسجيل عمليات معاودة الاتصال في عنصر TripModel

يوضح المثال التالي كيفية استخدام مكونات البيانات فقط:

TripModelManager tripManager = ConsumerApi.getTripModelManager();
TripModel tripA = tripManager.getTripModel("trip_A");
tripA.registerTripCallback(new TripModelCallback() {})

استخدام واجهات برمجة التطبيقات لعنصر واجهة المستخدم

استخدِم الكائن ConsumerController للوصول إلى واجهات برمجة التطبيقات لعناصر واجهة المستخدم لحلول "الرحلات والتسليم" عند الطلب.

لإنشاء تطبيق مشاركة الرحلات باستخدام واجهات برمجة تطبيقات عناصر حلول الرحلات والتسليمات عند الطلب، يُرجى اتّباع الخطوات التالية:

  • يجب إعداد الكائن ConsumerApi.
  • يمكنك الحصول على عنصر TripModelManager من الكائن ConsumerApi.
  • يمكنك الحصول على عنصر "TripModel" من "TripModelManager" الذي يتتبّع رحلة واحدة.
  • أضِف ConsumerMap[View/Fragment] إلى عرض التطبيق.
  • يمكنك الحصول على عنصر ConsumerController من ConsumerMap[View/Fragment].
  • يُرجى تقديم الكائن TripModel إلى وحدة التحكّم للحصول على عنصر JourneySharingSession.
  • استخدِم وحدة التحكّم لعرض JourneySharingSession.

يوضِّح المثال التالي كيفية استخدام واجهات برمجة التطبيقات لواجهة المستخدِم:

TripModelManager tripManager = ConsumerApi.getTripModelManager();
TripModel tripA = TripModelManager.getTripModel("trip_A");

// Session is NOT automatically started when created.
JourneySharingSession jsSessionA = JourneySharingSession.createInstance(tripA);
JourneySharingSession jsSessionB = JourneySharingSession.createInstance(tripB);

// But a session is automatically started when shown.
ConsumerController.showSession(jsSessionA);
ConsumerController.showSession(jsSessionB); // hides trip A; shows trip B.
ConsumerController.hideAllSessions(); // don't show any sessions

// Unregister listeners and delete UI elements of jsSessionA.
consumerController.showSession(jsSessionA);
jsSessionA.stop();
// Recreates and shows UI elements of jsSessionA.
jsSessionA.start();

التغييرات التي طرأت على رمز البنية النمطية

إذا كان تطبيق "مشاركة الرحلة" يستخدم إصدارات سابقة من "حزمة تطوير البرامج (SDK) للمستهلكين"، ستتطلب بنية الوحدات المُحدَّثة بعض التغييرات على الرمز البرمجي. ويوضّح هذا القسم بعض هذه التغييرات.

أذونات تحديد الموقع الجغرافي

لم تعُد أذونات FINE_LOCATION مطلوبة في حزمة تطوير البرامج (SDK) للمستهلك

مراقبة الرحلة

تتطلب البنية النمطية المحدثة تغييرات في التعليمات البرمجية لكل من مستخدمي طبقة البيانات وواجهة المستخدم.

في الإصدارات السابقة، قد يتعامل مستخدم طبقة البيانات مع مراقبة الرحلة باستخدام التعليمة البرمجية التالية:

ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
manager.setActiveTrip("trip_id")
manager.registerActiveTripCallback(new TripModelCallback() {})

باستخدام البنية النمطية، سيستخدم مستخدم طبقة البيانات التعليمة البرمجية التالية:

ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
TripModel tripA = TripModelManager.getTrip("trip_A")
tripA.registerTripCallback(new TripModelCallback() {})

في الإصدارات السابقة، قد يتعامل مستخدم واجهة المستخدم مع مراقبة الرحلة باستخدام التعليمة البرمجية التالية:

ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
manager.setActiveTrip("trip_id")

ConsumerController controller = consumerGoogleMap.getConsumerController();
consumerController.startJourneySharing()

باستخدام البنية النمطية، سيستخدم مستخدم واجهة المستخدم التعليمة البرمجية التالية:

ConsumerApi.initialize()
TripModelManager manager = ConsumerApi.getTripManager()
TripModel tripA = TripModelManager.getTripModel("trip_A");

ConsumerController controller = consumerGoogleMap.getConsumerController();
JourneySharingSession jsSessionA = JourneySharingSession.createInstance(tripA);
controller.showSession(jsSessionA);

إعادة توسيط الخريطة

لم يعد يتم تكبير عرض الخريطة أو الجزء لتحديد موقع المستخدم عند الإعداد عندما لا تكون هناك جلسة نشطة. ستواصل ميزة "التكبير/التصغير التلقائي" تلقائيًا لعرض جلسة "مشاركة الرحلة" النشطة طالما أنّ ميزة Autocam مفعّلة. ويتم تمكين Auto Camera بشكل افتراضي.

في الإصدارات السابقة، كنت تستخدم الرمز التالي لتوسيط الكاميرا للجلسة النشطة الحالية:

consumerController.centerMapForState()

باستخدام البنية النمطية، يمكنك استخدام التعليمة البرمجية التالية:

CameraUpdate cameraUpdate = consumerController.getCameraUpdate()
if (cameraUpdate != null) {
   googleMap.animateCamera(cameraUpdate);
   // OR googleMap.moveCamera(cameraUpdate);
}

لإيقاف ميزة Autocam في الإصدارات السابقة، يمكنك استخدام الرمز التالي:

consumerController.disableAutoCamera(true);

باستخدام البنية النمطية، يمكنك استخدام التعليمة البرمجية التالية:

consumerController.setAutoCameraEnabled(false);

التخصيص

تمت إزالة زر الإجراء الرئيسي (FAB) المخصّص حلول الرحلات والتسليمات عند الطلب من الخريطة.

زر الإجراء الرئيسي المخصّص

تمت أيضًا إزالة الطرق المرتبطة بإجراءات FAB:

ConsumerController.isMyLocationFabEnabled()
ConsumerController.setMyLocationFabEnabled()