Bắt đầu với SDK trình điều khiển dành cho iOS

SDK trình điều khiển là một thư viện mà bạn tích hợp vào ứng dụng trình điều khiển. Đó là chịu trách nhiệm cập nhật cho Fleet Engine bằng thông tin vị trí, tuyến đường của người lái, quãng đường còn lại và giờ đến dự kiến. Google Play cũng tích hợp với SDK điều hướng, cung cấp các hướng dẫn điều hướng từng chặng cho người lái xe.

Yêu cầu tối thiểu về hệ thống

  • Thiết bị di động phải chạy iOS 14 trở lên.
  • Mã Xcode phiên bản 15 trở lên.
  • Điều kiện tiên quyết

    Hướng dẫn này giả định rằng ứng dụng của bạn đã triển khai SDK điều hướngFleet Engine phần phụ trợ đã được thiết lập và có sẵn. Tuy nhiên, mã ví dụ này cung cấp ví dụ về cách thiết lập SDK điều hướng.

    Bạn cũng phải bật SDK Maps dành cho iOS trong dự án của bạn trên Google Cloud và Nhận khoá API.

    Nhận quyền khiếu nại

    Nếu bạn là khách hàng Google Workspace, hãy tạo một Nhóm không gian làm việc như google-maps-platform-sdk-users@workspacedomain.com trong quá trình giới thiệu và cung cấp tên cho Google. Đây là phương pháp đề xuất. Sau đó, nhóm Workspace của bạn sẽ được thêm vào danh sách cho phép cấp quyền truy cập vào đúng kho lưu trữ CocoaPods. Xác nhận rằng người dùng các email và email tài khoản dịch vụ cần có quyền truy cập đều có trong danh sách này.

    Nếu tổ chức của bạn không thể tạo nhóm trên Workspace, hãy gửi một danh sách cho Google của người dùng và email tài khoản dịch vụ cần quyền truy cập vào các cấu phần phần mềm này.

    Phát triển cục bộ

    Để phát triển cục bộ, bạn chỉ cần đăng nhập bằng Cloud SDK.

    gcloud

    gcloud auth login
    

    Email dùng để đăng nhập phải là thành viên của Nhóm Workspace.

    Tự động hoá (hệ thống xây dựng hoặc tích hợp liên tục)

    Thiết lập máy chủ tự động theo các phương pháp hay nhất:

    • Nếu quy trình của bạn chạy trong môi trường Google Cloud, hãy dùng tự động phát hiện thông tin xác thực.

    • Nếu không, hãy lưu trữ tệp khoá tài khoản dịch vụ ở một vị trí an toàn trên hệ thống tệp của máy chủ lưu trữ và đặt giá trị GOOGLE_APPLICATION_CREDENTIALS biến môi trường một cách thích hợp.

    Email tài khoản dịch vụ được liên kết với thông tin xác thực phải là thành viên của Workspace Goup.

    Cấu hình dự án

    Bạn có thể định cấu hình SDK trình điều khiển bằng CocoaPods.

    Sử dụng CocoaPods

    Để định cấu hình SDK trình điều khiển bằng CocoaPods, bạn cần có các mục sau:

    1. Tạo một Podfile cho SDK trình điều khiển và dùng tệp này để cài đặt API và các phần phụ thuộc của API: Tạo một tệp có tên Podfile trong dự án của bạn thư mục. Tệp này xác định các phần phụ thuộc của dự án. Chỉnh sửa Podfile và thêm các phần phụ thuộc. Dưới đây là một ví dụ bao gồm phần phụ thuộc:

      source "https://github.com/CocoaPods/Specs.git"
      
      target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
        pod 'GoogleRidesharingDriver'
      end
      
    2. Lưu Podfile. Mở cửa sổ dòng lệnh và chuyển đến thư mục chứa Tệp nhóm:

      cd <path-to-project>
      
    3. Chạy lệnh cài đặt nhóm. Thao tác này sẽ cài đặt các API được chỉ định trong Podfile, cùng với mọi phần phụ thuộc có thể có.

      pod install
      
    4. Đóng Xcode rồi mở (nhấp đúp) tệp .xcworkspace của dự án để khởi chạy Xcode. Kể từ thời điểm này trở đi, bạn phải sử dụng tệp .xcworkspace để mở dự án.

    Phiên bản SDK alpha/beta

    Để định cấu hình phiên bản Alpha hoặc Beta của SDK trình điều khiển dành cho iOS, bạn cần các mục sau:

    • Công cụ CocoaPods: Để cài đặt công cụ này, hãy mở Terminal và chạy sau đây.

      sudo gem install cocoapods
      

      Tham khảo Hướng dẫn bắt đầu sử dụng CocoaPods để biết thêm chi tiết.

    • Tài khoản phát triển của bạn trong danh sách truy cập của Google. Kho lưu trữ nhóm của phiên bản Alpha và Beta của SDK đó không phải là nguồn công khai. Người nhận truy cập vào các phiên bản đó, hãy liên hệ với Kỹ sư hỗ trợ khách hàng của Google. Kỹ sư này thêm tài khoản phát triển của bạn vào danh sách truy cập, sau đó đặt cookie cho xác thực.

    Sau khi dự án của bạn có trong danh sách truy cập, bạn có thể truy cập vào nhóm.

    1. Tạo một Podfile cho SDK trình điều khiển dành cho iOS và sử dụng tệp này để cài đặt API và các phần phụ thuộc của API: Tạo một tệp có tên Podfile trong dự án của bạn thư mục. Tệp này xác định các phần phụ thuộc của dự án. Chỉnh sửa Podfile và thêm các phần phụ thuộc. Dưới đây là một ví dụ bao gồm phần phụ thuộc:

      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. Lưu Podfile. Mở cửa sổ dòng lệnh và chuyển đến thư mục chứa Tệp nhóm:

      cd <path-to-project>
      
    3. Chạy lệnh cài đặt nhóm. Thao tác này sẽ cài đặt các API được chỉ định trong Podfile, cùng với mọi phần phụ thuộc có thể có.

      pod install
      
    4. Đóng Xcode rồi mở (nhấp đúp) tệp .xcworkspace của dự án để khởi chạy Xcode. Kể từ thời điểm này trở đi, bạn phải sử dụng tệp .xcworkspace để mở dự án.

    Cài đặt XCFramework

    XCFramework là một gói nhị phân mà bạn dùng để cài đặt SDK Trình điều khiển. Bạn có thể dùng gói này trên nhiều nền tảng, bao gồm cả các máy sử dụng chipset M1. Hướng dẫn này cho bạn biết cách thêm thủ công XCFramework chứa SDK trình điều khiển vào dự án và định cấu hình chế độ cài đặt bản dựng trong Xcode.

    Tải tệp nhị phân và tài nguyên SDK xuống:

    1. Giải nén các tệp nén để truy cập vào XCFramework và tài nguyên.

    2. Khởi động Xcode rồi mở một dự án hiện có hoặc tạo một dự án mới. Nếu bạn mới sử dụng iOS, hãy tạo dự án mới và chọn mẫu Ứng dụng iOS.

    3. Tạo một nhóm Khung trong nhóm dự án của bạn nếu chưa có nhóm Khung đó.

    4. Kéo tệp gRPCCertificates.bundle đã tải xuống vào thư mục cấp cao nhất của dự án Xcode của bạn. Khi được nhắc, hãy chọn Sao chép các mục nếu cần.

    5. Để cài đặt SDK Trình điều khiển, hãy kéo tệp GoogleRidesharingDriver.xcframework vào dự án của bạn trong phần Frameworks, Libraries and Embedded Content (Khung, Thư viện và Nội dung được nhúng). Khi được nhắc, hãy chọn Sao chép các mục nếu cần.

    6. Kéo GoogleRidesharingDriver.bundle đã tải xuống vào thư mục cấp cao nhất của dự án Xcode của bạn. Khi được nhắc, hãy chọn Copy items if needed.

    7. Chọn dự án của bạn trên Project Navigator và chọn mục tiêu cho ứng dụng.

    8. Mở thẻ Giai đoạn bản dựng và trong Liên kết nhị phân với thư viện, thêm khung và thư viện sau nếu chưa có:

      • 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
    9. Chọn dự án của bạn chứ không phải mục tiêu cụ thể rồi mở thẻ Build Settings (Cài đặt bản dựng). Trong mục Các cờ trình liên kết khác, hãy thêm ‑ObjC cho cả gỡ lỗi và phát hành. Nếu các chế độ cài đặt này không xuất hiện, hãy thay đổi bộ lọc trong thanh Cài đặt bản dựng từ Cơ bản thành Tất cả.

    Kiểm tra tệp kê khai về quyền riêng tư của Apple

    Apple yêu cầu thông tin chi tiết về quyền riêng tư của ứng dụng đối với các ứng dụng trên App Store. Hãy truy cập trang Thông tin chi tiết về quyền riêng tư trong App Store của Apple để biết thông tin cập nhật và biết thêm thông tin.

    Tệp kê khai về quyền riêng tư của Apple có trong gói tài nguyên cho SDK. Để xác minh rằng Tệp kê khai về quyền riêng tư đã được đưa vào tệp kê khai về quyền riêng tư, cũng như để kiểm tra nội dung trong đó, hãy tạo một bản lưu trữ ứng dụng rồi tạo báo cáo về quyền riêng tư trong kho lưu trữ đó.

    Triển khai hoạt động uỷ quyền và xác thực

    Khi ứng dụng Driver của bạn tạo và gửi bản cập nhật đến phần phụ trợ của Fleet Engine, yêu cầu phải bao gồm mã truy cập hợp lệ. Để uỷ quyền và xác thực các yêu cầu này, SDK trình điều khiển sẽ gọi đối tượng của bạn theo GMTDAuthorization giao thức. Đối tượng chịu trách nhiệm cung cấp mã truy cập cần thiết.

    Là nhà phát triển ứng dụng, bạn sẽ chọn cách tạo mã thông báo. Cách triển khai của bạn sẽ cung cấp khả năng làm những việc sau:

    • Tìm nạp mã truy cập (có thể ở định dạng JSON) từ một máy chủ HTTPS.
    • Phân tích cú pháp và lưu mã thông báo vào bộ nhớ đệm.
    • Làm mới mã thông báo khi mã này hết hạn.

    Để biết thông tin chi tiết về các mã thông báo mà máy chủ Fleet Engine dự kiến, hãy xem Tạo Mã thông báo web JSON (JWT) để uỷ quyền.

    Mã nhà cung cấp giống với mã dự án trên Google Cloud. Xem Hướng dẫn sử dụng API phân phối Fleet Engine để biết thêm thông tin.

    Ví dụ sau đây triển khai một trình cung cấp mã truy cập:

    #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
    

    Tạo một thực thể DeliveryDriverAPI

    Để nhận một phiên bản GMTDDeliveryVehicleReporter, trước tiên, bạn cần tạo một Thực thể GMTDDeliveryDriverAPI sử dụng providerID, xeID, driveContext và accessTokenProvider. providerID giống với Mã dự án trên Google Cloud. Ngoài ra, bạn có thể truy cập vào GMTDDeliveryVehicleReporter thực thể trực tiếp từ API trình điều khiển.

    Ví dụ sau đây sẽ tạo một thực thể 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];
    }
    

    Tuỳ ý nghe các sự kiện VehicleReporter (Trình báo cáo xe)

    GMTDDeliveryVehicleReporter cập nhật xe định kỳ khi locationTrackingEnabled là CÓ. Để phản hồi những bản cập nhật định kỳ này, bất kỳ có thể đăng ký các sự kiện GMTDDeliveryVehicleReporter bằng cách tuân thủ giao thức GMTDVehicleReporterListener.

    Bạn có thể xử lý các sự kiện sau:

    • vehicleReporter:didSucceedVehicleUpdate

      Thông báo cho ứng dụng Driver rằng các dịch vụ phụ trợ đã nhận được thông tin cập nhật về trạng thái và vị trí của xe.

    • vehicleReporter:didFailVehicleUpdate:withError

      Thông báo cho người nghe biết rằng không cập nhật được xe. Miễn là vị trí đã bật tính năng theo dõi, GMTDDeliveryVehicleReporter sẽ tiếp tục gửi dữ liệu mới nhất cho phần phụ trợ của Fleet Engine.

    Ví dụ sau đây xử lý các sự kiện này:

    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
    

    Bật tính năng theo dõi vị trí

    Để bật tính năng theo dõi vị trí, ứng dụng của bạn có thể đặt locationTrackingEnabled thành YES vào GMTDDeliveryVehicleReporter. Khi đó, GMTDDeliveryVehicleReporter sẽ = tự động gửi thông tin cập nhật về vị trí. Khi GMSNavigator đang điều hướng (khi một điểm đến được đặt thông qua setDestinations) và locationTrackingEnabled được đặt thành YES, GMTDDeliveryVehicleReporter sẽ đồng thời cũng tự động gửi thông tin cập nhật về tuyến đường và giờ đến dự kiến.

    Tuyến đường được thiết lập trong các lần cập nhật đó sẽ giống với tuyến đường của người lái xe di chuyển đến trong phiên điều hướng. Do đó, để tính năng theo dõi lô hàng hoạt động đúng cách, điểm tham chiếu được đặt qua -setDestinations:callback: phải khớp với đích đến được thiết lập trong phần phụ trợ Fleet Engine.

    Ví dụ sau đây sẽ bật tính năng theo dõi vị trí:

    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
    

    Theo mặc định, khoảng thời gian báo cáo là 10 giây, nhưng khoảng thời gian báo cáo có thể sẽ được thay đổi bằng locationUpdateInterval. Khoảng thời gian tối thiểu được hỗ trợ giữa những lần cập nhật là 5 giây. Khoảng thời gian tối đa được hỗ trợ cho một lần cập nhật là 60 giây. Thường xuyên hơn thì các bản cập nhật có thể dẫn đến yêu cầu và lỗi chậm hơn.

    Tắt tính năng cập nhật vị trí

    Ứng dụng của bạn có thể tắt tính năng cập nhật vị trí cho xe. Ví dụ: khi một kết thúc ca làm việc của người lái xe, ứng dụng của bạn có thể đặt locationTrackingEnabled thành NO.

      _vehicleReporter.locationTrackingEnabled = NO
    

    Xử lý lỗi update_mask

    Khi GMTDDeliveryVehicleReporter gửi thông tin cập nhật về xe, update_mask có thể xảy ra khi mặt nạ trống và thường xảy ra đối với lần đầu tiên cập nhật sau khi khởi động. Ví dụ sau đây trình bày cách xử lý lỗi này:

    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