نقل بيانات حزمة تطوير البرامج (SDK) للمستهلكين لنظام التشغيل iOS

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

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

نظرة عامة

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

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

كائن "TripModel"

في الإصدارات السابقة من "حزمة تطوير البرامج (SDK) للمستهلكين"، يتيح لك مثيل TripService مراقبة رحلة مباشرة واحدة فقط في كل مرة. باستخدام كائن TripModel، يمكنك مراقبة عدة رحلات مباشرة في مثيل TripService واحد. يمكن إنشاء مثيل لـ TripModel من TripService، ويكون كل مثيل من TripModel مرتبطًا برحلة معيّنة.

يتم تعديل الأحداث من خلال استدعاءات TripModel إذا كان المشترك المسجَّل في الرحلة عند إجراء التعديل.

ويمكن أيضًا استخدام الكائن TripModel لإنشاء مثيل للكائن JourneySharingSession.

MapViewSession ولاية

يمكن إضافة مثيل MapViewSession في mapView واحد فقط في كل مرّة، ويمكن أن يكون في إحدى الحالتين التاليتين:

  • تشير حالة GMTCMapViewSessionStateInactive إلى أنّه لم تتم إضافة MapViewSession بعد إلى أي mapView، أو أنّه تمت إزالته من mapView. عند إزالة مثيل MapViewSession من mapView، يتم استدعاء الطريقة didRemoveFromMapView.

    يؤدي طلب الإجراء hideMapViewSession أو hideAllMapViewSessions إلى إزالة mapViewSession من mapView:

    [_mapView hideMapViewSession:mapViewSessionA];

    أو

    [_mapView hideAllMapViewSessions];

  • تشير الحالة GMTCMapViewSessionStateActive إلى أنّ عنصر MapViewSession هذا قد تمت إضافته إلى mapView. عند إضافة مثيل من MapViewSession إلى mapView، يتم استدعاء الطريقة didAddToMapView. يؤدي طلب طريقة showMapViewSession إلى إضافة mapViewSession إلى هدف mapView المستهدف:

    [_mapView showMapViewSession:mapViewSessionA];

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

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

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

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

  1. يمكنك إعداد عنصر GMTCServices من خلال تحديد رقم تعريف موفّر الخدمة وموفِّر رمز الدخول.
  2. يمكنك الحصول على السمة tripService من المثيل المشترك لكائن GMTCServices.
  3. إنشاء مثيل لكائن GMTCTripModel أو استرداده لرحلة محدّدة باستخدام طريقة tripModelForTripName في الكائن tripService
  4. عليك تسجيل عمليات معاودة الاتصال لمثيل "GMTCTripModel" لبدء تتبُّع الرحلة.

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

[GMTCServices setAccessTokenProvider:[[AccessTokenProvider alloc] init]
                          providerID:yourProviderID];
GMTCTripService *tripService = [GMTCServices sharedServices].tripService;

// Create a tripModel instance for listening to updates to the trip specified by this trip name.
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];

// Register for the trip update events.
[tripModel registerSubscriber:self];

// To stop listening for the trip update.
[tripModel unregisterSubscriber:self];

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

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

  1. يمكنك إعداد عنصر GMTCServices من خلال تحديد رقم تعريف موفّر الخدمة وموفِّر رمز الدخول.
  2. عليك إعداد كائن GMTCMapView لعرض الخريطة الأساسية.
  3. يمكنك الحصول على السمة tripService من المثيل المشترك لكائن GMTCServices.
  4. إنشاء مثيل لكائن GMTCTripModel أو استرداده لرحلة محدّدة باستخدام طريقة tripModelForTripName في الكائن tripService
  5. إنشاء كائن GMTCJourneySharingSession باستخدام المثيل GMTCTripModel
  6. يمكنك عرض عنصر "GMTCJourneySharingSession" على mapView.
  7. عليك تسجيل عمليات معاودة الاتصال لمثيل "GMTCTripModel" لبدء تتبُّع الرحلة.

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

[GMTCServices setAccessTokenProvider:[[AccessTokenProvider alloc] init]
                          providerID:yourProviderID];
GMTCTripService *tripService = [GMTCServices sharedServices].tripService;

// Create a tripModel instance for listening to updates to the trip specified by this trip name.
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];
GMTCJourneySharingSession *journeySharingSession =
  [[GMTCJourneySharingSession alloc] initWithTripModel:tripModel];

// Add the journeySharingSession instance on the mapView for UI updating.
[self.mapView showMapViewSession:journeySharingSession];

// Register for the trip update events.
[tripModel registerSubscriber:self];

// To remove the JourneySharingSession from the mapView:
[self.mapView hideMapViewSession:journeySharingSession];

// To stop listening for the trip update.
[tripModel unregisterSubscriber:self];

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

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

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

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

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

GRCTripRequest *tripRequest =
    [[GRCTripRequest alloc] initWithRequestHeader:[GRSRequestHeader defaultHeader]
                                         tripName:tripName
                          autoRefreshTimeInterval:1];
GRCTripService *tripService = [GRCServices sharedServices].tripService;
[tripService registerServiceSubscriber:self];
[tripService setActiveTripWithRequest:tripRequest];

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

GMTCTripService *tripService = [GMTCServices sharedServices].tripService;
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];
tripModel.options.autoRefreshTimeInterval = 1;
[tripModel registerSubscriber:self];

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

// Show the Journey Sharing user interface.
[self.mapView startTripMonitoring];

// Hide the Journey Sharing user interface.
[self.mapView resetCustomerState];

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

// Show the Journey Sharing user interface.
GMTCJourneySharingSession *journeySharingSession =
  [[GMTCJourneySharingSession alloc] initWithTripModel:tripModel];
[self.mapView showMapViewSession:journeySharingSession];

// Hide the Journey Sharing user interface.
[self.mapView hideMapViewSession:journeySharingSession];