بدء استخدام حزمة تطوير البرامج (SDK) لتطبيق Drive لنظام التشغيل iOS

حزمة Driver SDK هي مكتبة تدمجها في تطبيق برنامج التشغيل. من المهم المسئول عن تحديث Fleet Engine بموقع المركبة وطريقها والمسافة المتبقية والوقت المقدر للوصول. وهي تتكامل أيضًا مع حزمة SDK للتنقل، والتي توفّر إرشادات التنقّل باتّجاهات مفصّلة للسائق.

الحد الأدنى لمتطلبات النظام

المتطلبات الأساسية

يفترض هذا الدليل أن تطبيقك ينفذ حزمة SDK للتنقل وأنّ Fleet Engine إعداد الواجهة الخلفية وإتاحتها. ومع ذلك، يوفر مثال التعليمة البرمجية نموذج لكيفية إعداد حزمة SDK للتنقل.

يجب أيضًا تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS في مشروع Google Cloud والحصول على مفتاح واجهة برمجة تطبيقات.

الحصول على إذن بالوصول

إذا كنت أحد عملاء Google Workspace، يمكنك إنشاء مجموعة Workspace مثل google-maps-platform-sdk-users@workspacedomain.com أثناء عملية الإعداد تزويد Google بالاسم. هذه هي الطريقة الموصى بها. ستتم بعد ذلك إضافة مجموعة Workspace إلى قائمة مسموح بها يمنح إمكانية الوصول إلى مستودعات CocoaPods الصحيحة. تأكد من أن المستخدم يتم تضمين رسائل البريد الإلكتروني وعناوين البريد الإلكتروني لحساب الخدمة التي تحتاج إلى الوصول في هذه القائمة.

إذا لم تتمكّن مؤسستك من إنشاء مجموعات Workspace، يمكنك إرسال قائمة إلى Google. من رسائل البريد الإلكتروني الخاصة بحساب المستخدم والخدمة التي تحتاج إلى الوصول إلى هذه العناصر.

تنمية محلية

بالنسبة للتنمية المحلية، يكفي تسجيل الدخول باستخدام Cloud SDK:

gcloud auth login

يجب أن يكون البريد الإلكتروني المُستخدَم لتسجيل الدخول عضوًا في مجموعة Workspace.

الأتمتة (إنشاء الأنظمة أو الدمج المستمر)

إعداد مضيفي التشغيل الآلي وفقًا لما يلي: أفضل الممارسات:

• في حال إجراء العملية داخل بيئة Google Cloud، استخدِم آلي بيانات الاعتماد.

• بخلاف ذلك، يمكنك تخزين ملف مفتاح حساب الخدمة في موقع آمن على نظام ملفات المضيف وتعيين GOOGLE_APPLICATION_CREDENTIALS متغير البيئة بشكل مناسب.

يجب أن يكون البريد الإلكتروني لحساب الخدمة المرتبط ببيانات الاعتماد عضوًا في مجموعة Workspace.

إعدادات المشروع

يمكنك إعداد حزمة تطوير البرامج (SDK) لبرنامج التشغيل لنظام التشغيل iOS باستخدام Cocoapods أو يدويًا.

فحص ملف بيان الخصوصية في Apple

تشترط Apple تفاصيل خصوصية التطبيقات للتطبيقات المتوفّرة على App Store. يُرجى الانتقال إلى صفحة تفاصيل خصوصية Apple App Store لمعرفة آخر الأخبار ومزيد من المعلومات.

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

تنفيذ التفويض والمصادقة

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

بصفتك مطوّر التطبيق، أنت تختار كيفية إنشاء الرموز المميّزة. عملية التنفيذ القدرة على إجراء ما يلي:

• استرجاع رمز دخول، ربما بتنسيق JSON، من خادم HTTPS.
• تحليل الرمز المميّز وتخزينه مؤقتًا
• أعِد تحميل الرمز المميّز عند انتهاء صلاحيته.

للحصول على تفاصيل الرموز المميّزة التي يتوقعها خادم Fleet Engine، يُرجى الاطّلاع على إنشاء رمز JSON المميّز للويب (JWT) للتفويض:

رقم تعريف مقدّم الخدمة هو نفسه رقم تعريف مشروع Google Cloud. يُرجى الاطّلاع على دليل المستخدم لواجهة برمجة التطبيقات Fleet Engine Deliveries API. لمزيد من المعلومات.

يقدم المثال التالي موفّرًا لرمز الدخول:

#import "SampleAccessTokenProvider.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

// SampleAccessTokenProvider.h
@interface SampleAccessTokenProvider : NSObject<GMTDAuthorization>
@end

static NSString *const PROVIDER_URL = @"INSERT_YOUR_TOKEN_PROVIDER_URL";

// SampleAccessTokenProvider.m
@implementation SampleAccessTokenProvider{
  // The cached vehicle token.
  NSString *_cachedVehicleToken;
  // Keep track of the vehicle ID the cached token is for.
  NSString *_lastKnownVehicleID;
  // Keep track of when tokens expire for caching.
  NSTimeInterval _tokenExpiration;
}

- (void)fetchTokenWithContext:(nullable GMTDAuthorizationContext *)authorizationContext
                   completion:(nonnull GMTDAuthTokenFetchCompletionHandler)completion {
  if (!completion) {
    NSAssert(NO, @"%s encountered an unexpected nil completion.", __PRETTY_FUNCTION__);
    return;
  }

  // Get the vehicle ID from the authorizationContext. This is set by the Driver SDK.
  NSString *vehicleID = authorizationContext.vehicleID;
  if (!vehicleID) {
    NSAssert(NO, @"Vehicle ID is missing from authorizationContext.");
    return;
  }

// Clear cached vehicle token if vehicle ID has changed.
  if (![_lastKnownVehicleID isEqual:vehicleID]) {
    _tokenExpiration = 0.0;
    _cachedVehicleToken = nil;
  }
  _lastKnownVehicleID = vehicleID;

  // Clear cached vehicle token if it has expired.
  if ([[NSDate date] timeIntervalSince1970] > _tokenExpiration) {
    _cachedVehicleToken = nil;
  }

  // If appropriate, use the cached token.
  if (_cachedVehicleToken) {
    completion(_cachedVehicleToken, nil);
    return;
  }
  // Otherwise, try to fetch a new token from your server.
  NSURL *requestURL = [NSURL URLWithString:PROVIDER_URL];
  NSMutableURLRequest *request = 
                          [[NSMutableURLRequest alloc] initWithURL:requestURL];
  request.HTTPMethod = @"GET";
  // Replace the following key values with the appropriate keys based on your
  // server's expected response.
  NSString *vehicleTokenKey = @"VEHICLE_TOKEN_KEY";
  NSString *tokenExpirationKey = @"TOKEN_EXPIRATION";
  __weak typeof(self) weakSelf = self;
  void (^handler)(NSData *_Nullable data, NSURLResponse *_Nullable response,
                  NSError *_Nullable error) =
      ^(NSData *_Nullable data, NSURLResponse *_Nullable response, NSError *_Nullable error) {
        typeof(self) strongSelf = weakSelf;
        if (error) {
          completion(nil, error);
          return;
        }

        NSError *JSONError;
        NSMutableDictionary *JSONResponse =
            [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:&JSONError];

        if (JSONError) {
          completion(nil, JSONError);
          return;
        } else {
          // Sample code only. No validation logic.
          id expirationData = JSONResponse[tokenExpirationKey];
          if ([expirationData isKindOfClass:[NSNumber class]]) {
            NSTimeInterval expirationTime = ((NSNumber *)expirationData).doubleValue;
            strongSelf->_tokenExpiration = [[NSDate date] timeIntervalSince1970] + expirationTime;
          }
          strongSelf->_cachedVehicleToken = JSONResponse[vehicleTokenKey];
          completion(JSONResponse[vehicleTokenKey], nil);
        }
    };
NSURLSessionConfiguration *config = [NSURLSessionConfiguration defaultSessionConfiguration];
NSURLSession *mainQueueURLSession =  
       [NSURLSession  sessionWithConfiguration:config delegate:nil
delegateQueue:[NSOperationQueue mainQueue]];
NSURLSessionDataTask *task = [mainQueueURLSession dataTaskWithRequest:request completionHandler:handler];
[task resume];
}

@end

إنشاء مثيل DeliveryDriverAPI

للحصول على مثيل GMTDDeliveryVehicleReporter، عليك أولاً إنشاء المثيل GMTDDeliveryDriverAPI الذي يستخدم providerID وvehicleID driverContext، وaccessTokenProvider. نطاق providerID هو نفسه معرّف مشروع Google Cloud ويمكنك الوصول إلى GMTDDeliveryVehicleReporter. من واجهة برمجة تطبيقات برنامج التشغيل مباشرةً.

ينشئ المثال التالي مثيل GMTDDeliveryDriverAPI:

#import "SampleViewController.h"
#import "SampleAccessTokenProvider.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

static NSString *const PROVIDER_ID = @"INSERT_YOUR_PROVIDER_ID";

@implementation SampleViewController {
 GMSMapView *_mapView;
}

- (void)viewDidLoad {
  NSString *vehicleID = @"INSERT_CREATED_VEHICLE_ID";
  SampleAccessTokenProvider *accessTokenProvider = 
                                [[SampleAccessTokenProvider alloc] init];
  GMTDDriverContext *driverContext = 
     [[GMTDDriverContext alloc] initWithAccessTokenProvider:accessTokenProvider
                                                 providerID:PROVIDER_ID 
                                              vehicleID:vehicleID 
      navigator:_mapView.navigator];

  GMTDDeliveryDriverAPI *deliveryDriverAPI = [[GMTDDeliveryDriverAPI alloc] initWithDriverContext:driverContext];
}

الاستماع بشكل اختياري إلى أحداث AutomotiveReporter

تُحدِّث "GMTDDeliveryVehicleReporter" المركبة بشكل دوري في حال locationTrackingEnabled هي نعم. للاستجابة لهذه التحديثات الدورية، سيتم يمكن للعنصر الاشتراك في أحداث GMTDDeliveryVehicleReporter من خلال التوافق مع بروتوكول GMTDVehicleReporterListener.

يمكنك التعامل مع الأحداث التالية:

• vehicleReporter:didSucceedVehicleUpdate

  إبلاغ تطبيق Driver بأنّ خدمات الخلفية قد تلقّت بنجاح وتحديث موقع المركبة والحالة.

• vehicleReporter:didFailVehicleUpdate:withError

  تُبلِغ المستمِع بتعذُّر تحديث المركبة. طالما أن الموقع تفعيل التتبُّع، وسيستمر GMTDDeliveryVehicleReporter في إرسال أحدث البيانات في خلفية Fleet Engine.

يتعامل المثال التالي مع هذه الأحداث:

SampleViewController.h
@interface SampleViewController : UIViewController<GMTDVehicleReporterListener>
@end

SampleViewController.m
#import "SampleViewController.h"
#import "SampleAccessTokenProvider.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

static NSString *const PROVIDER_ID = @"INSERT_YOUR_PROVIDER_ID";

@implementation SampleViewController {
 GMSMapView *_mapView;
}

- (void)viewDidLoad {
  // ASSUMES YOU IMPLEMENTED HAVE THE SAMPLE CODE UP TO THIS STEP.
  [ridesharingDriverAPI.vehicleReporter addListener:self];
}

- (void)vehicleReporter:(GMTDDeliveryVehicleReporter *)vehicleReporter didSucceedVehicleUpdate:(GMTDVehicleUpdate *)vehicleUpdate {
  // Handle update succeeded.
}

- (void)vehicleReporter:(GMTDDeliveryVehicleReporter *)vehicleReporter didFailVehicleUpdate:(GMTDVehicleUpdate *)vehicleUpdate withError:(NSError *)error {
  // Handle update failed.
}

@end

تفعيل تتبع الموقع الجغرافي

لتفعيل ميزة تتبُّع الموقع الجغرافي، يمكن لتطبيقك ضبط locationTrackingEnabled على YES. في GMTDDeliveryVehicleReporter. ثم GMTDDeliveryVehicleReporter إرسال تحديثات الموقع تلقائيًا. عندما تكون "GMSNavigator" في وضع التنقّل وضع (عند تحديد وجهة من خلال setDestinations) تم ضبط locationTrackingEnabled على YES، GMTDDeliveryVehicleReporter يرسل تلقائيًا تحديثات المسار والوقت المقدر للوصول أيضًا.

المسار الذي تم ضبطه أثناء هذه التحديثات هو المسار نفسه الذي يسلكه السائق الانتقال إليه أثناء جلسة التنقل. وبالتالي، لكي يعمل تتبع الأسطول بشكل صحيح، يجب أن تتطابق النقطة الوسيطة المحددة من خلال -setDestinations:callback: مع البيانات المحددة في خلفية Fleet Engine.

يوضّح المثال التالي ميزة تتبُّع الموقع الجغرافي:

SampleViewController.m
#import "SampleViewController.h"
#import "SampleAccessTokenProvider.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

static NSString *const PROVIDER_ID = @"INSERT_YOUR_PROVIDER_ID";

@implementation SampleViewController {
 GMSMapView *_mapView; 
}

- (void)viewDidLoad {
  // ASSUMES YOU IMPLEMENTED HAVE THE SAMPLE CODE UP TO THIS STEP.
  deliveryDriverAPI.vehicleReporter.locationTrackingEnabled = YES;
}

@end

بشكل افتراضي، يبلغ الفاصل الزمني لإعداد التقارير 10 ثوانٍ، ولكن يمكن مع locationUpdateInterval. الحدّ الأدنى للفاصل الزمني المتوافق مع التحديثات 5 ثوانٍ. يبلغ الحدّ الأقصى للفاصل الزمني المسموح به للتحديث 60 ثانية. أكثر تكرارًا إلى إبطاء الطلبات والأخطاء.

إيقاف الإشعارات بشأن الموقع الجغرافي وإبقاء المركبة غير متصلة بالإنترنت

يمكن لتطبيقك إيقاف تحديثات الموقع الجغرافي لمركبة. على سبيل المثال، عندما تنتهي وردية عمل السائق، يمكن لتطبيقك ضبط locationTrackingEnabled على NO.

  _vehicleReporter.locationTrackingEnabled = NO