بدء استخدام Driver SDK لنظام التشغيل iOS

مدير حِزم Swift

يمكن تثبيت Driver SDK من خلال Swift Package Manager. لإضافة حزمة SDK، تأكَّد من إزالة أي تبعيات حالية لـ Driver SDK.

لإضافة حزمة SDK إلى مشروع جديد أو حالي، يُرجى اتّباع الخطوات التالية:

1. افتح Xcode project أو workspace، ثم انتقِل إلى ملف > إضافة تبعيات الحزمة.
2. أدخِل https://github.com/googlemaps/ios-driver-sdk كعنوان URL، واضغط على Enter لسحب الحزمة، ثم انقر على "Add Package".
3. لتثبيت version محدّد، اضبط الحقل قاعدة التبعية على أحد الخيارات المستندة إلى الإصدار. بالنسبة إلى المشاريع الجديدة، ننصحك بتحديد أحدث إصدار واستخدام الخيار "Exact Version". بعد الانتهاء من التعديل، انقر على "Add Package" (إضافة حزمة).
4. من نافذة اختيار منتجات الحزم، تأكَّد من إضافة GoogleRidesharingDriver إلى هدف main المحدّد. بعد الانتهاء من التعديل، انقر على "Add Package" (إضافة حزمة).
5. للتحقّق من التثبيت، انتقِل إلى جزء General المستهدَف. في إطارات الأطر والمكتبات والمحتوى المضمَّن، من المفترض أن تظهر لك الحِزم المثبَّتة. يمكنك أيضًا عرض القسم "تبعيات الحزمة" في "Project Navigator" للتحقق من الحزمة وإصدارها.

لتعديل package لمشروع حالي، اتّبِع الخطوات التالية:

1. من Xcode، انتقل إلى "ملف > الحزم > التحديث إلى أحدث إصدارات الحزمة".
2. للتحقّق من التثبيت، انتقِل إلى قسم تبعيات الحزمة في Project Navigator للتحقّق من الحزمة وإصدارها.

لإزالة تبعيات Driver SDK الحالية التي تمت إضافتها باستخدام CocoaPods، اتّبِع الخطوات التالية:

1. أغلِق مساحة عمل Xcode. افتح الوحدة الطرفية ونفِّذ الأمر التالي:

   sudo gem install cocoapods-deintegrate cocoapods-clean 
   pod deintegrate 
   pod cache clean --all

2. عليك إزالة Podfile وPodfile.resolved وXcode workspace في حال عدم استخدامها لأي منتج آخر غير CocoaPods.

لإزالة حزمة "SDK لبرنامج التشغيل" الحالية التي تم تثبيتها يدويًا، اتّبِع الخطوات التالية:

1. من إعدادات ضبط مشروع Xcode، ابحث عن Frameworks والمكتبات والمحتوى المضمّن. استخدِم علامة الطرح(-) لإزالة إطار العمل التالي:

   • GoogleRidesharingDriver.xcframework

2. يجب إزالة حزمة GoogleRidesharingDriver من دليل المستوى الأعلى لمشروع Xcode.

CocoaPods

لإعداد "حزمة تطوير البرامج (SDK) للسائق" باستخدام CocoaPods، ستحتاج إلى العناصر التالية:

• أداة CocoaPods: لتثبيت هذه الأداة، افتح المحطة الطرفية وشغِّل الأمر التالي.

   sudo gem install cocoapods

1. أنشئ Podfile لـ Driver SDK واستخدمه لتثبيت واجهة برمجة التطبيقات وتبعياتها: أنشئ ملفًا باسم Podfile في دليل مشروعك. يحدد هذا الملف تبعيات مشروعك. قم بتحرير Podfile وأضف تبعياتك. فيما يلي مثال يتضمن التبعيات:

   source "https://github.com/CocoaPods/Specs.git"
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleRidesharingDriver'
   end
   

   في ما يلي مثال يتضمّن مجموعات الإصدارات الأولية والتجريبية لـ Driver SDK كتبعيات:

   source "https://cpdc-eap.googlesource.com/ridesharing-driver-sdk.git"
   source "https://github.com/CocoaPods/Specs.git"
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleRidesharingDriver'
   end
   

2. احفظ Podfile. افتح الوحدة الطرفية وانتقل إلى الدليل الذي يحتوي على Podfile:

   cd <path-to-project>
   

3. شغِّل أمر pod install. سيؤدي هذا إلى تثبيت واجهات برمجة التطبيقات المحددة في Podfile، بالإضافة إلى أي تبعيات قد تكون لديهم.

   pod install
   

4. أغلق Xcode، ثم افتح (انقر نقرًا مزدوجًا) ملف .xcworkspace الخاص بمشروعك لتشغيل Xcode. من هذا الوقت فصاعدًا، يجب عليك استخدام ملف .xcworkspace لفتح المشروع.

للحصول على مزيد من التفاصيل، يمكنك الرجوع إلى دليل البدء في CocoaPods.

التثبيت اليدوي

XCFramework عبارة عن حزمة ثنائية تستخدمها لتثبيت Driver SDK. يمكنك استخدام هذه الحزمة على منصات متعددة، بما في ذلك الأجهزة التي تستخدم Apple silicon. يوضّح هذا الدليل كيفية إضافة XCFramework الذي يحتوي على حزمة Driver SDK يدويًا إلى مشروعك وضبط إعدادات الإصدار في Xcode.

تنزيل البرنامج الثنائي لحزمة SDK ومواردها:

• GoogleRidesharingDriver.xcframework
• GoogleRidesharingDriver.bundle

1. استخرِج الملفات للوصول إلى XCFramework والموارد.

2. شغِّل Xcode وافتح مشروعًا حاليًا أو أنشئ مشروعًا جديدًا. إذا كنت مستخدِمًا جديدًا لنظام التشغيل iOS، أنشئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.

3. أنشئ مجموعة أطر العمل ضمن مجموعة مشروعك إذا لم تكن موجودة بالفعل.

4. لتثبيت Driver SDK، اسحب ملف GoogleRidesharingDriver.xcframework إلى مشروعك ضمن إطارات الأطر، والمكتبات، والمحتوى المضمَّن. عندما يُطلب منك، حدد نسخ العناصر إذا لزم الأمر.

5. اسحب ملف GoogleRidesharingDriver.bundle الذي تم تنزيله إلى دليل المستوى الأعلى في مشروع Xcode. اختَر "Copy items if needed" عندما يُطلب منك ذلك.

6. حدد مشروعك من Project Navigator واختر هدف تطبيقك.

7. افتح علامة التبويب "مراحل الإنشاء"، وفي "ربط النظام الثنائي مع المكتبات"، أضف أطر العمل والمكتبات التالية إذا لم تكن موجودة بالفعل:

   • Accelerate.framework
   • AudioToolbox.framework
   • AVFoundation.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libxml2.tbd
   • libz.tbd
   • LocalAuthentication.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework
   • WebKit.framework

8. اختَر مشروعك بدلاً من هدف محدّد، وافتح علامة التبويب إعدادات الإنشاء. في القسم علامات رابط أخرى، أضِف -ObjC لكل من تصحيح الأخطاء والإصدار. إذا لم تظهر هذه الإعدادات، عليك تغيير الفلتر في شريط "إعدادات الإصدار" من أساسي إلى الكل.

Swift

import GoogleRidesharingDriver

private let providerURL = "INSERT_YOUR_TOKEN_PROVIDER_URL"

class SampleAccessTokenProvider: NSObject, GMTDAuthorization {
  private struct AuthToken {
    // The cached vehicle token.
    let token: String
    // Keep track of when the token expires for caching.
    let expiration: TimeInterval
    // Keep track of the vehicle ID the cached token is for.
    let vehicleID: String
  }

  enum AccessTokenError: Error {
    case missingAuthorizationContext
    case missingData
  }

  private var authToken: AuthToken?

  func fetchToken(
    with authorizationContext: GMTDAuthorizationContext?,
    completion: @escaping GMTDAuthTokenFetchCompletionHandler
  ) {
    // Get the vehicle ID from the authorizationContext. This is set by the Driver SDK.
    guard let authorizationContext = authorizationContext else {
      completion(nil, AccessTokenError.missingAuthorizationContext)
      return
    }
    let vehicleID = authorizationContext.vehicleID

    // If appropriate, use the cached token.
    if let authToken = authToken,
      authToken.expiration > Date.now.timeIntervalSince1970 && authToken.vehicleID == vehicleID
    {
      completion(authToken.token, nil)
      return
    }

    // Otherwise, try to fetch a new token from your server.
    let request = URLRequest(url: URL(string: providerURL))
    let task = URLSession.shared.dataTask(with: request) { [weak self] data, _, error in
      guard let strongSelf = self else { return }
      guard error == nil else {
        completion(nil, error)
        return
      }

      // Replace the following key values with the appropriate keys based on your
      // server's expected response.
      let vehicleTokenKey = "VEHICLE_TOKEN_KEY"
      let tokenExpirationKey = "TOKEN_EXPIRATION"
      guard let data = data,
        let fetchData = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
        let token = fetchData[vehicleTokenKey] as? String,
        let expiration = fetchData[tokenExpirationKey] as? Double
      else {
        completion(nil, AccessTokenError.missingData)
        return
      }

      strongSelf.authToken = AuthToken(
        token: token, expiration: expiration, vehicleID: vehicleID)
      completion(token, nil)
    }
    task.resume()
  }
}

Objective-C

#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 {
  // 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 vehicletoken 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

Swift

import GoogleRidesharingDriver

private let providerID = "INSERT_YOUR_PROVIDER_ID"

class SampleViewController: UIViewController {
  private let mapView: GMSMapView

  override func viewDidLoad() {
    super.viewDidLoad()

    let vehicleID = "INSERT_CREATED_VEHICLE_ID"
    let accessTokenProvider = SampleAccessTokenProvider()
    let driverContext = GMTDDriverContext(
      accessTokenProvider: accessTokenProvider,
      providerID: providerID,
      vehicleID: vehicleID,
      navigator: mapView.navigator)
    let ridesharingDriverAPI = GMTDRidesharingDriverAPI(driverContext: driverContext)
  }
}

Objective-C

#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];

  GMTDRidesharingDriverAPI *ridesharingDriverAPI = [[GMTDRidesharingDriverAPI alloc] initWithDriverContext:driverContext];
}

Swift

import GoogleRidesharingDriver

private let providerID = "INSERT_YOUR_PROVIDER_ID"

class SampleViewController: UIViewController, GMTDVehicleReporterListener {
  private let mapView: GMSMapView

  override func viewDidLoad() {
    // Assumes you have implemented the sample code up to this step.
    ridesharingDriverAPI.vehicleReporter.add(self)
  }

  func vehicleReporter(_ vehicleReporter: GMTDVehicleReporter, didSucceed vehicleUpdate: GMTDVehicleUpdate) {
    // Handle update succeeded.
  }

  func vehicleReporter(_ vehicleReporter: GMTDVehicleReporter, didFail vehicleUpdate: GMTDVehicleUpdate, withError error: Error) {
    // Handle update failed.
  }
}

Objective-C

/*

    *   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 have implemented the sample code up to this step.
  [ridesharingDriverAPI.vehicleReporter addListener:self];
}

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

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

@end

Swift

import GoogleRidesharingDriver

private let providerID = "INSERT_YOUR_PROVIDER_ID"

class SampleViewController: UIViewController, GMTDVehicleReporterListener {
  private let mapView: GMSMapView

  override func viewDidLoad() {
    // Assumes you have implemented the sample code up to this step.
    if let roadSnappedLocationProvider = mapView.roadSnappedLocationProvider {
      roadSnappedLocationProvider.add(ridesharingDriverAPI.vehicleReporter)
      roadSnappedLocationProvider.startUpdatingLocation()
    }
  }
}

Objective-C

/*

    *   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 have implemented the sample code up to this step.
  [_mapView.roadSnappedLocationProvider addListener:ridesharingDriverAPI.vehicleReporter];
  [_mapView.roadSnappedLocationProvider startUpdatingLocation];
}

@end

Swift

import GoogleRidesharingDriver

private let providerID = "INSERT_YOUR_PROVIDER_ID"

class SampleViewController: UIViewController, GMTDVehicleReporterListener {
  private let mapView: GMSMapView

  override func viewDidLoad() {
    // Assumes you have implemented the sample code up to this step.
    ridesharingDriverAPI.vehicleReporter.locationTrackingEnabled = true
  }
}

Objective-C

/*
    *   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 have implemented the sample code up to this step.
  ridesharingDriverAPI.vehicleReporter.locationTrackingEnabled = YES;
}

@end

Swift

import GoogleRidesharingDriver

private let providerID = "INSERT_YOUR_PROVIDER_ID"

class SampleViewController: UIViewController, GMTDVehicleReporterListener {
  private let mapView: GMSMapView

  override func viewDidLoad() {
    // Assumes you have implemented the sample code up to this step.
    ridesharingDriverAPI.vehicleReporter.update(.online)
  }
}

Objective-C

#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 have implemented the sample code up to this step.
  [ridesharingDriverAPI.vehicleReporter
                                   updateVehicleState:GMTDVehicleStateOnline];
}

@end

Swift

import GoogleRidesharingDriver

class VehicleReporterListener: NSObject, GMTDVehicleReporterListener {
  func vehicleReporter(
    _ vehicleReporter: GMTDVehicleReporter,
    didFail vehicleUpdate: GMTDVehicleUpdate,
    withError error: Error
  ) {
    let fullError = error as NSError
    if let innerError = fullError.userInfo[NSUnderlyingErrorKey] as? NSError {
      let innerFullError = innerError as NSError
      if innerFullError.localizedDescription.contains("update_mask cannot be empty") {
        emptyMaskUpdates += 1
        return
      }
    }
    failedUpdates += 1
  }

  override init() {
    emptyMaskUpdates = 0
    failedUpdates = 0
  }
}

Objective-C

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

@implementation VehicleReporterListener {
  NSInteger emptyMaskUpdates = 0;
  NSInteger failedUpdates = 0;
}

-   (void)vehicleReporter:(GMTDVehicleReporter *)vehicleReporter
   didFailVehicleUpdate:(GMTDVehicleUpdate *)vehicleUpdate
              withError:(NSError *)error {
  for (NSError *underlyingError in error.underlyingErrors) {
    if ([underlyingError.localizedDescription containsString:@"update_mask cannot be empty"]) {
      emptyMaskUpdates += 1;
      return;
    }
  }
  failedUpdates += 1
}

@end

Swift

vehicleReporter.locationTrackingEnabled = false

Objective-C

_vehicleReporter.locationTrackingEnabled = NO;